Transaction Prompts

​

Overview

Transaction Prompts give app the option to show users a capsule-managed prompt to manually approve or deny any transaction or message signing events.

This feature is required when interacting with wallets created outside your app, but can also be turned on for all wallets/transactions in your application. We recommend enabling this feature if you prefer not to implement transaction approval/display flows, or if you prefer users to explicitly approve every transaction on an embedded wallet.

​

How it Works

Transaction Prompts are mandatory in the following scenarios

• Wallet Interaction: When a user attempts to sign a message or execute a transaction using their wallet in an application that is different from where the wallet was created.
• Multi-Application Transactions: After a wallet has been used across multiple applications, any subsequent transactions will prompt the user for approval. This ensures that the user is aware of and consents to all interactions involving their wallet, regardless of the application being used.

To turn on Transaction Prompts for all transactions/wallets, enable “Always show transaction prompts” for your API key in the Developer Portal

​

User Interaction

When a transaction or message signing event is initiated, users will see a popup containing the following details:

• Message Details: An encoded string representing the message.

• Transaction Details:
  • From Address: The wallet address initiating the transaction.
  • To Address: The recipient wallet address.
  • Amount: The number of tokens being transferred.
  • Action: The specific action being performed (e.g., token transfer, minting an NFT).
  • Conversion Rates: Relevant exchange rates if applicable.
  • Chain Information: Information about the blockchain being used.

​

Technical Details

​

Transaction Events and Statuses

• On Approval: If the user approves the transaction or no approval is necessary, the signMessage/signTransaction function will return a SuccessfulSignatureRes result, which will contain the signature.
• On Denial or Timeout: If the user denies the transaction or the timeout is reached, a TransactionReviewError will be thrown that includes the transactionReviewUrl that must be handled by the partner implementing the feature.

​

Error Handling

When implementing Transaction Prompts, various errors can arise during the signing process. It’s important to handle these errors gracefully to ensure a smooth user experience. Below are common scenarios and recommended handling strategies:

​

1. Transaction Denied

Description: The user denies the transaction or message signing request.

Error Handling:

try {
    await client.sendTokens(...);
} catch (error) {
    if (error instanceof TransactionReviewDenied) {
        console.warn("The transaction was denied by the user.");
    }
}

​

2. Timeout Reached

Description: The user does not respond to the popup within the configured timeout period. This returns an addition property of transactionReviewUrl and pendingTransactionId

• pendingTransactionId - Can be used in conjunction with the getPendingTransaciton function available via the CoreCapsule class (or WebCapsule, by extension). If it does not exist, that means the user has denied the transaction request.
• transactionReviewUrl - Can be used to open a popup if desired, which will present the user with the sign message / transaction popup.

Error Handling:

try {
    await client.sendTokens(...);
} catch (error) {
    if (error instanceof TransactionReviewTimeout) {
        console.warn("The transaction was denied by the user.");
    }
}

​

Examples

​

Example 1: EVM - Ethers Signer

Basic Tx Send

import { CapsuleEthersSigner } from '@usecapsule/ethers-v6-integration';

const tx = {
  from: capsule.wallets?.[currentWalletId]?.address,
  to: txToAddress,
  value: web3.utils.toWei(txValue, 'gwei'),
  gasLimit: txGasAmount,
  maxPriorityFeePerGas: txMaxPriorityFeePerGas,
  maxFeePerGas: txMaxFeePerGas,
  nonce,
  chainId,
  smartContractAbi,
  smartContractFunctionName,
  smartContractFunctionArgs: smartContractFunctionArgs ? JSON.parse(smartContractFunctionArgs) : [],
  smartContractByteCode,
  type: 2,
};

const provider = new ethers.EtherscanProvider(CHAIN_ID, API_KEY);
const ethersSigner = new CapsuleEthersSigner(capsule, provider, WALLET_ID);
let res;
try {
  res = await ethersSigner.sendTransaction(tx);
} catch (error) {
  console.log(error);
}
console.log('send ethers tx response:\n', res);

Custom timeout

// Create a new instance of CapsuleEthersSigner with custom timeout
const ethersSigner = new CapsuleEthersSigner(capsule, provider, WALLET_ID, TIMEOUT_MS);

​

Example 2: Cosmos - CosmJS Signer

Basic Instantiation with Token Transfer

import Capsule from '@usecapsule/web-sdk';
import { CapsuleProtoSigner } from '@usecapsule/cosmjs-v0-integration';
import { SigningStargateClient } from '@cosmjs/stargate';

// Create a new instance of CapsuleProtoSigner
const protoSigner = new CapsuleProtoSigner(capsule);
const client = await SigningStargateClient.connectWithSigner(COSMOS_TESTNET_RPC, protoSigner);
const fromAddress = protoSigner.address;

try {
    await client.sendTokens(
      fromAddress,
      COSMOS_DEFAULT_TO_ADDRESS,
      [
        {
          denom: 'uatom',
          amount: '808',
        },
      ],
      {
        amount: [
          {
            amount: '1000',
            denom: 'uatom',
          },
        ],
        gas: '200000',
      },
    );
  } catch (error) {
    if (error instanceof TransactionReviewDenied) {
      console.log('Transaction review has been denied by the user');
    }

    if (error instanceof TransactionReviewTimeout) {
      console.log('Transaction review has timed out');
    }

    console.error(error);
  }
}

Custom Timeout

// Create a new instance of CapsuleProtoSigner with custom timeout
const protoSigner = new CapsuleProtoSigner(capsule, undefined, undefined, TIMEOUT_MS);