@circle-fin/app-kit 1.0.0

package/README.md

@@ -0,0 +1,640 @@
+# App Kit
+
+<div align="center">
+
+[![npm version](https://badge.fury.io/js/@circle-fin%2Fapp-kit.svg)](https://badge.fury.io/js/@circle-fin%2Fapp-kit)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Discord](https://img.shields.io/discord/473781666251538452?label=Discord&logo=discord)](https://discord.com/invite/buildoncircle)
+
+**A unified, strongly-typed SDK for seamless stablecoin operations across chains**
+
+_Making cross-chain transfers and same-chain swaps as simple as a single function call_
+
+</div>
+
+## Table of Contents
+
+- [App Kit](#app-kit)
+  - [Table of Contents](#table-of-contents)
+  - [Overview](#overview)
+    - [Why App Kit?](#why-app-kit)
+  - [Architecture Flow](#architecture-flow)
+  - [Installation](#installation)
+    - [Adapters](#adapters)
+  - [Quick Start](#quick-start)
+    - [🌉 Cross-Chain Bridge](#-cross-chain-bridge)
+    - [🔄 Same-Chain Swap](#-same-chain-swap)
+    - [📊 Estimate Operations](#-estimate-operations)
+    - [🔍 Query Supported Chains](#-query-supported-chains)
+  - [Configuration](#configuration)
+    - [Send Parameters](#send-parameters)
+    - [Swap Parameters](#swap-parameters)
+    - [Bridge Parameters](#bridge-parameters)
+  - [Custom Fees](#custom-fees)
+    - [Operation-Level Custom Fees](#operation-level-custom-fees)
+    - [Kit-Level Fee Policies](#kit-level-fee-policies)
+  - [Error Handling](#error-handling)
+  - [Examples](#examples)
+    - [Basic Cross-Chain Transfer](#basic-cross-chain-transfer)
+    - [Same-Chain Token Swap](#same-chain-token-swap)
+    - [Send to Different Address](#send-to-different-address)
+    - [Event Monitoring](#event-monitoring)
+  - [API Reference](#api-reference)
+    - [Core Methods](#core-methods)
+  - [Development](#development)
+    - [Building](#building)
+    - [Testing](#testing)
+    - [Local Development](#local-development)
+  - [Community \& Support](#community--support)
+  - [License](#license)
+
+## Overview
+
+The App Kit ecosystem is Circle's open-source effort to streamline stablecoin development with SDKs that are easy to use correctly and hard to misuse. Kits are cross-framework (viem, ethers, @solana/web3) and integrate cleanly into any stack. They're opinionated with sensible defaults, but offer escape hatches for full control. A pluggable architecture makes implementation flexible, and all kits are interoperable, so they can be composed to suit a wide range of use cases.
+
+The App Kit provides a **unified interface** for both cross-chain transfers and same-chain swaps, abstracting away the complexity of choosing between bridging and swapping operations. It combines the power of Bridge Kit and Swap Kit into a single, cohesive API.
+
+### Why App Kit?
+
+- **🎯 Unified interface**: Single API for both bridge and swap operations
+- **🤖 Smart routing**: Automatically selects the appropriate operation (bridge vs swap)
+- **⚡ Zero-config defaults**: Built-in reliable RPC endpoints - start building right away
+- **🔧 Bring your own infrastructure**: Seamlessly integrate with your existing setup when needed
+- **🔒 Production-ready security**: Leverages Circle's CCTPv2 for bridging and trusted swap providers
+- **🚀 Developer experience**: Complete TypeScript support, comprehensive validation, and instant connectivity
+- **🌍 Multi-chain support**: Bridge across **35 chains** with **578 total bridge routes** through Circle's CCTPv2
+  - **Mainnet (17 chains)**: Arbitrum, Avalanche, Base, Codex, Ethereum, HyperEVM, Ink, Linea, OP Mainnet, Plume, Polygon PoS, Sei, Solana, Sonic, Unichain, World Chain, XDC
+  - **Testnet (18 chains)**: Arc Testnet, Arbitrum Sepolia, Avalanche Fuji, Base Sepolia, Codex Testnet, Ethereum Sepolia, HyperEVM Testnet, Ink Testnet, Linea Sepolia, OP Sepolia, Plume Testnet, Polygon PoS Amoy, Sei Testnet, Solana Devnet, Sonic Testnet, Unichain Sepolia, World Chain Sepolia, XDC Apothem
+- **🔄 Swap support**: Same-chain token swaps powered by Circle's Stablecoin Service
+- **🎯 Flexible adapters**: Supporting EVM (Viem, Ethers) and Solana (@solana/web3)
+- **📡 Real-time event monitoring**: Track progress throughout the operation lifecycle
+- **🛡️ Robust error handling**: Graceful partial success recovery
+- **✈️ Pre-flight validation**: Verify operations with cost estimation before execution
+
+## Architecture Flow
+
+The App Kit follows a composable architecture that integrates Bridge Kit and Swap Kit:
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│                        App Kit                               │
+│                   (Unified Interface)                       │
+└──────────────────────┬──────────────────────────────────────┘
+                       │
+         ┌─────────────┴─────────────┐
+         │                           │
+         ▼                           ▼
+┌─────────────────┐         ┌─────────────────┐
+│   Bridge Kit    │         │    Swap Kit     │
+│ (Cross-Chain)   │         │  (Same-Chain)   │
+└────────┬────────┘         └────────┬────────┘
+         │                           │
+         ▼                           ▼
+┌─────────────────┐         ┌─────────────────┐
+│     Provider    │         │     Provider    │
+│   (CCTPv2)      │         │   (Service)     │
+└────────┬────────┘         └────────┬────────┘
+         │                           │
+         └─────────────┬─────────────┘
+                       ▼
+               ┌───────────────┐
+               │    Adapter    │
+               │ (Blockchain)  │
+               └───────────────┘
+```
+
+1. **Adapter**: Handles blockchain-specific operations (wallets, transactions, gas)
+2. **Provider**: Implements protocols (CCTPv2 for bridging, Circle Service for swaps)
+3. **Bridge/Swap Kit**: Specialized kits for each operation type
+4. **App Kit**: Unified orchestration layer providing a consistent API
+
+This separation ensures that each component has a single responsibility while maintaining seamless integration across the entire stablecoin operation lifecycle.
+
+## Installation
+
+```bash
+npm install @circle-fin/app-kit
+# or
+yarn add @circle-fin/app-kit
+```
+
+### Adapters
+
+Choose the appropriate adapter for your target chains:
+
+```bash
+# For EVM chains (Ethereum, Base, Arbitrum, etc.)
+npm install @circle-fin/adapter-viem-v2 viem
+# or
+yarn add @circle-fin/adapter-viem-v2 viem
+
+# For EVM chains using Ethers.js
+npm install @circle-fin/adapter-ethers-v6
+# or
+yarn add @circle-fin/adapter-ethers-v6
+
+# For Solana
+npm install @circle-fin/adapter-solana @solana/web3.js @solana/spl-token
+# or
+yarn add @circle-fin/adapter-solana @solana/web3.js @solana/spl-token
+```
+
+### Chain Definitions
+
+Import chain definitions directly from the kit:
+
+```typescript
+import { Ethereum, Base, Polygon, Solana } from '@circle-fin/app-kit/chains'
+
+// Use with adapter context
+const result = await kit.bridge({
+  from: { adapter, chain: Ethereum },
+  to: { adapter, chain: Base },
+  amount: '10.50',
+})
+```
+
+All 35 CCTPv2-supported chains are available for import.
+
+## Quick Start
+
+### 🌉 Cross-Chain Bridge
+
+Transfer USDC from one chain to another:
+
+```typescript
+import { AppKit } from '@circle-fin/app-kit'
+import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+
+// Initialize the kit
+const kit = new AppKit()
+
+// Create ONE adapter that works across all chains
+const adapter = createViemAdapterFromPrivateKey({
+  privateKey: process.env.PRIVATE_KEY as string,
+})
+
+// Bridge from Ethereum to Base
+const result = await kit.bridge({
+  from: { adapter, chain: 'Ethereum' },
+  to: { adapter, chain: 'Base' },
+  amount: '10.50',
+})
+```
+
+### 🔄 Same-Chain Swap
+
+Swap tokens on the same chain with support for multiple stablecoins:
+
+```typescript
+// Swap USDC to USDT on Ethereum
+const result = await kit.swap({
+  from: { adapter, chain: 'Ethereum' },
+  tokenIn: 'USDC',
+  tokenOut: 'USDT',
+  amountIn: '100.0',
+})
+
+// Swap DAI to USDC (18 decimals handled automatically)
+const daiSwap = await kit.swap({
+  from: { adapter, chain: 'Ethereum' },
+  tokenIn: 'DAI',
+  tokenOut: 'USDC',
+  amountIn: '500.0',
+})
+
+// Swap native ETH to stablecoin
+const nativeSwap = await kit.swap({
+  from: { adapter, chain: 'Ethereum' },
+  tokenIn: 'NATIVE', // ETH on Ethereum
+  tokenOut: 'USDC',
+  amountIn: '1.5',
+})
+```
+
+### 📊 Estimate Operations
+
+Get cost estimates before executing operations:
+
+```typescript
+// Estimate bridge operation
+const bridgeEstimate = await kit.estimateBridge({
+  from: { adapter, chain: 'Ethereum' },
+  to: { adapter, chain: 'Base' },
+  amount: '10.50',
+})
+
+// Estimate swap operation
+const swapEstimate = await kit.estimateSwap({
+  from: { adapter, chain: 'Ethereum' },
+  tokenIn: 'USDC',
+  tokenOut: 'USDT',
+  amountIn: '100.0',
+})
+
+console.log('Bridge fees:', bridgeEstimate.fees)
+console.log(
+  'Swap estimated output:',
+  swapEstimate.estimatedOutput?.amount,
+  swapEstimate.estimatedOutput?.token,
+)
+```
+
+### 🔍 Query Supported Chains
+
+Check which chains support specific operations:
+
+```typescript
+// Get all chains that support bridging
+const bridgeChains = kit.getSupportedChains('bridge')
+
+// Get all chains that support swapping
+const swapChains = kit.getSupportedChains('swap')
+
+// Get all chains (both bridge and swap)
+const allChains = kit.getSupportedChains()
+```
+
+## Configuration
+
+### Send Parameters
+
+The `send()` method provides a unified interface for transferring tokens. It automatically determines whether to use bridging or swapping based on the source and destination chains:
+
+```typescript
+interface SendParams {
+  from: AdapterContext // Source wallet and chain
+  to: Adapter | string // Destination wallet or address
+  amount: string // Amount to transfer (e.g., '10.50')
+  token?: TokenAlias | string // Optional, defaults to 'USDC'
+}
+```
+
+**Token Support**
+
+The `token` field accepts both known aliases and custom token contract addresses:
+
+**Known aliases (for send operations):**
+
+- `'USDC'` - USD Coin (6 decimals)
+- `'USDT'` - Tether USD (6 decimals)
+- `'NATIVE'` - Chain's native currency (ETH, SOL, etc.)
+
+**Custom addresses:**
+
+- EVM contract addresses (e.g., `0x6B175474E89094C44Da98b954EedeAC495271d0F`)
+- Solana SPL mint addresses
+
+**Note**: For swap operations, additional stablecoins (EURC, DAI, USDE, PYUSD) are supported. See [Swap Parameters](#swap-parameters) section below.
+
+**Examples**
+
+```typescript
+// Using USDC (default)
+await kit.send({
+  from: { adapter, chain: 'Ethereum' },
+  to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
+  amount: '10.0',
+  token: 'USDC',
+})
+
+// Using USDT
+await kit.send({
+  from: { adapter, chain: 'Ethereum' },
+  to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
+  amount: '100.0',
+  token: 'USDT',
+})
+
+// Using NATIVE
+await kit.send({
+  from: { adapter, chain: 'Ethereum' },
+  to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
+  amount: '1.5',
+  token: 'NATIVE', // ETH on Ethereum
+})
+
+// Using a custom ERC-20 token address (e.g., DAI)
+await kit.send({
+  from: { adapter, chain: 'Ethereum' },
+  to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
+  amount: '50.0',
+  token: '0x6B175474E89094C44Da98b954EedeAC495271d0F', // DAI contract address
+})
+
+// Using a custom SPL token on Solana
+await kit.send({
+  from: { adapter, chain: 'Solana' },
+  to: 'DhzPkKCLJGHBZbs1AzmK2tRNLZkV8J3yWF3LuWMuKJpN',
+  amount: '50.0',
+  token: 'So11111111111111111111111111111111111111112', // Wrapped SOL
+})
+```
+
+### Swap Parameters
+
+For explicit same-chain swaps:
+
+```typescript
+interface SwapParams {
+  from: AdapterContext // Source wallet and chain
+  tokenIn: SupportedToken // Input token
+  tokenOut: SupportedToken // Output token
+  amountIn: string // Amount to swap
+  to?: string // Optional recipient address
+  config?: SwapConfig // Optional swap configuration
+}
+
+// SupportedToken includes:
+// - Stablecoins (6 decimals): 'USDC', 'EURC', 'USDT', 'PYUSD'
+// - Stablecoins (18 decimals): 'DAI', 'USDE'
+// - Native: 'NATIVE' (chain's native currency)
+```
+
+**Swap Examples with Different Tokens**
+
+```typescript
+// Swap between 6-decimal stablecoins
+await kit.swap({
+  from: { adapter, chain: 'Ethereum' },
+  tokenIn: 'EURC',
+  tokenOut: 'USDC',
+  amountIn: '100.0',
+})
+
+// Swap DAI (18 decimals) to USDT
+await kit.swap({
+  from: { adapter, chain: 'Ethereum' },
+  tokenIn: 'DAI',
+  tokenOut: 'USDT',
+  amountIn: '500.0', // SDK automatically handles 18-decimal precision
+})
+
+// Swap native token to stablecoin
+await kit.swap({
+  from: { adapter, chain: 'Ethereum' },
+  tokenIn: 'NATIVE', // ETH on Ethereum
+  tokenOut: 'USDC',
+  amountIn: '2.5',
+})
+```
+
+### Bridge Parameters
+
+For explicit cross-chain bridges:
+
+```typescript
+interface BridgeParams {
+  from: AdapterContext // Source wallet and chain
+  to: BridgeDestination // Destination wallet/address and chain
+  amount: string // Amount to transfer (e.g., '10.50')
+  token?: 'USDC' // Optional, defaults to 'USDC'
+  config?: BridgeConfig // Optional bridge configuration
+}
+```
+
+## Custom Fees
+
+App Kit supports custom developer fees on both bridge and swap operations.
+
+### Operation-Level Custom Fees
+
+Apply custom fees to individual operations:
+
+```typescript
+// Bridge with custom fee
+await kit.bridge({
+  from: { adapter, chain: 'Ethereum' },
+  to: { adapter, chain: 'Base' },
+  amount: '1000',
+  config: {
+    customFee: {
+      value: '10', // 10 USDC fee
+      recipientAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0',
+    },
+  },
+})
+
+// Swap with custom fee
+await kit.swap({
+  from: { adapter, chain: 'Ethereum' },
+  tokenIn: 'USDC',
+  tokenOut: 'USDT',
+  amountIn: '1000',
+  config: {
+    customFee: {
+      value: '10',
+      recipientAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0',
+    },
+  },
+})
+```
+
+### Kit-Level Fee Policies
+
+For dynamic fee calculation across all operations, use kit-level policies:
+
+```typescript
+import { AppKit } from '@circle-fin/app-kit'
+import { formatUnits } from 'viem'
+
+const kit = new AppKit()
+
+kit.setCustomFeePolicy({
+  calculateFee: (params) => {
+    // Calculate fee based on operation type and parameters
+    const amount = Number(formatUnits(BigInt(params.amount), 6))
+    const feePercentage = type === 'bridge' ? 0.01 : 0.005 // 1% for bridge, 0.5% for swap
+
+    return (amount * feePercentage).toFixed(6)
+  },
+  resolveFeeRecipientAddress: (type, info) => {
+    // Return appropriate address based on operation type and chain
+    return info.chain.type === 'solana'
+      ? 'SolanaAddressBase58...'
+      : '0xEvmAddress...'
+  },
+})
+
+// All subsequent operations will use this policy
+await kit.bridge({
+  from: { adapter, chain: 'Ethereum' },
+  to: { adapter, chain: 'Base' },
+  amount: '1000', // Custom fee calculated automatically
+})
+```
+
+## Error Handling
+
+The kit uses a thoughtful error handling approach:
+
+- **Hard errors** (thrown): Validation, configuration, and authentication errors
+- **Soft errors** (returned): Recoverable issues like insufficient balance or network errors
+
+```typescript
+import { AppKit } from '@circle-fin/app-kit'
+import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+
+const kit = new AppKit()
+const adapter = createViemAdapterFromPrivateKey({
+  privateKey: process.env.PRIVATE_KEY as string,
+})
+
+const result = await kit.bridge({
+  from: { adapter, chain: 'Ethereum' },
+  to: { adapter, chain: 'Base' },
+  amount: '100.0',
+})
+
+if (result.state === 'success') {
+  console.log('Operation successful!')
+} else {
+  // Handle partial completion with recovery information
+  console.log(
+    'Successful steps:',
+    result.steps.filter((s) => s.state === 'success'),
+  )
+}
+```
+
+## Examples
+
+### Basic Cross-Chain Transfer
+
+```typescript
+import { AppKit } from '@circle-fin/app-kit'
+import { createViemAdapterFromPrivateKey } from '@circle-fin/adapter-viem-v2'
+
+const kit = new AppKit()
+const adapter = createViemAdapterFromPrivateKey({
+  privateKey: process.env.PRIVATE_KEY as string,
+})
+
+// Bridge USDC from Ethereum to Base
+const result = await kit.bridge({
+  from: { adapter, chain: 'Ethereum' },
+  to: { adapter, chain: 'Base' },
+  amount: '50.0',
+})
+
+console.log('Bridge result:', result)
+```
+
+### Same-Chain Token Swap
+
+```typescript
+// Swap USDC to USDT on Ethereum
+const result = await kit.swap({
+  from: { adapter, chain: 'Ethereum' },
+  tokenIn: 'USDC',
+  tokenOut: 'USDT',
+  amountIn: '100.0',
+})
+
+console.log('Swap result:', result)
+```
+
+### Send to Different Address
+
+```typescript
+// Send to a different address (automatically chooses bridge or swap)
+const result = await kit.send({
+  from: { adapter, chain: 'Ethereum' },
+  to: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
+  amount: '10.50',
+  token: 'USDC',
+})
+```
+
+### Event Monitoring
+
+```typescript
+// Listen to bridge events
+kit.on('bridge.approve', (payload) => {
+  console.log('Approval transaction:', payload.values.txHash)
+})
+
+kit.on('bridge.burn', (payload) => {
+  console.log('Burn transaction:', payload.values.txHash)
+})
+
+// Listen to all events
+kit.on('*', (payload) => {
+  console.log('Action:', payload.method)
+})
+
+// Execute operation
+await kit.bridge({
+  from: { adapter, chain: 'Ethereum' },
+  to: { adapter, chain: 'Base' },
+  amount: '10.0',
+})
+```
+
+## API Reference
+
+### Core Methods
+
+- `kit.send(params)` - Unified interface for transfers (auto-routes to bridge or swap)
+- `kit.bridge(params)` - Execute cross-chain bridge operation
+- `kit.swap(params)` - Execute same-chain swap operation
+- `kit.estimateBridge(params)` - Get cost estimates for bridging
+- `kit.estimateSwap(params)` - Get cost estimates for swapping
+- `kit.estimateSend(params)` - Get cost estimates for send operation
+- `kit.getSupportedChains(operationType?)` - Query supported chains by operation type
+- `kit.setCustomFeePolicy(policy)` - Set kit-level custom fee policy
+- `kit.on(event, handler)` - Listen to operation events
+- `kit.off(event, handler)` - Remove event listener
+
+## Development
+
+### Building
+
+```bash
+# From the root of the monorepo
+nx build @circle-fin/app-kit
+```
+
+### Testing
+
+```bash
+# From the root of the monorepo
+nx test @circle-fin/app-kit
+```
+
+### Local Development
+
+```bash
+# Install dependencies
+yarn install
+
+# Build all packages
+yarn build
+
+# Build the app-kit specifically
+nx build @circle-fin/app-kit
+
+# Run tests
+nx test @circle-fin/app-kit
+```
+
+## Community & Support
+
+- **💬 Discord**: [Join our community](https://discord.com/invite/buildoncircle)
+
+## License
+
+This project is licensed under the Apache 2.0 License. Contact [support](https://help.circle.com/s/submit-ticket) for details.
+
+---
+
+<div align="center">
+
+**Ready to start building?**
+
+[Join Discord](https://discord.com/invite/buildoncircle)
+
+_Built with ❤️ by Circle_
+
+</div>

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@circle-fin/app-kit",
+  "version": "1.0.0",
+  "private": false,
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "main": "./index.cjs",
+  "module": "./index.mjs",
+  "types": "./index.d.ts",
+  "dependencies": {
+    "@core/chains": "0.3.0",
+    "@circle-fin/bridge-kit": "1.6.1",
+    "@circle-fin/swap-kit": "1.0.0",
+    "@core/provider": "0.0.9",
+    "@core/utils": "0.2.3",
+    "@core/adapter": "0.2.0",
+    "@core/errors": "0.2.3",
+    "@core/tokens": "0.0.4"
+  },
+  "devDependencies": {
+    "@core/adapter": "0.1.1",
+    "@core/chains": "0.2.0",
+    "@core/provider": "0.0.8",
+    "@core/utils": "0.2.2",
+    "@nx/vite": "21.1.2",
+    "vitest": "^3.0.0"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs",
+      "require": "./index.cjs",
+      "default": "./index.cjs"
+    },
+    "./chains": {
+      "types": "./chains.d.ts",
+      "import": "./chains.mjs",
+      "require": "./chains.cjs",
+      "default": "./chains.cjs"
+    },
+    "./context": {
+      "types": "./kit/context/context.d.ts",
+      "import": "./kit/context/context.mjs",
+      "require": "./kit/context/context.cjs"
+    },
+    "./bridge": {
+      "types": "./kit/operations/bridge/bridge.d.ts",
+      "import": "./kit/operations/bridge/bridge.mjs",
+      "require": "./kit/operations/bridge/bridge.cjs"
+    },
+    "./estimateBridge": {
+      "types": "./kit/operations/estimateBridge/estimateBridge.d.ts",
+      "import": "./kit/operations/estimateBridge/estimateBridge.mjs",
+      "require": "./kit/operations/estimateBridge/estimateBridge.cjs"
+    },
+    "./swap": {
+      "types": "./kit/operations/swap/swap.d.ts",
+      "import": "./kit/operations/swap/swap.mjs",
+      "require": "./kit/operations/swap/swap.cjs"
+    },
+    "./estimateSwap": {
+      "types": "./kit/operations/estimateSwap/estimateSwap.d.ts",
+      "import": "./kit/operations/estimateSwap/estimateSwap.mjs",
+      "require": "./kit/operations/estimateSwap/estimateSwap.cjs"
+    }
+  },
+  "files": [
+    "chains.*",
+    "index.*",
+    "README.md",
+    "QUICKSTART.md",
+    "package.json",
+    "LICENSE"
+  ]
+}