@aptos-labs/cross-chain-core 5.8.2 → 6.0.0

package/README.md

@@ -296,6 +296,32 @@ console.log(`Destination TX: ${destinationChainTxnId}`);
 - `originChainTxnId`: Transaction hash on Aptos
 - `destinationChainTxnId`: Transaction hash on the destination chain
 
+### Server-Side Solana Claim (Optional)
+
+When withdrawing USDC from Aptos to Solana, the claim transaction on Solana requires a signature. By default, the user's wallet signs this transaction. However, for a smoother user experience, you can configure a **server-side claim** where your backend signs the Solana claim transaction instead.
+
+**Benefits:**
+- Users only sign once (the Aptos burn transaction)
+- No second wallet popup after the ~60 second attestation wait
+- Seamless one-click withdrawal flow
+
+To enable server-side claiming, configure `serverClaimUrl` in your `solanaConfig`:
+
+```typescript
+const crossChainCore = new CrossChainCore({
+  dappConfig: {
+    aptosNetwork: Network.MAINNET,
+    solanaConfig: {
+      serverClaimUrl: "/api/claim-withdraw", // Your API endpoint
+    },
+  },
+});
+```
+
+When configured, the SDK will automatically POST the attestation receipt to your server endpoint after the Aptos burn transaction is confirmed and attested. Your server then signs and submits the Solana claim transaction using a funded keypair.
+
+📖 **See [SERVERSIDE_SOLANA_SIGNER.md](./SERVERSIDE_SOLANA_SIGNER.md) for complete implementation guide.**
+
 ## Chain ID Mappings
 
 The SDK provides mappings from Ethereum chain IDs to chain configurations:

package/dist/CrossChainCore.d.ts

@@ -3,6 +3,17 @@ import { ChainsConfig, TokenConfig, ChainConfig } from "./config";
 export interface CrossChainDappConfig {
     aptosNetwork: Network;
     disableTelemetry?: boolean;
+    /**
+     * Returns an epoch-second timestamp used as `expireTimestamp` when building
+     * Aptos transactions. Called at transaction-build time so that each
+     * transaction in a multi-step bridge flow gets a fresh expiration window.
+     *
+     * @example
+     * ```ts
+     * getExpireTimestamp: () => Math.floor(Date.now() / 1000) + 120 // 2 minutes
+     * ```
+     */
+    getExpireTimestamp?: () => number;
     solanaConfig?: {
         rpc?: string;
         priorityFeeConfig?: {
@@ -11,12 +22,89 @@ export interface CrossChainDappConfig {
             min?: number;
             max?: number;
         };
+        /**
+         * URL of a server-side API endpoint that claims withdraw transactions on Solana.
+         * When set, the SDK will POST the attested receipt to this URL instead of
+         * asking the user's wallet to sign the claim transaction.
+         *
+         * Expected request body: { serializedReceipt: string, destinationAddress: string, sourceChain: string }
+         * Expected response: { destinationChainTxnId: string }
+         * Check out the SERVERSIDE_SOLANA_SIGNER.md file for more details.
+         *
+         * @example
+         * const crossChainCore = new CrossChainCore({
+         *   dappConfig: {
+         *     aptosNetwork: Network.TESTNET,
+         *     solanaConfig: {
+         *       serverClaimUrl: "/api/claim-withdraw",
+         *     },
+         *   },
+         * });
+         */
+        serverClaimUrl?: string;
+        /**
+         * Solana transaction confirmation commitment level.
+         *
+         * - `"finalized"` (default) — waits for supermajority finalization (~30 s).
+         * - `"confirmed"` — waits for supermajority confirmation (~0.5 s).
+         *
+         * For bridge flows `"confirmed"` is usually sufficient because Wormhole
+         * guardians independently verify finality before issuing attestations.
+         *
+         * @default "finalized"
+         *
+         * @example
+         * const crossChainCore = new CrossChainCore({
+         *   dappConfig: {
+         *     aptosNetwork: Network.MAINNET,
+         *     solanaConfig: {
+         *       commitment: "confirmed", // ~0.5 s vs ~30 s
+         *     },
+         *   },
+         * });
+         */
+        commitment?: "confirmed" | "finalized";
+    };
+    /**
+     * Custom RPC endpoints for EVM chains. When provided, these override the
+     * built-in `defaultRpc` values for balance lookups and Wormhole SDK
+     * initialization.
+     *
+     * @example
+     * ```ts
+     * evmConfig: {
+     *   Ethereum: { rpc: "https://rpc.ankr.com/eth/MY_KEY" },
+     *   Base: { rpc: "https://rpc.ankr.com/base/MY_KEY" },
+     * }
+     * ```
+     */
+    evmConfig?: Partial<Record<EvmChainName, {
+        rpc: string;
+    }>>;
+    /**
+     * Custom RPC endpoint for the Sui chain. When provided, overrides the
+     * built-in `defaultRpc` for balance lookups and Wormhole SDK initialization.
+     *
+     * @example
+     * ```ts
+     * suiConfig: { rpc: "https://fullnode.mainnet.sui.io" }
+     * ```
+     */
+    suiConfig?: {
+        rpc?: string;
     };
 }
 export type { AccountAddressInput } from "@aptos-labs/ts-sdk";
 export { NetworkToChainId, NetworkToNodeAPI } from "@aptos-labs/ts-sdk";
 export type AptosAccount = Account;
 export type Chain = "Solana" | "Ethereum" | "Sepolia" | "Aptos" | "BaseSepolia" | "ArbitrumSepolia" | "Avalanche" | "Base" | "Arbitrum" | "PolygonSepolia" | "Polygon" | "Sui";
+/**
+ * EVM chain names supported by the SDK — derived from {@link Chain} by
+ * excluding the non-EVM ecosystems. Adding a new EVM chain to `Chain`
+ * automatically makes it a valid key in `evmConfig`.
+ */
+export type EvmChainName = Exclude<Chain, "Solana" | "Aptos" | "Sui">;
+export declare const EVM_CHAIN_NAMES: EvmChainName[];
 export declare const EthereumChainIdToTestnetChain: Record<string, ChainConfig>;
 export declare const EthereumChainIdToMainnetChain: Record<string, ChainConfig>;
 export type CCTPProviders = "Wormhole";
@@ -29,6 +117,13 @@ export declare class CrossChainCore {
     readonly _dappConfig: CrossChainDappConfig;
     readonly CHAINS: ChainsConfig;
     readonly TOKENS: Record<string, TokenConfig>;
+    /**
+     * Last known source-chain transaction ID, set by signers immediately after
+     * a transaction is submitted. Acts as a recovery side-channel so that
+     * callers can retrieve the tx hash even when the orchestration layer throws
+     * before returning it (e.g. claim failure after a successful burn).
+     */
+    _lastSourceChainTxId: string | undefined;
     constructor(args: {
         dappConfig: CrossChainDappConfig;
     });

package/dist/CrossChainCore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CrossChainCore.d.ts","sourceRoot":"","sources":["../src/CrossChainCore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAYtD,OAAO,EACL,YAAY,EAKZ,WAAW,EACX,WAAW,EACZ,MAAM,UAAU,CAAC;AAQlB,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,OAAO,CAAC;IACtB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,YAAY,CAAC,EAAE;QACb,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,iBAAiB,CAAC,EAAE;YAClB,UAAU,CAAC,EAAE,MAAM,CAAC;YACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC;YAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;YACb,GAAG,CAAC,EAAE,MAAM,CAAC;SACd,CAAC;KACH,CAAC;CACH;AACD,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACxE,MAAM,MAAM,YAAY,GAAG,OAAO,CAAC;AAGnC,MAAM,MAAM,KAAK,GACb,QAAQ,GACR,UAAU,GACV,SAAS,GACT,OAAO,GACP,aAAa,GACb,iBAAiB,GACjB,WAAW,GACX,MAAM,GACN,UAAU,GACV,gBAAgB,GAChB,SAAS,GACT,KAAK,CAAC;AAGV,eAAO,MAAM,6BAA6B,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAMrE,CAAC;AAGF,eAAO,MAAM,6BAA6B,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAMrE,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC;AAEvC,MAAM,WAAW,kBAAkB,CACjC,aAAa,GAAG,GAAG,EACnB,cAAc,GAAG,GAAG,EACpB,gBAAgB,GAAG,GAAG,EACtB,iBAAiB,GAAG,GAAG,EACvB,gBAAgB,GAAG,GAAG,EACtB,iBAAiB,GAAG,GAAG;IAEvB,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACzD,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC/D,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAChE;AAED,qBAAa,cAAc;IACzB,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAExC;IAEF,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAiB;IAC9C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAiB;gBAEjD,IAAI,EAAE;QAAE,UAAU,EAAE,oBAAoB,CAAA;KAAE;IAWtD,WAAW,CAAC,YAAY,EAAE,aAAa,GAAG,kBAAkB;IAgBtD,oBAAoB,CACxB,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,KAAK,GACjB,OAAO,CAAC,MAAM,CAAC;CA6CnB"}
+{"version":3,"file":"CrossChainCore.d.ts","sourceRoot":"","sources":["../src/CrossChainCore.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -2,5 +2,6 @@ export * from "./CrossChainCore";
 export * from "./config";
 export * from "./providers/wormhole/index";
 export * from "./providers/wormhole/types";
+export * from "./utils/receiptSerialization";
 export { Network } from "@aptos-labs/ts-sdk";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,UAAU,CAAC;AACzB,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,8BAA8B,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC"}