Detailed Instructions

First, you must select a bridge aggregator that fits your dApp's needs. Popular choices include Socket (formerly Bungee) and LI.FI, which aggregate multiple bridges and DEXs for optimal routes. Evaluate them based on supported chains, fees, and ease of integration. Once chosen, install the necessary package in your project. For a Node.js/JavaScript project using Socket, you would run the installation command.

• Sub-step 1: Install the SDK: Use npm or yarn to add the aggregator's package to your project dependencies.
• Sub-step 2: Import the Module: In your application code, import the core classes or functions from the SDK.
• Sub-step 3: Initialize the Client: Create an instance of the aggregator client, often requiring an API key for higher rate limits.

bashCopy
npm install @socket.tech/socket-sdk

Tip: Always check the official documentation for the latest installation instructions and required API keys, as configurations can change.

Detailed Instructions

With the SDK initialized, you can now fetch routes for a desired cross-chain transfer. This involves specifying the source chain, destination chain, token addresses, and amount. The aggregator will return a list of possible routes from its integrated bridges and DEXs, each with a quote detailing estimated fees, time, and received amount. You must handle this asynchronous call and parse the response to present options to the user.

• Sub-step 1: Define Transfer Parameters: Set the fromChainId (e.g., 1 for Ethereum), toChainId (e.g., 137 for Polygon), fromTokenAddress (e.g., 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 for USDC), toTokenAddress, and fromAmount.
• Sub-step 2: Call the Quote Function: Use the SDK method, such as getRoutes or getQuote, to request data.
• Sub-step 3: Process the Response: Filter and sort the returned routes based on user preferences like lowest cost or fastest speed.

javascriptCopy
const routes = await socketClient.getRoutes({
  fromChainId: 1,
  toChainId: 137,
  fromTokenAddress: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  toTokenAddress: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174', // USDC on Polygon
  fromAmount: '1000000', // 1 USDC (6 decimals)
  userAddress: '0xYourUserAddress'
});

Tip: Always validate the token addresses and chain IDs, as using incorrect ones will result in failed transactions or lost funds.

Detailed Instructions

After the user selects a route, you need to build the transaction. The aggregator SDK provides a method to generate the necessary transaction data (calldata) for the chosen route. This data is what your dApp will send to the user's wallet. Crucially, if the transfer involves an ERC-20 token, the user must approve the aggregator's bridge contract to spend their tokens before the main bridge transaction can proceed. This is a separate, on-chain transaction.

• Sub-step 1: Generate Transaction Data: Call a function like buildTransaction with the selected route ID and user address to get the txn object.
• Sub-step 2: Check Allowance: Query the token contract's allowance function to see if the user has already granted sufficient approval to the bridge contract address.
• Sub-step 3: Execute Approval (if needed): If allowance is insufficient, prompt the user to sign an approval transaction. The SDK often provides a helper method for this.

javascriptCopy
// Build the main bridge transaction
const txnData = await socketClient.buildTransaction({
  route: selectedRoute,
  userAddress: '0xYourUserAddress'
});

// Check and handle approval
const neededAllowance = selectedRoute.approvalData;
if (neededAllowance) {
  // Execute approval transaction via user's wallet
  await walletClient.sendTransaction(neededAllowance);
}

Tip: To improve UX, consider using token approval via ERC-20 permits if the aggregator and chain support it, as it can save gas and a separate transaction.

Detailed Instructions

The final step is to execute the bridge transaction. Using the transaction data from the previous step, you prompt the user to sign and send the transaction via their connected wallet (e.g., MetaMask). Once the transaction is submitted on the source chain, you must monitor its status through the aggregator's status API. The process involves waiting for confirmation on the source chain, the bridge's execution, and finally the receipt of funds on the destination chain. The SDK typically provides a way to poll for status updates using the transaction hash or a unique bridge ID.

• Sub-step 1: Send the Transaction: Use the user's wallet provider (like ethers.js or viem) to send the txnData.
• Sub-step 2: Obtain Transaction Hash: Capture the txHash from the sent transaction for tracking.
• Sub-step 3: Poll for Status: Use a method like getBridgeStatus with the txHash or bridgeId to get updates (e.g., 'PENDING', 'COMPLETED', 'FAILED').
• Sub-step 4: Notify the User: Update your UI based on status changes and notify the user when funds arrive.

javascriptCopy
// Send the bridge transaction
const txHash = await walletClient.sendTransaction(txnData.tx);
console.log('Transaction sent:', txHash);

// Monitor status
const status = await socketClient.getBridgeStatus({ transactionHash: txHash });
// Status object includes fromStatus, toStatus, etc.

Tip: Implement a robust polling mechanism with appropriate intervals and timeouts. Also, listen for real-time webhook events if the aggregator offers them for more efficient status updates.

Detailed Instructions

Before initiating any transaction, you must perform protocol and route verification. This involves checking the security audits, team reputation, and the specific liquidity sources for your chosen path.

• Sub-step 1: Audit Verification: Visit the aggregator's official documentation (e.g., docs.socket.tech or docs.li.fi) and locate their audit reports. Verify the reports are from reputable firms like Quantstamp, Trail of Bits, or OpenZeppelin, and check that findings are resolved.
• Sub-step 2: Route Inspection: When a route is proposed (e.g., USDC from Ethereum to Arbitrum via Hop), click to expand the details. Identify the underlying bridge protocols (like Hop, Across, Stargate) and verify they are legitimate. Be wary of routes using unaudited or obscure bridges.
• Sub-step 3: Contract Address Check: Manually compare the interaction contract address shown in your wallet pop-up against the official list on the aggregator's website. For example, Socket's main Diamond Proxy on Ethereum is 0xc30141B657f4216252dc59Af2e7CdB9D8792e1B0. Never interact with an address not listed.

Tip: Bookmark the official verification pages. For LI.FI, you can check their contract addresses at https://docs.li.fi/smart-contracts/contract-addresses.

Detailed Instructions

This step ensures your wallet hygiene and connection scoping are configured to minimize attack surface. A compromised or overly permissive wallet connection is a primary vector for asset theft.

• Sub-step 1: Use a Dedicated Wallet: Consider using a separate, low-balance hot wallet specifically for bridge interactions. Never connect a wallet holding your entire portfolio or private keys to a new dApp. Use hardware wallet integration for significant sums.
• Sub-step 2: Review Connection Permissions: When connecting your wallet (e.g., MetaMask), reject requests for excessive permissions. The aggregator should only request to view your address and suggest transactions. It should never ask for your private key, seed phrase, or permission to 'unlimited' spending on all tokens.
• Sub-step 3: Check for Impersonators: Always access the aggregator via its official URL (e.g., https://app.socket.tech or https://li.fi). Double-check the domain for typos (e.g., s0cket.tech). Use a bookmark instead of search engine links to avoid phishing sites.

Tip: Regularly review and revoke unused wallet connections using a tool like Revoke.cash (https://revoke.cash) to remove old token approvals granted to bridge contracts.

Detailed Instructions

Transaction simulation and parameter validation are critical to avoid unexpected outcomes like excessive slippage, wrong destination address, or hidden fees.

• Sub-step 1: Run a Test Transaction: If transferring a large amount, first send a small, test amount (e.g., $10 worth) to verify the entire flow works as expected, including receipt on the destination chain.
• Sub-step 2: Decode and Inspect Calldata: Advanced users should inspect the transaction calldata before signing. For example, a swapAndBridge call on Socket will contain encoded data for multiple protocols. While complex, look for the destination chain ID and recipient address.

jsonCopy
// Example snippet from a transaction calldata structure
{
  "target": "0xc301...1B0",
  "data": "0x...", // Encoded function call
  "chainId": 42161 // Destination: Arbitrum
}

• Sub-step 3: Final Wallet Pop-up Scrutiny: In your wallet's final confirmation screen, verify: 1) The To: contract address matches the official aggregator contract, 2) The estimated gas fee is reasonable, 3) The Max Slippage setting (e.g., 0.5%) is acceptable, and 4) The estimated Minimum Received amount on the destination chain.

Tip: Use a blockchain explorer like Tenderly (https://tenderly.co) to simulate the exact transaction before broadcasting it, checking for potential reverts or errors.

Detailed Instructions

After broadcasting the transaction, active monitoring and portfolio management are required to confirm success and maintain security.

• Sub-step 1: Track with Explorer and Aggregator: Use the transaction hash to monitor progress on a block explorer (Etherscan, Arbiscan). Simultaneously, use the aggregator's built-in tracking page (e.g., LI.FI's transfer history). The aggregator's status (e.g., Source Done, Destination Pending) is often more detailed for cross-chain actions.
• Sub-step 2: Verify Destination Receipt: Confirm the funds have arrived in the correct wallet on the destination chain. Do not rely solely on the aggregator's UI; check your wallet balance on the destination network directly or via the destination chain's block explorer.
• Sub-step 3: Revoke Unnecessary Approvals: After the bridge is complete, if you do not plan to use the same aggregator/bridge path again soon, revoke the token approval you granted. For example, if you bridged USDC, you gave the bridge contract an allowance. Revoke it to zero using the aggregator's own 'Revoke' feature or a site like Revoke.cash.

Tip: Bookmark the aggregator's support or helpdesk channel (e.g., Discord) with your transaction hash ready. In case of a stall, you can quickly seek help from their team to investigate.