@riftresearch/sdk 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 riftresearch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+# rift-sdk
+
+SDK for swapping between bitcoin and evm chains
+
+## Installation
+
+```bash
+bun add rift-sdk
+```
+
+## Usage
+
+```typescript
+import { greet } from 'rift-sdk';
+
+console.log(greet('World')); // Hello, World!
+```
+
+## Contributing
+
+Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for contribution guidelines.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,358 @@
+type U256 = string;
+type BitcoinChain = {
+	kind: "BITCOIN";
+};
+type EvmChain = {
+	kind: "EVM";
+	chainId: number;
+};
+type Chain = BitcoinChain | EvmChain;
+type NativeToken = {
+	kind: "NATIVE";
+	decimals: number;
+};
+type Erc20Token = {
+	kind: "TOKEN";
+	address: string;
+	decimals: number;
+};
+type TokenIdentifier = NativeToken | Erc20Token;
+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;
+	amount: U256;
+	deposit_detected_at: string;
+	confirmations: number;
+	last_checked: string;
+	confirmed_at?: string;
+}
+interface MMDepositStatus {
+	tx_hash: string;
+	amount: U256;
+	deposit_detected_at: string;
+	confirmations: number;
+	last_checked: string;
+}
+interface SettlementStatus {
+	tx_hash: string;
+	broadcast_at: string;
+	confirmations: number;
+	completed_at?: string;
+	fee?: U256;
+}
+interface LatestRefund {
+	timestamp: string;
+	recipient_address: string;
+}
+interface RealizedSwap {
+	user_input: U256;
+	mm_output: U256;
+	protocol_fee: U256;
+	liquidity_fee: U256;
+	network_fee: U256;
+}
+interface SwapRates {
+	liquidity_fee_bps: number;
+	protocol_fee_bps: number;
+	network_fee_sats: number;
+}
+interface SwapFees {
+	liquidity_fee: U256;
+	protocol_fee: U256;
+	network_fee: U256;
+}
+interface LotCurrency {
+	chain: "bitcoin" | "ethereum" | "base" | "solana";
+	token: {
+		type: "Native";
+	} | {
+		type: "Address";
+		data: string;
+	};
+	decimals: number;
+}
+interface Lot {
+	currency: LotCurrency;
+	amount: U256;
+}
+interface SwapQuote {
+	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;
+}
+interface Swap {
+	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;
+}
+declare const BTC: Currency;
+declare const CBBTC_ETHEREUM: Currency;
+declare const CBBTC_BASE: Currency;
+/**
+* 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)
+*/
+type SwapRoute = {
+	type: "direct_rift";
+	direction: "to_btc" | "from_btc";
+} | {
+	type: "cowswap_then_rift";
+	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
+* - BTC → EVM token: direct_rift (from_btc) - Rift handles all BTC -> EVM swaps directly
+*/
+declare function detectRoute(from: Currency, to: Currency): SwapRoute;
+interface SupportedModes {
+	exactInput: boolean;
+	exactOutput: boolean;
+}
+/**
+* Check which trade modes are supported for a given currency pair.
+*
+* - 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)
+*/
+declare function getSupportedModes(from: Currency, to: Currency): SupportedModes;
+import { PublicClient, WalletClient } from "viem";
+type RiftOrder = Swap;
+interface TradeParameters {
+	/** The currency to swap from */
+	from: Currency;
+	/** The currency to swap to */
+	to: Currency;
+	/** Amount in smallest unit (sats for BTC, wei for ETH, etc.) */
+	amount: string;
+	/** Whether amount refers to input or output */
+	mode: "exact_input" | "exact_output";
+	/** Address to receive the output tokens */
+	destinationAddress: string;
+	/** Address to receive refunds if swap fails. Defaults to source wallet address */
+	refundAddress?: string;
+	/**
+	* Slippage tolerance for the preswap (CowSwap) 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 {
+	quoteId: string;
+	from: {
+		currency: Currency;
+		amount: string;
+	};
+	to: {
+		currency: Currency;
+		amount: string;
+	};
+	fees: {
+		protocol: string;
+		liquidity: string;
+		network: string;
+		totalUsd: number;
+	};
+	expiresAt: Date;
+	priceImpact?: number;
+}
+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";
+/**
+* Function type for sending Bitcoin.
+* Implementers provide this function to handle BTC transactions in their app.
+*
+* @example
+* // Using Xverse
+* const sendBitcoin: SendBitcoinFn = async ({ recipient, amountSats }) => {
+*   await Wallet.request('sendTransfer', {
+*     recipients: [{ address: recipient, amount: Number(amountSats) }],
+*   })
+* }
+*
+* @example
+* // Using Leather
+* const sendBitcoin: SendBitcoinFn = async ({ recipient, amountSats }) => {
+*   await window.LeatherProvider.request('sendTransfer', {
+*     recipients: [{ address: recipient, amount: amountSats }],
+*   })
+* }
+*/
+type SendBitcoinFn = (params: {
+	/** Bitcoin address to send to (deposit vault) */
+	recipient: string;
+	/** Amount to send in satoshis */
+	amountSats: string;
+}) => Promise<void>;
+interface RiftSdkOptions {
+	/** Viem PublicClient for reading chain data */
+	publicClient: PublicClient;
+	/** Viem WalletClient for signing and sending transactions */
+	walletClient: WalletClient;
+	/** Function to send Bitcoin (implement using your preferred wallet) */
+	sendBitcoin: SendBitcoinFn;
+	/** Rift API URL. Defaults to production API */
+	apiUrl?: string;
+}
+declare class RiftSdk {
+	private riftClient;
+	private publicClient;
+	private walletClient;
+	private sendBitcoinFn;
+	constructor(options: RiftSdkOptions);
+	/**
+	* Get a quote for a swap and return a function to execute it.
+	*
+	* @example
+	* const { quote, executeSwap } = await sdk.getQuote({
+	*   from: CBBTC_BASE,
+	*   to: BTC,
+	*   amount: '100000000', // 1 cbBTC
+	*   mode: 'exact_input',
+	*   destinationAddress: 'bc1q...',
+	* })
+	*
+	* console.log(`You'll receive: ${quote.to.amount} sats`)
+	* const swap = await executeSwap()
+	*/
+	getQuote(params: TradeParameters): Promise<GetQuoteResult>;
+	/**
+	* Direct cbBTC ↔ BTC swap via Rift only.
+	*/
+	private getDirectRiftQuote;
+	/**
+	* ERC20 → cbBTC (CowSwap) → BTC (Rift)
+	*/
+	private getCowswapThenRiftQuote;
+	/**
+	* exact_input: ERC20 (known) → cbBTC → BTC (calculated)
+	*/
+	private getCowswapThenRiftExactInput;
+	/**
+	* exact_output: ERC20 (calculated) → cbBTC → BTC (known)
+	*/
+	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 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 };