AllSet SDK

Bridge tokens between Fast network 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 |

Install

Pure helpers only:

npm install @fastxyz/allset-sdk

Full bridge execution (requires @fastxyz/sdk):

npm install @fastxyz/allset-sdk @fastxyz/sdk

Quick Start

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('~/.allset/.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,
});

AllSetProvider Setup

AllSetProvider connects to AllSet bridge infrastructure.

Default (testnet)

import { AllSetProvider } from '@fastxyz/allset-sdk/node';

const allset = new AllSetProvider();

Specify Network

const allset = new AllSetProvider({ network: 'testnet' });
// or when available:
const allset = new AllSetProvider({ network: 'mainnet' });

Custom Config

const allset = new AllSetProvider({
  configPath: './my-networks.json',
  crossSignUrl: 'https://custom.cross-sign.example.com',
});

Provider Options

interface AllSetProviderOptions {
  network?: 'testnet' | 'mainnet';
  configPath?: string;      // Custom config file path
  crossSignUrl?: string;    // Override cross-sign endpoint
}

Network Config Resolution Order

1. Custom configPath (if provided, highest priority)
2. ~/.allset/networks.json (user override)
3. Bundled defaults from src/default-config.ts

Fast Wallet Setup

Fast wallet is required for withdrawals (Fast → EVM).

import { FastProvider, FastWallet } from '@fastxyz/sdk';

const fastProvider = new FastProvider({ network: 'testnet' });
const fastWallet = await FastWallet.fromKeyfile('~/.fast/keys/default.json', fastProvider);

See @fastxyz/sdk documentation for wallet setup details.

EVM Wallet Setup

EVM wallet is required for deposits (EVM → Fast).

Generate New Wallet

import { createEvmWallet } from '@fastxyz/allset-sdk/node';

const account = createEvmWallet();
console.log('Address:', account.address);
console.log('Private Key:', account.privateKey);  // Save this!

From Private Key

const account = createEvmWallet('0x1234...64hexchars');
// or without 0x prefix
const account = createEvmWallet('1234...64hexchars');

From Keyfile

const account = createEvmWallet('~/.allset/.evm/keys/default.json');

Keyfile format:

{
  "privateKey": "abc123...64hexchars",
  "address": "0x..."
}

Create EVM Executor

EVM executor provides viem clients for blockchain operations:

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 }

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

viem Interoperability

createEvmWallet() returns a standard viem account (from privateKeyToAccount), so it's fully interoperable:

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);

You can use existing viem accounts directly — no need to re-wrap them.

Common Operations

Deposit: EVM → Fast

Send tokens from an EVM chain to Fast network:

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()
});

Withdraw: Fast → EVM

Send tokens from Fast network to an EVM chain:

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
});

Advanced: Custom Intents

Execute custom operations on EVM via intents:

import { buildTransferIntent, buildExecuteIntent } from '@fastxyz/allset-sdk';

await allset.executeIntent({
  chain: 'arbitrum-sepolia',
  fastWallet,
  token: 'USDC',
  amount: '1000000',
  intents: [
    buildTransferIntent(USDC_ADDRESS, '0xRecipient'),
    buildExecuteIntent(CONTRACT_ADDRESS, calldata),
  ],
});

Intent Builders

| 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 |

Pure Helpers (Browser-Safe)

Use for deposit planning without execution:

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)

Configuration

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.

Finding Supported Assets

Supported tokens are configured in src/default-config.ts.

Testnet tokens:

| Chain | Token | EVM Address | |-------|-------|-------------| | arbitrum-sepolia | USDC | 0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d | | ethereum-sepolia | USDC | 0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238 |

Mainnet tokens:

| Chain | Token | EVM Address | |-------|-------|-------------| | base | USDC | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 | | arbitrum | USDC | 0xaf88d065e77c8cC2239327C5EDb3A432268e5831 |

To add custom tokens, create ~/.allset/networks.json with your token config.

Config Files

~/.allset/
├── networks.json      # Custom network config (overrides defaults)
└── .evm/
    └── keys/
        └── default.json   # EVM wallet keyfiles

Custom Network Config

Create ~/.allset/networks.json to override bundled defaults.

API Reference

AllSetProvider Methods

| 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 |

Error Codes

| 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 |

Supported Networks

| Network | Chain | Chain ID | Status | |---------|-------|----------|--------| | Testnet | Arbitrum Sepolia | 421614 | ✅ | | Testnet | Ethereum Sepolia | 11155111 | ✅ | | Testnet | Base | 8453 | ✅ | | Mainnet | Coming soon | — | 🔜 |

Development

npm install
npm run build
npm test

See SKILL.md for detailed workflows.

License

MIT