@riftresearch/sdk 0.1.3 → 0.2.0

package/README.md

@@ -14,11 +14,9 @@ yarn add @riftresearch/sdk
 bun add @riftresearch/sdk
 ```
 
-## Usage
+## Quickstart
 
-### USDC → BTC Swap (Base)
-
-```typescript
+```ts
 import { RiftSdk, BTC, type Currency } from '@riftresearch/sdk'
 import { createPublicClient, createWalletClient, http } from 'viem'
 import { privateKeyToAccount } from 'viem/accounts'
@@ -48,79 +46,38 @@ const sdk = new RiftSdk({
   publicClient,
   walletClient,
   sendBitcoin: async ({ recipient, amountSats }) => {
-    // Only needed for BTC → ERC20 swaps
+    // Only needed for BTC -> ERC20 swaps
     throw new Error('Not implemented')
   },
 })
 
-// Get quote for swapping 100 USDC to BTC
+// Get a quote
 const { quote, executeSwap } = await sdk.getQuote({
   from: USDC_BASE,
   to: BTC,
   amount: '100000000', // 100 USDC (6 decimals)
   mode: 'exact_input',
-  destinationAddress: 'bc1q...', // Your Bitcoin address
+  destinationAddress: 'bc1q...',
 })
 
 console.log(`Swapping ${quote.from.amount} USDC for ${quote.to.amount} sats`)
 console.log(`Fees: $${quote.fees.totalUsd.toFixed(2)}`)
 
-// Execute the swap (routes through CowSwap → Rift)
+// Execute the swap
 const swap = await executeSwap()
-console.log(`Swap ID: ${swap.swapId}`)
+console.log(`Swap ID: ${swap.swapId}`) // API order ID
 
 // Check status
 const status = await sdk.getSwapStatus(swap.swapId)
 console.log(`Status: ${status.status}`)
 ```
 
-### BTC → ETH Swap (Ethereum Mainnet)
-
-```typescript
-import { RiftSdk, BTC, type Currency } from '@riftresearch/sdk'
-import { createPublicClient, createWalletClient, http } from 'viem'
-import { privateKeyToAccount } from 'viem/accounts'
-import { mainnet } from 'viem/chains'
-
-// Define ETH on Ethereum mainnet
-const ETH_MAINNET: Currency = {
-  chain: { kind: 'EVM', chainId: 1 },
-  token: { kind: 'NATIVE', decimals: 18 },
-}
-
-const account = privateKeyToAccount('0x...')
-const publicClient = createPublicClient({ chain: mainnet, transport: http() })
-const walletClient = createWalletClient({
-  account,
-  chain: mainnet,
-  transport: http(),
-})
-
-const sdk = new RiftSdk({
-  publicClient,
-  walletClient,
-  sendBitcoin: async ({ recipient, amountSats }) => {
-    // Implement using your Bitcoin wallet (Xverse, Leather, etc.)
-    await sendBitcoinTransaction(recipient, amountSats)
-  },
-})
-
-// Get quote for swapping 0.01 BTC to ETH
-const { quote, executeSwap } = await sdk.getQuote({
-  from: BTC,
-  to: ETH_MAINNET,
-  amount: '1000000', // 0.01 BTC (8 decimals = 1,000,000 sats)
-  mode: 'exact_input',
-  destinationAddress: '0x...', // Your Ethereum address
-})
-
-console.log(`Swapping ${quote.from.amount} sats for ${quote.to.amount} wei`)
-
-const swap = await executeSwap()
-console.log(`Swap ID: ${swap.swapId}`)
-```
+## Build & Publish
 
+The SDK uses **bunup**.
 
-## License
+- Build: `bun run --filter '@riftresearch/sdk' build`
+- Publish (from repo root): `bun run publish:sdk`
+- Release (version bump + build + publish): `bun run release:sdk`
 
-MIT
+The `dist/` directory is what gets published to npm.

package/dist/index.d.ts

@@ -21,124 +21,264 @@ interface Currency {
 	chain: Chain;
 	token: TokenIdentifier;
 }
-type SwapStatus = "waiting_user_deposit_initiated" | "waiting_user_deposit_confirmed" | "waiting_mm_deposit_initiated" | "waiting_mm_deposit_confirmed" | "settling" | "settled" | "refunding_user" | "failed";
-interface UserDepositStatus {
-	tx_hash: string;
+/**
+* A currency amount that was specified by the user (exact).
+*/
+interface SpecifiedAmount {
+	currency: Currency;
 	amount: U256;
-	deposit_detected_at: string;
-	confirmations: number;
-	last_checked: string;
-	confirmed_at?: string;
 }
-interface MMDepositStatus {
-	tx_hash: string;
+/**
+* A calculated output amount for exact_input mode.
+* The user specifies exact input, and this represents the expected output.
+*/
+interface CalculatedOutputAmount {
+	currency: Currency;
+	/** Expected output based on current market conditions */
 	amount: U256;
-	deposit_detected_at: string;
-	confirmations: number;
-	last_checked: string;
+	/** Minimum guaranteed output after slippage (optional - not all routes provide this) */
+	minimum?: U256;
 }
-interface SettlementStatus {
-	tx_hash: string;
-	broadcast_at: string;
-	confirmations: number;
-	completed_at?: string;
-	fee?: U256;
+/**
+* A calculated input amount for exact_output mode.
+* The user specifies exact output, and this represents the expected input.
+*/
+interface CalculatedInputAmount {
+	currency: Currency;
+	/** Expected input based on current market conditions */
+	amount: U256;
+	/** Maximum input required after slippage (optional - not all routes provide this) */
+	maximum?: U256;
 }
-interface LatestRefund {
-	timestamp: string;
-	recipient_address: string;
+/**
+* A single fee component with amount in native currency and USD equivalent.
+*/
+interface FeeComponent {
+	/** Amount in the smallest unit of the currency */
+	amount: U256;
+	/** The currency this fee is denominated in */
+	currency: Currency;
+	/** USD equivalent of the fee */
+	usd: number;
 }
-interface RealizedSwap {
-	user_input: U256;
-	mm_output: U256;
-	protocol_fee: U256;
-	liquidity_fee: U256;
-	network_fee: U256;
+/**
+* Rift protocol fees broken down by type.
+*/
+interface RiftFees {
+	/** Bitcoin network transaction fee */
+	network: FeeComponent;
+	/** Fee paid to liquidity providers */
+	liquidity: FeeComponent;
+	/** Rift protocol fee */
+	protocol: FeeComponent;
 }
-interface SwapRates {
-	liquidity_fee_bps: number;
-	protocol_fee_bps: number;
-	network_fee_sats: number;
+/**
+* Complete fee breakdown for a swap quote.
+* Shows fees from each leg of the swap in their native currencies.
+*/
+interface FeeBreakdown {
+	/** Fees from DEX swap BEFORE Rift (e.g., 1inch USDC → cbBTC) */
+	preswap?: FeeComponent;
+	/** Fees from the Rift protocol (optional for mono-chain swaps) */
+	rift?: RiftFees;
+	/** Fees from DEX swap AFTER Rift (e.g., Swapper cbBTC → USDC) */
+	postswap?: FeeComponent;
+	/** Total fees in USD across all legs */
+	totalUsd: number;
 }
-interface SwapFees {
-	liquidity_fee: U256;
-	protocol_fee: U256;
-	network_fee: U256;
+/**
+* Base fields shared by all quote responses.
+*/
+interface QuoteResponseBase {
+	id: string;
+	fees: FeeBreakdown;
+	expiresAt: string;
 }
-interface LotCurrency {
-	chain: "bitcoin" | "ethereum" | "base" | "solana";
-	token: {
-		type: "Native";
-	} | {
-		type: "Address";
-		data: string;
-	};
-	decimals: number;
+/**
+* Quote response for exact_input mode.
+* User specifies exact input amount, output is calculated with slippage bound.
+*/
+interface ExactInputQuoteResponse extends QuoteResponseBase {
+	mode: "exact_input";
+	/** The exact input amount specified by the user */
+	from: SpecifiedAmount;
+	/** The calculated output amount with slippage bound */
+	to: CalculatedOutputAmount;
 }
-interface Lot {
-	currency: LotCurrency;
-	amount: U256;
+/**
+* Quote response for exact_output mode.
+* User specifies exact output amount, input is calculated with slippage bound.
+*/
+interface ExactOutputQuoteResponse extends QuoteResponseBase {
+	mode: "exact_output";
+	/** The calculated input amount with slippage bound */
+	from: CalculatedInputAmount;
+	/** The exact output amount specified by the user */
+	to: SpecifiedAmount;
 }
-interface SwapQuote {
+/**
+* Discriminated union of quote responses.
+* Use `mode` to determine which fields are specified vs calculated.
+*/
+type QuoteResponse = ExactInputQuoteResponse | ExactOutputQuoteResponse;
+type OrderStatus = "waiting_for_deposit" | "deposit_confirming" | "initiating_transfer" | "confirming_transfer" | "swap_complete" | "refunding_user" | "failed";
+interface OrderStatusResponse {
+	status: OrderStatus;
+}
+/**
+* Execution actions - the mechanism by which a step is executed.
+*/
+type ExecutionAction = "evm_call" | "btc_transfer";
+/**
+* Step kinds grouped by action type.
+*/
+type EvmCallKind = "approval" | "transfer_erc20" | "oneinch_swap";
+type BtcTransferKind = "transfer_btc";
+/**
+* EVM Call step - execute calldata on an EVM chain.
+* Used for: token approvals, ERC20 transfers, 1inch swaps.
+*/
+interface EvmCallStep {
+	/** Step ID for tracking */
 	id: string;
-	market_maker_id: string;
-	from: Lot;
-	to: Lot;
-	rates: SwapRates;
-	fees: SwapFees;
-	min_input: U256;
-	max_input: U256;
-	affiliate?: string;
-	expires_at: string;
-	created_at: string;
+	/** Execution mechanism */
+	action: "evm_call";
+	/** Specific step type */
+	kind: EvmCallKind;
+	/** Chain ID for the transaction */
+	chainId: number;
+	/** Contract address to call */
+	to: string;
+	/** Encoded calldata */
+	calldata: string;
+	/** Native ETH value to send (for oneinch_swap) */
+	value?: U256;
+	/** Token address (for approval, transfer_evm) */
+	tokenAddress?: string;
+	/** Spender address (for approval) */
+	spenderAddress?: string;
+	/** Amount for display/verification (for approval, transfer_evm) */
+	amount?: U256;
 }
-interface Swap {
+/**
+* BTC Transfer step - send Bitcoin to an address.
+* Used for: depositing BTC to Rift vault.
+*/
+interface BtcTransferStep {
+	/** Step ID for tracking */
 	id: string;
-	market_maker_id: string;
-	quote: SwapQuote;
-	metadata: {
-		start_asset?: string;
-	} | Record<string, never>;
-	realized?: RealizedSwap | Record<string, never>;
-	deposit_vault_salt: string;
-	deposit_vault_address: string;
-	mm_nonce: string;
-	user_destination_address: string;
-	refund_address: string;
-	status: SwapStatus;
-	user_deposit_status?: UserDepositStatus | Record<string, never>;
-	mm_deposit_status?: MMDepositStatus | Record<string, never>;
-	settlement_status?: SettlementStatus | Record<string, never>;
-	latest_refund?: LatestRefund | Record<string, never>;
-	failure_reason?: string | null;
-	failure_at?: string | null;
-	mm_notified_at?: string | null;
-	mm_private_key_sent_at?: string | null;
-	created_at: string;
-	updated_at: string;
+	/** Execution mechanism */
+	action: "btc_transfer";
+	/** Specific step type */
+	kind: BtcTransferKind;
+	/** Bitcoin address to send to */
+	toAddress: string;
+	/** Amount in satoshis */
+	amountSats: U256;
 }
+/**
+* Discriminated union of all execution step types.
+* Discriminate on `action` for execution logic, or `kind` for specific handling.
+*/
+type ExecutionStep = EvmCallStep | BtcTransferStep;
+/**
+* Order response with execution steps that the client must execute.
+*/
+interface OrderResponse {
+	/** The Rift swap/order ID */
+	swapId: string;
+	/** Normalized quote matching /quote response */
+	quote: QuoteResponse;
+	/** Ordered list of steps the client must execute */
+	executionSteps: ExecutionStep[];
+}
+/** Native BTC on Bitcoin */
 declare const BTC: Currency;
+/** cbBTC on Ethereum mainnet */
 declare const CBBTC_ETHEREUM: Currency;
+/** cbBTC on Base */
 declare const CBBTC_BASE: Currency;
+import { treaty } from "@elysiajs/eden";
+import { Elysia } from "elysia";
+declare const app: Elysia;
+declare const appTyped: typeof app;
+type App = typeof appTyped;
+/**
+* Create a type-safe API client for the Rift Swap Router.
+*
+* @param baseUrl - The base URL of the swap router API (e.g., 'https://router-api-v2-production.up.railway.app')
+* @returns A fully typed Eden Treaty client
+*
+* @example
+* ```typescript
+* import { createClient } from '@riftresearch/sdk'
+*
+* const api = createClient('https://router-api-v2-production.up.railway.app')
+*
+* // Get a quote - fully typed request and response
+* const { data: quote, error } = await api.quote.post({
+*   type: 'EXACT_INPUT',
+*   from: {
+*     chain: { kind: 'BITCOIN' },
+*     token: { kind: 'NATIVE', decimals: 8 },
+*   },
+*   to: {
+*     chain: { kind: 'EVM', chainId: 8453 },
+*     token: { kind: 'TOKEN', address: '0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf', decimals: 8 },
+*   },
+*   amount: '100000', // 0.001 BTC in sats
+* })
+*
+* if (error) {
+*   console.error('Failed to get quote:', error)
+*   return
+* }
+*
+* console.log('Quote ID:', quote.id)
+* console.log('You will receive:', quote.to.amount)
+*
+* // Create an order from the quote
+* const { data: order, error: orderError } = await api.order.post({
+*   id: quote.id,
+*   destinationAddress: '0x...',
+*   refundAddress: 'bc1q...',
+* })
+*
+* if (order) {
+*   console.log('Deposit to:', order.deposit_vault_address)
+* }
+*
+* // Check order status
+* const { data: status } = await api.order({ orderId: order.id }).get()
+* ```
+*/
+/** Type of the Rift API client */
+type RiftClient = ReturnType<typeof treaty<App>>;
+declare function createClient(baseUrl: string): RiftClient;
 /**
 * Discriminated union of all possible swap routes.
 *
 * - direct_rift: BTC <-> EVM token (Rift handles directly)
-* - cowswap_then_rift: ERC20 (non-cbBTC) -> BTC (CowSwap to cbBTC, then Rift to BTC)
+* - oneinch_then_rift: ERC20 (non-cbBTC) -> BTC (1inch to cbBTC, then Rift to BTC)
+* - oneinch_monochain: EVM token -> EVM token (single-chain 1inch swap)
 */
 type SwapRoute = {
 	type: "direct_rift";
 	direction: "to_btc" | "from_btc";
 } | {
-	type: "cowswap_then_rift";
+	type: "oneinch_then_rift";
+	evmChainId: number;
+} | {
+	type: "oneinch_monochain";
 	evmChainId: number;
 };
 /**
 * Detect the appropriate swap route based on currency pair.
 *
 * Routes:
-* - EVM token → BTC: direct_rift (to_btc) for cbBTC, cowswap_then_rift for other ERC20s
+* - EVM token → BTC: direct_rift (to_btc) for cbBTC, oneinch_then_rift for other ERC20s
 * - BTC → EVM token: direct_rift (from_btc) - Rift handles all BTC -> EVM swaps directly
+* - EVM token → EVM token (same chain): oneinch_monochain
 */
 declare function detectRoute(from: Currency, to: Currency): SwapRoute;
 interface SupportedModes {
@@ -151,11 +291,11 @@ interface SupportedModes {
 * - cbBTC ↔ BTC: both modes supported
 * - BTC → cbBTC: both modes supported
 * - BTC → ERC20 (non-cbBTC): only exact_input (Rift doesn't support exact_output for chained swaps)
-* - ERC20 → BTC: both modes supported (SDK handles via CowSwap + Rift)
+* - ERC20 → BTC: exact_input only (1inch is exact-input quoting)
 */
 declare function getSupportedModes(from: Currency, to: Currency): SupportedModes;
 import { PublicClient, WalletClient } from "viem";
-type RiftOrder = Swap;
+type RiftOrder = OrderStatusResponse;
 interface TradeParameters {
 	/** The currency to swap from */
 	from: Currency;
@@ -170,58 +310,63 @@ interface TradeParameters {
 	/** Address to receive refunds if swap fails. Defaults to source wallet address */
 	refundAddress?: string;
 	/**
-	* Slippage tolerance for the preswap (CowSwap) leg, in basis points.
+	* Approval amount strategy for ERC20 swaps.
+	* - "full" (default): approve max uint256
+	* - "partial": approve only the sell amount
+	*/
+	approvalMode?: "full" | "partial";
+	/**
+	* Slippage tolerance for the 1inch swap leg, in basis points.
 	* e.g., 50 = 0.5%, 100 = 1%
-	*
-	* If not provided, CowSwap will use auto slippage which suggests an
-	* appropriate value based on the quote and market conditions.
 	*/
 	preswapSlippageBps?: number;
 }
-interface QuoteResult {
+/**
+* Base fields shared by all quote results.
+*/
+interface QuoteResultBase {
 	quoteId: string;
-	from: {
-		currency: Currency;
-		amount: string;
-	};
-	to: {
-		currency: Currency;
-		amount: string;
-	};
-	fees: {
-		protocol: string;
-		liquidity: string;
-		network: string;
-		totalUsd: number;
-	};
+	fees: FeeBreakdown;
 	expiresAt: Date;
 	priceImpact?: number;
 }
+/**
+* Quote result for exact_input mode.
+* User specifies exact input amount, output is calculated with slippage bound.
+*/
+interface ExactInputQuoteResult extends QuoteResultBase {
+	mode: "exact_input";
+	/** The exact input amount specified by the user */
+	from: SpecifiedAmount;
+	/** The calculated output amount with slippage bound */
+	to: CalculatedOutputAmount;
+}
+/**
+* Quote result for exact_output mode.
+* User specifies exact output amount, input is calculated with slippage bound.
+*/
+interface ExactOutputQuoteResult extends QuoteResultBase {
+	mode: "exact_output";
+	/** The calculated input amount with slippage bound */
+	from: CalculatedInputAmount;
+	/** The exact output amount specified by the user */
+	to: SpecifiedAmount;
+}
+/**
+* Discriminated union of quote results.
+* Use `mode` to determine which fields are specified vs calculated.
+*/
+type QuoteResult = ExactInputQuoteResult | ExactOutputQuoteResult;
 interface GetQuoteResult {
 	quote: QuoteResult;
 	executeSwap: () => Promise<SwapResult>;
 }
-/** Raw CowSwap order from the API */
-interface CowSwapOrder {
-	uid: string;
-	status: string;
-	sellToken: string;
-	buyToken: string;
-	sellAmount: string;
-	buyAmount: string;
-	executedSellAmount: string;
-	executedBuyAmount: string;
-	receiver: string;
-	validTo: number;
-	creationDate: string;
-}
 interface SwapResult {
 	swapId: string;
 	status: SwapStatus2;
 	rift: RiftOrder;
-	preswap?: CowSwapOrder;
 }
-type SwapStatus2 = "pending_deposit" | "deposit_detected" | "processing" | "funds_received" | "swapping" | "settling" | "completed" | "failed" | "refunding";
+type SwapStatus2 = OrderStatus;
 /**
 * Function type for sending Bitcoin.
 * Implementers provide this function to handle BTC transactions in their app.
@@ -281,78 +426,26 @@ declare class RiftSdk {
 	*/
 	getQuote(params: TradeParameters): Promise<GetQuoteResult>;
 	/**
-	* Direct cbBTC ↔ BTC swap via Rift only.
-	*/
-	private getDirectRiftQuote;
-	/**
-	* ERC20 → cbBTC (CowSwap) → BTC (Rift)
+	* Execute a single step from the server's execution steps.
+	* Dispatch based on `action` (the execution mechanism).
 	*/
-	private getCowswapThenRiftQuote;
+	private executeStep;
 	/**
-	* exact_input: ERC20 (known) → cbBTC → BTC (calculated)
+	* Execute an EVM call step - send a transaction with calldata.
+	* Handles: approval, transfer_evm, oneinch_swap
 	*/
-	private getCowswapThenRiftExactInput;
+	private executeEvmCallStep;
 	/**
-	* exact_output: ERC20 (calculated) → cbBTC → BTC (known)
+	* Execute a BTC transfer step - send BTC to the vault address.
 	*/
-	private getCowswapThenRiftExactOutput;
-	/**
-	* Execute the CowSwap → Rift swap flow.
-	*
-	* Flow:
-	* 1. Create Rift order first to get deposit vault address
-	* 2. Ensure CowSwap approval for the sell token (skip for native tokens)
-	* 3. Get fresh CowSwap quote with receiver = deposit vault
-	* 4. Post CowSwap order → cbBTC goes directly to Rift vault
-	*/
-	private executeCowswapThenRift;
+	private executeBtcTransferStep;
 	private buildQuoteResult;
-	private buildCombinedQuoteResult;
 	private buildSwapResult;
-	private executeDeposit;
-	private transferErc20;
 	private getAddress;
 	private getRefundAddress;
 	/**
-	* Map API status to SDK status.
-	*
-	* For chained swaps (BTC → non-cbBTC ERC20), the user doesn't receive funds
-	* until settlement is complete, so we use different statuses.
-	*/
-	private mapStatus;
-	/**
 	* Get the current status of a swap by its ID.
-	*
-	* For multi-leg swaps (ERC20 → BTC via CowSwap), returns both
-	* the raw CowSwap order and the raw Rift order.
 	*/
 	getSwapStatus(swapId: string): Promise<SwapResult>;
-	private getCowSwapOrder;
-	private fetchCowSwapOrder;
-	private computeOverallStatus;
 }
-/**
-* URL-safe swap ID encoding/decoding.
-*
-* Format: base64url encoded string containing:
-* - Rift-only: "r|<riftOrderId>" or "r|<riftOrderId>|c" (chained)
-* - CowSwap+Rift: "c|<cowOrderId>|<riftOrderId>"
-*/
-type SwapIdData = {
-	type: "rift";
-	riftOrderId: string;
-	chained?: boolean;
-} | {
-	type: "cowswap_rift";
-	cowOrderId: string;
-	riftOrderId: string;
-};
-/**
-* Encode swap ID data into a URL-safe string.
-*/
-declare function encodeSwapId(data: SwapIdData): string;
-/**
-* Decode a URL-safe swap ID string back to its components.
-*/
-declare function decodeSwapId(encoded: string): SwapIdData;
-export { getSupportedModes, encodeSwapId, detectRoute, decodeSwapId, TradeParameters, TokenIdentifier, SwapStatus2 as SwapStatus, SwapRoute, SwapResult, SwapIdData, SupportedModes, SendBitcoinFn, RiftSdkOptions, RiftSdk, RiftOrder, QuoteResult, NativeToken, GetQuoteResult, EvmChain, Erc20Token, Currency, CowSwapOrder, Chain, CBBTC_ETHEREUM, CBBTC_BASE, BitcoinChain, BTC, SwapStatus as ApiSwapStatus };
+export { getSupportedModes, detectRoute, createClient, TradeParameters, TokenIdentifier, SwapStatus2 as SwapStatus, SwapRoute, SwapResult, SupportedModes, SendBitcoinFn, RiftSdkOptions, RiftSdk, RiftOrder, RiftClient, QuoteResult, OrderResponse, NativeToken, GetQuoteResult, ExecutionStep, ExecutionAction, EvmChain, EvmCallStep, EvmCallKind, Erc20Token, Currency, Chain, CBBTC_ETHEREUM, CBBTC_BASE, BtcTransferStep, BtcTransferKind, BitcoinChain, BTC, App };