Allow once-off sponsored transactions

.github/workflows/deploy-preview.yaml

@@ -20,6 +20,19 @@ jobs:
             github.event.pull_request.head.repo.full_name != github.repository &&
             github.event.action == 'opened'
         steps:
+            - name: Check branch name prefix (for external PRs)
+              env:
+                USER_NAME: ${{ github.event.pull_request.user.login }}
+                BRANCH_NAME: ${{ github.event.pull_request.head.ref }}
+              run: |
+                PREFIX="${BRANCH_NAME%%/*}"
+                lower_user_name="${USER_NAME,,}"
+                lower_prefix="${PREFIX,,}"
+                if [[ "$lower_prefix" != "$lower_user_name" ]]; then
+                    echo "Invalid branch name. Please ensure that your PR branch name starts with your GitHub username in the format of <username>/<branch-name>. Eg. myusername/my-feature"
+                    exit 1
+                fi
+
             - name: Comment on external PR
               uses: peter-evans/create-or-update-comment@71345be0265236311c031f5c7866368bd1eff043 # v4.0.0
               with:
@@ -28,7 +41,7 @@ jobs:
                       ## 👋 Thanks for your contribution!
 
                       Since this PR comes from a forked repository, preview deployment requires approval from a maintainer for security reasons.
-                      Please ensure that your PR is coming from a meaningful branch name. Eg. feature/my-feature **not main**
+                      Please ensure that your PR branch name starts with your GitHub username in the format of <username>/<branch-name>. Eg. myusername/my-feature **not main**
 
                       **Next steps:**
                       1. A maintainer will review your code
@@ -56,6 +69,19 @@ jobs:
             AWS_REGION: eu-west-1
             BRANCH_NAME: ${{ github.event.pull_request.head.ref }}
         steps:
+            - name: Check branch name prefix (for external PRs)
+              if: github.event.pull_request.head.repo.full_name != github.repository
+              env:
+                USER_NAME: ${{ github.event.pull_request.user.login }}
+              run: |
+                PREFIX="${BRANCH_NAME%%/*}"
+                lower_user_name="${USER_NAME,,}"
+                lower_prefix="${PREFIX,,}"
+                if [[ "$lower_prefix" != "$lower_user_name" ]]; then
+                    echo "Invalid branch name. Please ensure that your PR branch name starts with your GitHub username in the format of <username>/<branch-name>. Eg. myusername/my-feature"
+                    exit 1
+                fi
+
             - name: Checkout
               uses: actions/checkout@v4
               with:
@@ -97,10 +123,18 @@ jobs:
               run: |
                   AWS_MAX_ATTEMPTS=10 aws cloudfront create-invalidation --distribution-id ${{ secrets.AWS_PREVIEW_CLOUDFRONT_DISTRIBUTION_ID }} --paths '/' '/*'
 
+            - name: Find Comment
+              uses: peter-evans/find-comment@b30e6a3c0ed37e7c023ccd3f1db5c6c0b0c23aad # v4.0.0
+              id: find-comment
+              with:
+                  issue-number: ${{ github.event.pull_request.number }}
+                  comment-author: 'github-actions[bot]'
+                  body-includes: 🚀 Preview environment deployed!
+
             - name: Create Deployment Comment
-              if: github.event.action == 'opened' || github.event.action == 'reopened' || github.event.pull_request.draft == true
               uses: peter-evans/create-or-update-comment@71345be0265236311c031f5c7866368bd1eff043 # v4.0.0
               with:
+                  comment-id: ${{ steps.find-comment.outputs.comment-id }}
                   issue-number: ${{ github.event.pull_request.number }}
                   body: |
                       # 🚀 Preview environment deployed!

.github/workflows/destroy-preview-env.yaml

@@ -1,7 +1,7 @@
 name: Destroy Preview Environment
 
 on:
-  pull_request:
+  pull_request_target:
     branches:
       - main
     paths: ['examples/homepage/**', 'packages/vechain-kit/**', 'yarn.lock']
@@ -16,9 +16,26 @@ jobs:
       id-token: write
       pull-requests: write
     runs-on: ubuntu-latest
-    env:
-      BRANCH_NAME: ${{ github.event.pull_request.head.ref }}
     steps:
+      - name: Find Previous Deployment Comment
+        uses: peter-evans/find-comment@3eae4d37986fb5a8592848f6a574fdf654e61f9e # v3.1.0
+        id: find-comment
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          comment-author: 'github-actions[bot]'
+          body-includes: '🚀 Preview environment deployed!'
+
+      - name: Remove Deployment PR Comment
+        run: |
+          if [[ -z "${COMMENT_ID}" ]]; then
+            echo "No deployment comment found. Please ensure that the preview environment was deployed before destroying it."
+            exit 1
+          fi
+          gh api --method DELETE /repos/${{ github.repository }}/issues/comments/${COMMENT_ID}
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COMMENT_ID: ${{ steps.find-comment.outputs.comment-id }}
+
       - name: Configure AWS credentials
         uses: aws-actions/configure-aws-credentials@7474bc4690e29a8392af63c5b98e7449536d5c3a # v4
         with:
@@ -36,16 +53,3 @@ jobs:
       - name: Remove Preview Environment from S3
         run: |
           aws s3 rm s3://${{ secrets.AWS_PREVIEW_BUCKET_NAME }}/${{ steps.process-branch-name.outputs.processedBranchName }} --recursive
-
-      - name: Find Previous Deployment Comment
-        uses: peter-evans/find-comment@3eae4d37986fb5a8592848f6a574fdf654e61f9e # v3.1.0
-        id: find-comment
-        with:
-          issue-number: ${{ github.event.pull_request.number }}
-          comment-author: 'github-actions[bot]'
-          body-includes: '🚀 Preview environment deployed!'
-
-      - name: Remove Deployment PR Comment
-        run: gh api --method DELETE /repos/${{ github.repository }}/issues/comments/${{ steps.find-comment.outputs.comment-id }}
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

examples/next-template/src/app/components/features/TransactionExamples/TransactionExamples.tsx

@@ -45,6 +45,26 @@ export function TransactionExamples() {
         suggestedMaxGas: undefined,
     });
 
+    const buildTransactionWithDAppSponsored = useBuildTransaction({
+        clauseBuilder: () => {
+            if (!account?.address) return [];
+
+            return [
+                {
+                    ...thor.contracts
+                        .load(b3trMainnetAddress, IB3TR__factory.abi)
+                        .clause.transfer(account.address, BigInt('0')).clause,
+                    comment: `This is a dummy transaction to test the transaction modal. Confirm to transfer 0 B3TR to ${account?.address}`,
+                },
+            ];
+        },
+        refetchQueryKeys: [],
+        onSuccess: () => {},
+        onFailure: () => {},
+        suggestedMaxGas: undefined,
+        // dAppSponsoredUrl: "", <--- YOUR DELEGATOR URL HERE
+    });
+
     const {
         open: openTransactionModal,
         close: closeTransactionModal,
@@ -64,14 +84,19 @@ export function TransactionExamples() {
 
     const handleTransactionWithModal = useCallback(async () => {
         openTransactionModal();
-        await sendTransaction({});
-    }, [sendTransaction, openTransactionModal]);
+        await (buildTransactionWithDAppSponsored.sendTransaction({}));
+    }, [buildTransactionWithDAppSponsored, openTransactionModal]);
 
     const handleTryAgain = useCallback(async () => {
         resetStatus();
         await sendTransaction({});
     }, [sendTransaction, resetStatus]);
 
+    const handleTryAgainWithSponsoredModal = useCallback(async () => {
+        buildTransactionWithDAppSponsored.resetStatus();
+        await buildTransactionWithDAppSponsored.sendTransaction({});
+    }, [buildTransactionWithDAppSponsored]);
+
     return (
         <>
             <Box>
@@ -89,8 +114,8 @@ export function TransactionExamples() {
                     </Button>
                     <Button
                         onClick={handleTransactionWithModal}
-                        isLoading={isTransactionPending}
-                        isDisabled={isTransactionPending}
+                        isLoading={buildTransactionWithDAppSponsored.isTransactionPending ?? isTransactionPending}
+                        isDisabled={buildTransactionWithDAppSponsored.isTransactionPending ?? isTransactionPending}
                         data-testid="tx-with-modal-button"
                     >
                         Tx with modal
@@ -113,12 +138,12 @@ export function TransactionExamples() {
             <TransactionModal
                 isOpen={isTransactionModalOpen}
                 onClose={closeTransactionModal}
-                status={status}
-                txReceipt={txReceipt}
-                txError={error}
-                onTryAgain={handleTryAgain}
+                status={buildTransactionWithDAppSponsored.status ?? status}
+                txReceipt={buildTransactionWithDAppSponsored.txReceipt ?? txReceipt}
+                txError={buildTransactionWithDAppSponsored.error ?? error}
+                onTryAgain={handleTryAgainWithSponsoredModal ?? handleTryAgain}
                 uiConfig={{
-                    title: 'Test Transaction',
+                    title: 'Test Transaction with DApp Sponsored',
                     description: `This is a dummy transaction to test the transaction modal. Confirm to transfer 0 B3TR to ${humanAddress(
                         account?.address ?? '',
                     )}`,

packages/vechain-kit/src/hooks/thor/transactions/useBuildTransaction.ts

@@ -12,6 +12,7 @@ export type BuildTransactionProps<ClausesParams> = {
     suggestedMaxGas?: number;
     gasPadding?: number;
     onFailure?: () => void;
+    dAppSponsoredUrl?: string;
 };
 
 /**
@@ -23,6 +24,7 @@ export type BuildTransactionProps<ClausesParams> = {
  * @param onFailure - An optional callback function to be called after the transaction is failed or cancelled.
  * @param suggestedMaxGas - The suggested maximum gas for the transaction.
  * @param gasPadding - The padding to add to the suggested maximum gas.
+ * @param dAppSponsoredUrl - The dApp sponsored delegator url.
  * @returns An object containing the result of the `useSendTransaction` hook and a `sendTransaction` function.
  */
 export const useBuildTransaction = <ClausesParams>({
@@ -33,6 +35,7 @@ export const useBuildTransaction = <ClausesParams>({
     onFailure,
     suggestedMaxGas,
     gasPadding,
+    dAppSponsoredUrl,
 }: BuildTransactionProps<ClausesParams>) => {
     const { account } = useWallet();
     const queryClient = useQueryClient();
@@ -62,6 +65,7 @@ export const useBuildTransaction = <ClausesParams>({
         suggestedMaxGas,
         onTxFailedOrCancelled: onFailure,
         gasPadding,
+        dAppSponsoredUrl,
     });
 
     /**
@@ -70,9 +74,9 @@ export const useBuildTransaction = <ClausesParams>({
      */
     const sendTransaction = useCallback(
         async (props: ClausesParams) => {
-            result.sendTransaction(clauseBuilder(props));
+            result.sendTransaction(clauseBuilder(props), dAppSponsoredUrl);
         },
-        [clauseBuilder, result],
+        [clauseBuilder, result, dAppSponsoredUrl],
     );
 
     return { ...result, sendTransaction };

packages/vechain-kit/src/hooks/thor/transactions/useSendTransaction.ts

@@ -21,6 +21,7 @@ import { Revision, TransactionClause } from '@vechain/sdk-core';
  * @param suggestedMaxGas the suggested max gas for the transaction
  * @param privyUIOptions options to pass to the Privy UI
  * @param gasPadding the gas padding to use for the transaction (Eg. 0.1 for 10%)
+ * @param dAppSponsoredUrl the dApp sponsored delegator url.
  */
 type UseSendTransactionProps = {
     signerAccountAddress?: string | null;
@@ -34,6 +35,7 @@ type UseSendTransactionProps = {
         buttonText?: string;
     };
     gasPadding?: number;
+    dAppSponsoredUrl?: string;
 };
 
 /**
@@ -47,7 +49,15 @@ type UseSendTransactionProps = {
  * @param error error that occurred while sending the transaction
  */
 export type UseSendTransactionReturnValue = {
-    sendTransaction: (clauses?: TransactionClause[]) => Promise<void>;
+    sendTransaction: (
+        clauses?: TransactionClause[],
+        dAppSponsoredUrl?: string,
+        privyUIOptions?: {
+            title?: string;
+            description?: string;
+            buttonText?: string;
+        },
+    ) => Promise<void>;
     isTransactionPending: boolean;
     isWaitingForWalletConfirmation: boolean;
     txReceipt: TransactionReceipt | null;
@@ -88,6 +98,7 @@ export type UseSendTransactionReturnValue = {
  * @param suggestedMaxGas the suggested max gas for the transaction
  * @param privyUIOptions options to pass to the Privy UI
  * @param gasPadding the gas padding to use for the transaction (Eg. 0.1 for 10%)
+ * @param dAppSponsoredUrl the dApp sponsored delegator url.
  * @returns see {@link UseSendTransactionReturnValue}
  */
 export const useSendTransaction = ({
@@ -98,6 +109,7 @@ export const useSendTransaction = ({
     suggestedMaxGas,
     privyUIOptions,
     gasPadding,
+    dAppSponsoredUrl,
 }: UseSendTransactionProps): UseSendTransactionReturnValue => {
     const thor = useThor();
     const { signer } = useDAppKitWallet();
@@ -117,7 +129,8 @@ export const useSendTransaction = ({
                 | TransactionClause[]
                 | (() => TransactionClause[])
                 | (() => Promise<TransactionClause[]>),
-            options?: {
+            dAppSponsoredUrl?: string,
+            privyUIOptions?: {
                 title?: string;
                 description?: string;
                 buttonText?: string;
@@ -129,7 +142,7 @@ export const useSendTransaction = ({
                 return await privyWalletProvider.sendTransaction({
                     txClauses: _clauses,
                     ...privyUIOptions,
-                    ...options,
+                    dAppSponsoredUrl,
                 });
             }
 
@@ -180,6 +193,11 @@ export const useSendTransaction = ({
             nodeUrl,
             privyWalletProvider,
             privyUIOptions,
+            feeDelegation,
+            thor,
+            signer,
+            gasPadding,
+            dAppSponsoredUrl,
         ],
     );
 
@@ -194,14 +212,14 @@ export const useSendTransaction = ({
     >(null);
 
     const sendTransactionAdapter = useCallback(
-        async (_clauses?: TransactionClause[]): Promise<void> => {
+        async (_clauses?: TransactionClause[], _dAppSponsoredUrl?: string): Promise<void> => {
             if (!_clauses && !clauses) throw new Error('clauses are required');
             try {
                 setTxHash(null);
                 setSendTransactionPending(true);
                 setSendTransactionError(null);
                 setError(undefined);
-                const response = await sendTransaction(_clauses ?? [], {
+                const response = await sendTransaction(_clauses ?? [], _dAppSponsoredUrl, {
                     ...privyUIOptions,
                 });
 
@@ -219,7 +237,7 @@ export const useSendTransaction = ({
                 setSendTransactionPending(false);
             }
         },
-        [sendTransaction, clauses, privyUIOptions],
+        [sendTransaction, clauses, privyUIOptions, dAppSponsoredUrl],
     );
 
     /**