@across-protocol/app-sdk - npm Package Compare versions

Comparing version 0.0.2 to 0.0.3

package.json

 {
   "name": "@across-protocol/app-sdk",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "main": "./dist/index.mjs",
@@ -64,3 +64,3 @@ "module": "./dist/index.mjs",
     "check-exports": "attw --pack . --ignore-rules=cjs-resolves-to-esm",
-    "test": "vitest run",
+    "test": "vitest run --reporter=verbose",
     "ci": "pnpm run build && pnpm run check-exports pnpm npm run lint && pnpm run test",
@@ -67,0 +67,0 @@ "typedoc": "typedoc --out docs src/index.ts"

README.md

@@ -41,3 +41,3 @@ <br/>
 
-To get started, install the integrator sdk and its peer dependency [viem](https://viem.sh/).
+To get started, install the app sdk and its peer dependency [viem](https://viem.sh/).
 
@@ -112,8 +112,126 @@ ```bash
 
-## Deposit details
+## Cross-chain message handling
 
-TODO
+Across enables users to seamlessly interact with your dApp or chain using assets from other chains.
 
-## Cross-chain message handling
+### 1. Craft a cross-chain message
 
+To implement this feature, you first need to specify a `crossChainMessage`.
+The example below shows a cross-chain message for staking USDC into a contract deployed
+on Optimism by:
+
+1. Approve USDC to be pulled into staking
+2. Stake approved amount into contract
+
+```ts
+// Example staking contract on Optimism
+const stakingContractAddress = "0x733Debf51574c70CfCdb7918F032E16F686bd9f8";
+// USDC on Optimism
+const usdcAddress = "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85";
+// Example user address
+const userAddress = "0x924a9f036260DdD5808007E1AA95f08eD08aA569a";
+const inputAmount = parseUnits("200", 6);
+
+const crossChainMessage = {
+  // This address will receive the amount of bridged tokens on the destination chain if
+  // one of the cross-chain actions fail. Leftover tokens are here as well if all actions
+  // succeed.
+  fallbackRecipient: userAddress,
+  // List of actions that should be executed on the destination chain
+  actions: [
+    {
+      // Address of target contract on destination chain, i.e. USDC on Optimism
+      target: usdcAddress,
+      // Encoded function data, i.e. calldata for approving USDC to be pulled in by
+      // staking contract
+      callData: generateApproveCallData(
+        stakingContractAddress,
+        inputAmount
+      ),
+      // Native msg.value, can be 0 in the context of USDC
+      value: 0n,
+      // Update call data callback - we need to provide a callback function to
+      // re-generate calldata because it depends on the `outputAmount`, i.e.
+      // `inputAmount` - `relayer fee`. This is the amount the user has available after a
+      // relayer filled the deposit on the destination chain.
+      updateCallData: (outputAmount) => generateApproveCallData(
+        stakingContractAddress,
+        outputAmount
+      )
+    },
+    {
+      // Address of target contract on destination chain, i.e. staking contract
+      // on Optimism
+      target: stakingContractAddress,
+      // Encoded function data, i.e. calldata for staking USDC on behalf of user
+      callData: generateStakeCallData(
+        userAddress,
+        inputAmount
+      )
+      // Native msg.value, can be 0 in the context of USDC
+      value: 0n,
+      // Same reasoning as above in the approve step.
+      updateCallData: (outputAmount) => generateStakeCallData(
+        stakingContractAddress,
+        outputAmount
+      )
+    }
+  ]
+}
+
+function generateApproveCallData(spender: Address, amount: uint256) {
+  const approveCallData = encodeFunctionData({
+    abi: [parseAbiItem("function approve(address spender, uint256 value)")],
+    args: [spender, amount],
+  });
+
+  return approveCallData;
+}
+
+function generateStakeCallData(userAddress: Address, amount: uint256) {
+  return encodeFunctionData({
+    abi: [parseAbiItem("function stake(address stakerAddress, uint256 amount")],
+    args: [userAddress, amount],
+  });
+}
+```
+
+### 2. Retrieve a quote
+
+After specifying a cross-chain message, you simply can fetch a quote the same way as a normal bridge
+
+```ts
+const route = {
+  originChainId: arbitrum.chainId
+  destinationChainId: optimism.chainId,
+  inputToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
+  outputToken: "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
+};
+const quote = await client.getQuote({
+  route,
+  inputAmount,
+  crossChainMessage // crated above
+});
+```
+
+### 3. Execute a quote
+
+If the quote is available, you can execute like so
+
+```ts
+import { useWalletClient } from "wagmi";
+
+const wallet = useWalletClient();
+
+await client.executeQuote({
+  walletClient: wallet,
+  deposit: quote.deposit, // returned by `getQuote`
+  onProgress: (progress) => {
+    // handle progress
+  },
+});
+```
+
+## Deposit details
+
 TODO
@@ -120,0 +238,0 @@

No alert changes

Improved metrics

Total package byte prevSize

168684

increased by3.15%

Lines of code

2861

increased by0.95%

Number of lines in readme file

289

increased by69.01%

No dependency changes