@fastxyz/allset-sdk 0.1.12 → 1.0.1

package/README.md

@@ -1,384 +1,440 @@
-# AllSet SDK
+# @fastxyz/allset-sdk
 
-Bridge tokens between Fast network and EVM chains.
+AllSet SDK for bridging tokens between [Fast network](https://fast.xyz) and EVM chains.
 
-| Entrypoint | Use Case |
-|------------|----------|
-| `@fastxyz/allset-sdk` | Pure helpers (deposit planning, intent builders) |
-| `@fastxyz/allset-sdk/node` | Full bridge execution (deposits, withdrawals) |
-| `@fastxyz/allset-sdk/browser` | Browser-safe pure helpers |
+- **EVM → Fast (deposit):** `executeDeposit()`
+- **Fast → EVM (withdrawal):** `executeWithdraw()` or `executeIntent()` + intent builders
+- **Pure helpers:** `buildDepositTransaction()`, intent builders, address utils — browser-safe
 
-## Install
+**Design:** All functions are pure — no embedded chain config, no file system access, no environment variable reads. The caller provides all addresses, URLs, and credentials.
 
-For node bridge execution and pure helpers only:
+---
 
-```bash
-npm install @fastxyz/allset-sdk
-```
+## Use Cases
 
-Install [`@fastxyz/sdk`](https://github.com/fastxyz/fast-sdk) only for FastWallet-backed flows such as `sendToExternal(...)` and `executeIntent(...)`:
+- Bridge tokens from EVM to Fast network (deposit / EVM → Fast)
+- Bridge tokens from Fast to EVM (withdrawal / Fast → EVM)
+- Execute custom intents on EVM via AllSet bridge
+- Build or plan deposit transactions (pure, browser-safe helpers)
+- Set up EVM wallets for bridging
 
-```bash
-npm install @fastxyz/allset-sdk @fastxyz/sdk
-```
+**Out of scope:** Fast-only operations (balance, send, sign) → [`@fastxyz/sdk`](../fast-sdk) · EVM-only operations without bridging · Swaps, lending, or staking
 
-## Quick Start
+All functions are exported from a single root entrypoint — no sub-paths:
 
 ```ts
-import { FastProvider, FastWallet } from '@fastxyz/sdk';
-import { AllSetProvider, createEvmWallet, createEvmExecutor } from '@fastxyz/allset-sdk/node';
-
-// 1. Setup providers and wallets
-const fastProvider = new FastProvider({ network: 'testnet' });
-const allset = new AllSetProvider({ network: 'testnet' });
-const fastWallet = await FastWallet.fromKeyfile('~/.fast/keys/default.json', fastProvider);
-const evmAccount = createEvmWallet('~/.evm/keys/default.json');
-const evmClients = createEvmExecutor(evmAccount, 'https://sepolia-rollup.arbitrum.io/rpc', 421614);
-
-// 2. Deposit: EVM → Fast
-await allset.sendToFast({
-  chain: 'arbitrum-sepolia',
-  token: 'USDC',
-  amount: '1000000',
-  from: evmAccount.address,
-  to: fastWallet.address,
-  evmClients,
-});
-
-// 3. Withdraw: Fast → EVM
-await allset.sendToExternal({
-  chain: 'arbitrum-sepolia',
-  token: 'USDC',
-  amount: '1000000',
-  from: fastWallet.address,
-  to: evmAccount.address,
-  fastWallet,
-});
+import { ... } from '@fastxyz/allset-sdk';
 ```
 
 ---
 
-## AllSetProvider Setup
+## Installation
 
-AllSetProvider connects to AllSet bridge infrastructure.
+```bash
+npm install @fastxyz/allset-sdk
+# or
+pnpm add @fastxyz/allset-sdk
+```
 
-### Default (testnet)
+`viem` is installed as a package dependency and is also useful directly in consumer code when you need chain objects or wallet helpers.
 
-```ts
-import { AllSetProvider } from '@fastxyz/allset-sdk/node';
+---
 
-const allset = new AllSetProvider();
-```
+## Workflows
 
-### Specify Network
+### Deposit (EVM → Fast)
 
 ```ts
-const allset = new AllSetProvider({ network: 'testnet' });
-// or when available:
-const allset = new AllSetProvider({ network: 'mainnet' });
+import { createEvmWallet, createEvmExecutor, executeDeposit } from '@fastxyz/allset-sdk';
+
+const account = createEvmWallet('0xYourPrivateKey');
+const evmClients = createEvmExecutor(account, 'https://your-evm-rpc...', 421614);
+
+const result = await executeDeposit({
+  chainId: 421614,
+  bridgeContract: '0xb536...', // AllSet bridge contract on Arbitrum Sepolia
+  tokenAddress: '0x75fa...', // USDC on Arbitrum Sepolia
+  amount: '1000000', // 1 USDC (6 decimals)
+  senderAddress: account.address,
+  receiverAddress: 'fast1abc...', // your Fast address
+  evmClients,
+});
+
+console.log(result.txHash); // EVM transaction hash
 ```
 
-### Custom Config
+### Smart Deposit via EIP-7702 (EVM → Fast, gasless)
+
+Gas is paid in the deposit token (USDC) — no ETH required.
 
 ```ts
-const allset = new AllSetProvider({
-  configPath: './my-networks.json',
-  crossSignUrl: 'https://custom.cross-sign.example.com',
-});
-```
+import { smartDeposit, encodeDepositCalldata, fastAddressToBytes32, InsufficientBalanceError } from '@fastxyz/allset-sdk';
 
-### Provider Options
+const receiverBytes32 = fastAddressToBytes32('fast1abc...');
+const depositCalldata = encodeDepositCalldata({
+  tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC on Base
+  amount: 1_000n, // 0.001 USDC
+  receiverBytes32,
+});
 
-```ts
-interface AllSetProviderOptions {
-  network?: 'testnet' | 'mainnet';
-  configPath?: string;      // Custom config file path
-  crossSignUrl?: string;    // Override cross-sign endpoint
+try {
+  const result = await smartDeposit({
+    privateKey: '0xYourPrivateKey',
+    rpcUrl: 'https://base-rpc...',
+    allsetApiUrl: 'https://allset.fast.xyz/api',
+    tokenAddress: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+    amount: 1_000n,
+    bridgeAddress: '0x8677EdAA374b7A47ff0093947AABE4aCbB2D4538',
+    depositCalldata,
+  });
+
+  console.log(result.txHash); // on-chain transaction hash
+  console.log(result.userOpHash); // ERC-4337 UserOperation hash
+} catch (err) {
+  if (err instanceof InsufficientBalanceError) {
+    console.error(`Need ${err.required}, have ${err.balance}`);
+  }
 }
 ```
 
-### Network Config Resolution Order
+### Withdrawal (Fast → EVM)
 
-1. Custom `configPath` (if provided, highest priority)
-2. `~/.allset/networks.json` (user override)
-3. Bundled defaults from `src/default-config.ts`
-
----
+```ts
+import { Signer, FastProvider } from '@fastxyz/sdk';
+import { executeWithdraw } from '@fastxyz/allset-sdk';
+
+const signer = new Signer('0xYourPrivateKey');
+const provider = new FastProvider({ rpcUrl: 'https://your-fast-rpc...' });
+
+const result = await executeWithdraw({
+  fastBridgeAddress: 'fast1bridge...',
+  relayerUrl: 'https://relayer.allset...',
+  crossSignUrl: 'https://cross-sign.allset...',
+  tokenEvmAddress: '0x75fa...',
+  tokenFastTokenId: 'abc123...', // hex token ID on Fast network (no 0x)
+  amount: '1000000',
+  receiverEvmAddress: '0xReceiverEVM...',
+  networkId: 'fast:testnet', // or 'fast:mainnet'
+  signer,
+  provider,
+});
 
-## Fast Wallet Setup
+console.log(result.txHash);
+```
 
-Fast wallet is required for withdrawals (Fast → EVM).
+### Withdrawal with custom intents
 
 ```ts
-import { FastProvider, FastWallet } from '@fastxyz/sdk';
-
-const fastProvider = new FastProvider({ network: 'testnet' });
-const fastWallet = await FastWallet.fromKeyfile('~/.fast/keys/default.json', fastProvider);
+import { Signer, FastProvider } from '@fastxyz/sdk';
+import { executeIntent, buildTransferIntent } from '@fastxyz/allset-sdk';
+
+const signer = new Signer('0xYourPrivateKey');
+const provider = new FastProvider({ rpcUrl: 'https://...' });
+
+const result = await executeIntent({
+  fastBridgeAddress: 'fast1bridge...',
+  relayerUrl: 'https://relayer.allset...',
+  crossSignUrl: 'https://cross-sign.allset...',
+  tokenEvmAddress: '0x75fa...',
+  tokenFastTokenId: 'abc123...',
+  amount: '1000000',
+  intents: [buildTransferIntent('0x75fa...', '0xReceiverEVM...')],
+  networkId: 'fast:testnet',
+  signer,
+  provider,
+});
 ```
 
-See [`@fastxyz/sdk` documentation](https://github.com/fastxyz/fast-sdk) for wallet setup details.
-
 ---
 
-## EVM Wallet Setup
+## API Reference
 
-EVM wallet is required for deposits (EVM → Fast).
+### Wallet & Clients
 
-### Generate New Wallet
+#### `createEvmWallet(privateKey?): EvmAccount`
 
-```ts
-import { createEvmWallet } from '@fastxyz/allset-sdk/node';
+Creates an EVM wallet. Generates a new random wallet if `privateKey` is omitted.
 
-const account = createEvmWallet();
-console.log('Address:', account.address);
-console.log('Private Key:', account.privateKey);  // Save this!
+```ts
+const account = createEvmWallet(); // random
+const account = createEvmWallet('0xabc123...'); // from existing key
+// account.privateKey — hex key (persist to reuse)
+// account.address    — 0x address
 ```
 
-### From Private Key
+#### `createEvmExecutor(account, rpcUrl, chainId): EvmClients`
+
+Creates viem `walletClient` and `publicClient` for the given chain.
 
 ```ts
-const account = createEvmWallet('0x1234...64hexchars');
-// or without 0x prefix
-const account = createEvmWallet('1234...64hexchars');
+const { walletClient, publicClient } = createEvmExecutor(account, rpcUrl, 421614);
 ```
 
-### From Keyfile
+Supported chain IDs: `1` (Ethereum), `11155111` (Sepolia), `421614` (Arbitrum Sepolia), `42161` (Arbitrum), `8453` (Base).
 
-```ts
-const account = createEvmWallet('~/.evm/keys/default.json');
-```
+---
 
-**Keyfile format:**
-```json
-{
-  "privateKey": "abc123...64hexchars",
-  "address": "0x..."
-}
-```
+### Bridge Execution
 
-### Create EVM Executor
+#### `executeDeposit(params): Promise<BridgeResult>`
 
-EVM executor provides viem clients for blockchain operations:
+Executes an EVM → Fast deposit. For ERC-20 tokens, automatically submits an `approve` transaction if the current allowance is insufficient.
+
+> **Note:** `isNative` is only for native EVM assets (ETH). All ERC-20 tokens (including USDC, USDT, etc.) use `tokenAddress` and `isNative: false` (the default). Do not set `isNative: true` for ERC-20 tokens.
 
 ```ts
-import { createEvmExecutor } from '@fastxyz/allset-sdk/node';
-
-const evmClients = createEvmExecutor(
-  account,                                    // From createEvmWallet()
-  'https://sepolia-rollup.arbitrum.io/rpc',  // RPC URL
-  421614                                      // Chain ID
-);
-// Returns { walletClient, publicClient }
+interface ExecuteDepositParams {
+  chainId: number;
+  bridgeContract: `0x${string}`;
+  tokenAddress: `0x${string}`; // ERC-20 contract address (or zero address for native ETH when isNative=true)
+  isNative?: boolean; // true only for native ETH deposits; false (default) for all ERC-20 tokens
+  amount: string; // smallest units as string
+  senderAddress: string;
+  receiverAddress: string; // Fast bech32m address (fast1...)
+  evmClients: EvmClients;
+}
 ```
 
-### EVM Wallet Resolution
-
-`createEvmWallet(keyOrPath?)` resolves the parameter as:
-1. Omitted → Generate new random wallet
-2. Starts with `0x` or 64 hex chars → Derive from private key
-3. Contains `/`, `~`, or ends with `.json` → Load from keyfile
+#### `executeWithdraw(params): Promise<BridgeResult>`
 
-### viem Interoperability
-
-`createEvmWallet()` returns a standard viem account (from `privateKeyToAccount`), so it's **fully interoperable**:
+Executes a simple Fast → EVM token withdrawal. Automatically builds a `DynamicTransfer` intent for the given receiver address.
 
 ```ts
-import { privateKeyToAccount } from 'viem/accounts';
-
-// These are equivalent:
-const account1 = createEvmWallet('0xabc123...');
-const account2 = privateKeyToAccount('0xabc123...');
-
-// Both work with createEvmExecutor:
-createEvmExecutor(account1, rpcUrl, chainId);
-createEvmExecutor(account2, rpcUrl, chainId);
+interface ExecuteWithdrawParams {
+  fastBridgeAddress: string;
+  relayerUrl: string;
+  crossSignUrl: string;
+  tokenEvmAddress: string;
+  tokenFastTokenId: string; // hex, no 0x prefix
+  amount: string;
+  receiverEvmAddress: string; // EVM address to receive tokens
+  deadlineSeconds?: number; // default: 3600
+  networkId: string; // 'fast:testnet' | 'fast:mainnet' | ...
+  signer: Signer; // from @fastxyz/sdk
+  provider: FastProvider; // from @fastxyz/sdk
+}
 ```
 
-You can use existing viem accounts directly — no need to re-wrap them.
-
----
-
-## Common Operations
+#### `executeIntent(params): Promise<BridgeResult>`
 
-### Deposit: EVM → Fast
+Executes Fast → EVM bridge with custom intents. Internally:
 
-Send tokens from an EVM chain to Fast network:
+1. Transfers tokens to the bridge on Fast network
+2. Cross-signs the transfer certificate
+3. Submits intent claim on Fast network
+4. Cross-signs the intent certificate
+5. Submits to the relayer for EVM execution
 
 ```ts
-await allset.sendToFast({
-  chain: 'arbitrum-sepolia',   // EVM chain
-  token: 'USDC',               // Token symbol
-  amount: '1000000',           // Amount in smallest units (6 decimals for USDC)
-  from: evmAccount.address,    // Sender EVM address
-  to: fastWallet.address,      // Receiver Fast address
-  evmClients,                  // From createEvmExecutor()
-});
+interface ExecuteIntentParams {
+  fastBridgeAddress: string;
+  relayerUrl: string;
+  crossSignUrl: string;
+  tokenEvmAddress: string;
+  tokenFastTokenId: string; // hex, no 0x prefix
+  amount: string;
+  intents: Intent[];
+  externalAddress?: string; // override EVM target (required for depositBack/revoke flows)
+  deadlineSeconds?: number; // default: 3600
+  networkId: string; // 'fast:testnet' | 'fast:mainnet' | ...
+  signer: Signer; // from @fastxyz/sdk
+  provider: FastProvider; // from @fastxyz/sdk
+}
 ```
 
-### Withdraw: Fast → EVM
+#### `evmSign(certificate, crossSignUrl): Promise<EvmSignResult>`
 
-Send tokens from Fast network to an EVM chain:
+Cross-signs a Fast network certificate with the AllSet cross-sign service.
+
+---
+
+### Intent Builders (Pure)
 
 ```ts
-await allset.sendToExternal({
-  chain: 'arbitrum-sepolia',   // Target EVM chain
-  token: 'USDC',               // Token symbol
-  amount: '1000000',           // Amount in smallest units
-  from: fastWallet.address,    // Sender Fast address
-  to: evmAccount.address,      // Receiver EVM address
-  fastWallet,                  // From @fastxyz/sdk
-});
+buildTransferIntent(tokenAddress, receiverEvmAddress): Intent
+buildExecuteIntent(targetAddress, calldata, value?): Intent
+buildDepositBackIntent(tokenAddress, fastReceiverAddress): Intent
+buildRevokeIntent(): Intent
 ```
 
 ---
 
-## Advanced: Custom Intents
+### Deposit Planning (Pure, Browser-Safe)
 
-Execute custom operations on EVM via intents:
+#### `buildDepositTransaction(params): DepositTransactionPlan`
 
-```ts
-import { buildTransferIntent, buildExecuteIntent } from '@fastxyz/allset-sdk';
+Builds a deposit transaction without executing it. Useful for displaying, signing externally, or constructing in a browser.
 
-await allset.executeIntent({
-  chain: 'arbitrum-sepolia',
-  fastWallet,
-  token: 'USDC',
-  amount: '1000000',
-  intents: [
-    buildTransferIntent(USDC_ADDRESS, '0xRecipient'),
-    buildExecuteIntent(CONTRACT_ADDRESS, calldata),
-  ],
+```ts
+const plan = buildDepositTransaction({
+  chainId: 421614,
+  bridgeContract: '0xb536...',
+  tokenAddress: '0x75fa...',
+  amount: 1000000n, // bigint
+  receiver: 'fast1abc...',
 });
+// plan.to, plan.data, plan.value — pass to walletClient.sendTransaction()
 ```
 
-### Intent Builders
+#### `encodeDepositCalldata(params): Hex`
 
-| Builder | Purpose |
-|---------|---------|
-| `buildTransferIntent(token, receiver)` | ERC-20 transfer |
-| `buildExecuteIntent(target, calldata, value?)` | Generic contract call |
-| `buildDepositBackIntent(token, fastReceiver)` | Deposit back to Fast |
-| `buildRevokeIntent()` | Cancel pending intent |
+Encodes only the calldata for a deposit call.
 
 ---
 
-## Pure Helpers (Browser-Safe)
-
-Use for deposit planning without execution:
+### Address Utilities (Pure, Browser-Safe)
 
 ```ts
-import { buildDepositTransaction } from '@fastxyz/allset-sdk';
-
-const plan = buildDepositTransaction({
-  network: 'testnet',
-  chain: 'arbitrum-sepolia',
-  token: 'USDC',
-  amount: 1_000_000n,
-  receiver: 'fast1receiveraddress...',
-});
-
-console.log(plan.to);    // Bridge contract
-console.log(plan.data);  // Calldata
-console.log(plan.value); // ETH value (usually 0n)
+fastAddressToBytes32(address: string): Hex        // bech32m → 0x bytes32
+fastAddressToBytes(address: string): Uint8Array   // bech32m → Uint8Array
 ```
 
 ---
 
-## Configuration
+### Error Handling
 
-### Token Parameter
-
-The `token` field in `sendToFast`/`sendToExternal` accepts:
-
-| Format | Example |
-|--------|---------|
-| Symbol | `'USDC'` (mainnet), `'testUSDC'` (testnet) |
-| EVM Address | `'0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d'` |
-
-**Symbol aliases:** `testUSDC` normalizes to `USDC` for testnet chains.
+```ts
+import { FastError, type FastErrorCode } from '@fastxyz/allset-sdk';
+
+try {
+  await executeWithdraw({ ... });
+} catch (err) {
+  if (err instanceof FastError) {
+    console.error(err.code);     // 'TX_FAILED' | 'INVALID_ADDRESS' | 'INVALID_PARAMS'
+    console.error(err.message);
+    console.error(err.context);
+  }
+}
+```
 
-### Finding Supported Assets
+### Claims Encoding (Low-Level)
 
-Supported tokens are configured in [`src/default-config.ts`](./src/default-config.ts).
+`claims.ts` provides standalone functions for encoding AllSet bridge claims. These are used internally by `executeIntent()` but can also be used directly for custom flows:
 
-**Testnet tokens:**
+```ts
+import {
+  encodeTransferClaim,
+  hashTransferClaim,
+  encodeIntentClaim,
+  buildIntentClaimBytes,
+  extractClaimId,
+  type TransferClaimParams,
+  type IntentClaimParams,
+} from '@fastxyz/allset-sdk';
+
+// Encode a transfer claim for cross-signing
+const claimBytes = encodeTransferClaim({
+  fastAddress: 'fast1sender...',
+  tokenFastTokenId: 'abc123...',
+  amount: '1000000',
+  recipientEvmAddress: '0xReceiver...',
+  bridgeAddress: 'fast1bridge...',
+  nonce: 0n,
+  timestamp: BigInt(Math.floor(Date.now() / 1000)),
+});
 
-| Chain | Token | EVM Address |
-|-------|-------|-------------|
-| `arbitrum-sepolia` | USDC | `0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d` |
-| `ethereum-sepolia` | USDC | `0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238` |
+// Hash a transfer claim
+const claimHash = hashTransferClaim({ ... });
 
-**Mainnet tokens:**
+// Encode an intent claim
+const intentBytes = encodeIntentClaim({
+  externalAddress: '0xTarget...',
+  tokenEvmAddress: '0xUSDC...',
+  amount: '1000000',
+  fastAddress: 'fast1sender...',
+  transferClaimId: '0xabc...',
+  externalCallDeadline: BigInt(Math.floor(Date.now() / 1000) + 3600),
+});
 
-| Chain | Token | EVM Address |
-|-------|-------|-------------|
-| `base` | USDC | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
-| `arbitrum` | USDC | `0xaf88d065e77c8cC2239327C5EDb3A432268e5831` |
+// Extract the claim ID from cross-sign transaction output
+const claimId = extractClaimId(crossSignTransaction); // Uint8Array
+```
 
-To add custom tokens, create `~/.allset/networks.json` with your token config.
+### Relay Submission (Low-Level)
 
-### Config Files
+`relay.ts` provides a standalone function for submitting to the AllSet relayer. Use this for step-by-step flows, retry logic, or when you want to separate relay submission from the rest of the bridge flow:
 
-```
-~/.allset/
-└── networks.json      # Custom network config (overrides defaults)
+```ts
+import { relayExecute, type RelayParams } from '@fastxyz/allset-sdk';
+
+const result = await relayExecute({
+  relayerUrl: 'https://relayer.allset...',
+  encodedTransferClaim: [...],   // from evmSign result
+  transferProof: '0x...',         // EVM signature over the transfer claim
+  transferFastTxId: '0x...',      // Fast network tx ID for the transfer
+  fastsetAddress: 'fast1bridge...',
+  externalAddress: '0xTarget...',
+  encodedIntentClaim: [...],      // from evmSign result
+  intentProof: '0x...',            // EVM signature over the intent claim
+  intentClaimId: '0xabc...',
+});
 
-~/.evm/
-└── keys/
-    └── default.json   # EVM wallet keyfiles
+console.log(result.relayTxHash); // EVM transaction hash from the relayer
 ```
 
-### Custom Network Config
-
-Create `~/.allset/networks.json` to override bundled defaults.
-
 ---
 
-## API Reference
+## Types
 
-### AllSetProvider Methods
+```ts
+interface BridgeResult {
+  txHash: string;
+  orderId: string;
+  estimatedTime?: string;
+}
 
-| Method | Description |
-|--------|-------------|
-| `sendToFast(params)` | Deposit EVM → Fast |
-| `sendToExternal(params)` | Withdraw Fast → EVM |
-| `executeIntent(params)` | Execute custom intents |
-| `getChainConfig(chain)` | Get chain configuration |
-| `getTokenConfig(chain, token)` | Get token configuration |
+type FastErrorCode = 'TX_FAILED' | 'INVALID_ADDRESS' | 'INVALID_PARAMS' | 'CROSS_SIGN_FAILED' | 'RELAY_FAILED';
 
-### Error Codes
+class FastError extends Error {
+  readonly code: FastErrorCode;
+  readonly context?: Record<string, unknown>;
+}
 
-| Code | Meaning |
-|------|---------|
-| `INVALID_PARAMS` | Missing required parameter |
-| `INVALID_ADDRESS` | Bad address format |
-| `TOKEN_NOT_FOUND` | Unknown token symbol |
-| `UNSUPPORTED_OPERATION` | Chain not supported |
-| `TX_FAILED` | Transaction rejected |
+interface TransferClaimParams {
+  fastAddress: string;
+  tokenFastTokenId: string;
+  amount: string;
+  recipientEvmAddress: string;
+  bridgeAddress: string;
+  nonce: bigint;
+  timestamp: bigint;
+}
 
----
+interface IntentClaimParams {
+  externalAddress: string;
+  tokenEvmAddress: string;
+  amount: string;
+  fastAddress: string;
+  transferClaimId: string;
+  externalCallDeadline: bigint;
+}
 
-## Supported Networks
+interface RelayParams {
+  relayerUrl: string;
+  encodedTransferClaim: number[];
+  transferProof: string;
+  transferFastTxId: string;
+  fastsetAddress: string;
+  externalAddress: string;
+  encodedIntentClaim: number[];
+  intentProof: string;
+  intentClaimId: string;
+}
 
-| Network | Chain | Chain ID | Status |
-|---------|-------|----------|--------|
-| Testnet | Arbitrum Sepolia | 421614 | ✅ |
-| Testnet | Ethereum Sepolia | 11155111 | ✅ |
-| Testnet | Base | 8453 | ✅ |
-| Mainnet | Coming soon | — | 🔜 |
+interface RelayResult {
+  relayTxHash: string;
+}
+```
 
 ---
 
-## Development
-
-```bash
-npm install
-npm run build
-npm test
-```
-
-See [SKILL.md](./SKILL.md) for detailed workflows.
+## Changelog
 
-## License
+**v0.x (current)**
 
-MIT
+- `executeWithdraw()` — new convenience function for simple Fast → EVM withdrawals
+- `executeIntent()` / `executeWithdraw()` now accept `signer`, `provider`, `networkId` from `@fastxyz/sdk` (replaces `FastWalletLike`)
+- Added Ethereum mainnet (chainId 1) support
+- Pure-function API — no `AllSetProvider`, no embedded config, no keyfile loading
+- Single entrypoint `@fastxyz/allset-sdk` (no sub-path exports)
+- All config values passed as explicit function parameters