@stableflow/bridges 0.0.0-experimental-5a8afd7389-20260703

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StableFlow AI
+
+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,65 @@
+# @stableflow/bridges
+
+StableFlow bridge services: OneClick, CCTP, USDT0, FraxZero, Native, and composite routes.
+
+## Installation
+
+```bash
+pnpm add @stableflow/bridges @stableflow/core
+```
+
+Also install the wallet adapter(s) for the chains you support (e.g. `@stableflow/wallet-evm`).
+
+## When to use
+
+Use this package when you need:
+
+- **Multi-route quotes** across all supported bridge services (`BridgeSFA.getAllQuote`)
+- **Unified send and status** for a selected route (`BridgeSFA.send`, `BridgeSFA.getStatus`)
+- Low-level access to individual bridge implementations via `ServiceMap`
+
+For HTTP-only quote/status without wallet orchestration, [`@stableflow/core`](../core/README.md) `SFA` may be enough.
+
+## Main exports
+
+| Export | Description |
+|--------|-------------|
+| `BridgeSFA` | Multi-route quote, send, and status |
+| `GetAllQuoteParams` | Parameters for `getAllQuote` |
+| `ServiceMap` | Per-service `quote` / `send` / `getStatus` implementations |
+| `getQuoteModes` | Helpers to interpret quote shape (OneClick, exact output, etc.) |
+| Utilities | `formatQuoteError`, `addressToBytes32`, `quoteSignature`, `formatNumber` |
+| USDT0 / FraxZero | `USDT0_CONFIG`, `OFT_ABI`, `getHopMsgFee`, `FRAXZERO_MIDDLE_TOKEN_*`, … |
+
+Supported `Service` values (from `@stableflow/core`): `oneclick`, `usdt0`, `cctp`, `fraxzero`, composite routes (`usdt0-oneclick`, `oneclick-usdt0`, `fraxzero-oneclick`, `oneclick-fraxzero`), and `native`.
+
+See `dist/index.d.ts` after `pnpm build`.
+
+## Quick example
+
+```ts
+import { BridgeSFA } from '@stableflow/bridges';
+import { EVMWallet } from '@stableflow/wallet-evm';
+
+const wallet = new EVMWallet(/* provider */);
+
+const results = await BridgeSFA.getAllQuote({
+  dry: true, // fast comparison; use dry: false before send
+  prices: { ETH: '3000', BNB: '900' },
+  fromToken,
+  toToken,
+  wallet: wallet.wallet,
+  recipient: '0x...',
+  refundTo: '0x...',
+  amountWei: '1000000',
+  slippageTolerance: 0.5,
+});
+
+const txHash = await BridgeSFA.send(serviceType, { wallet: wallet.wallet, quote });
+const status = await BridgeSFA.getStatus(serviceType, { quote, hash: txHash });
+```
+
+## See also
+
+- [Developer Guide](../../DEVELOPER_GUIDE.md) — `dry` flag, wallet integration, Hyperliquid
+- [@stableflow/core](../core/README.md)

package/dist/index.d.mts

@@ -0,0 +1,323 @@
+import * as _stableflow_core from '@stableflow/core';
+import { Service, TokenConfig, WalletConfig, CancelablePromise, SubmitDepositTxResponse, TransactionStatus } from '@stableflow/core';
+import Big from 'big.js';
+
+declare const ServiceMap: Record<Service, any>;
+
+/**
+ * Serializable, unsigned EVM transaction data.
+ *
+ * This is what an API-driven custody integrator (e.g. an MPC wallet such as
+ * Fireblocks) receives. Stableflow builds the calldata; the integrator signs
+ * and broadcasts it through their own infrastructure, then reports the
+ * resulting hash back via `BridgeSFA.report`.
+ */
+interface EvmTxData {
+    chainId: number;
+    from: string;
+    to: string;
+    /** Hex-encoded calldata. `0x` for a plain native-token transfer. */
+    data: string;
+    /** Native token amount in wei, as a decimal string. */
+    value: string;
+    /** Optional gas limit as a decimal string. */
+    gasLimit?: string;
+}
+/**
+ * EIP-712 typed data for an ERC20 `Permit`, returned unsigned so an external
+ * signer (MPC/Fireblocks) can produce the signature. Nothing is signed or
+ * verified inside the SDK for this payload.
+ */
+interface PermitTypedData {
+    domain: {
+        name: string;
+        version: string;
+        chainId: number;
+        verifyingContract: string;
+    };
+    types: Record<string, Array<{
+        name: string;
+        type: string;
+    }>>;
+    values: {
+        owner: string;
+        spender: string;
+        value: string;
+        nonce: string;
+        deadline: number;
+    };
+    deadline: number;
+    nonce: number;
+    token: string;
+    spender: string;
+    owner: string;
+}
+/**
+ * Result of `BridgeSFA.buildTransaction`.
+ *
+ * Depending on the route, the integrator may need to: broadcast `approveTx`
+ * (optionally `approveResetTx` first on Ethereum), sign `permitTypedData`,
+ * and always broadcast the main `tx`. See `BridgeSFA.buildTransaction`.
+ */
+interface BuildTransactionResult {
+    chainId: number;
+    from: string;
+    /** Present when `quote.needApprove === true`. */
+    approveTx?: EvmTxData;
+    /**
+     * Present when `quote.needApprove === true` and the source chain is Ethereum.
+     * Some Ethereum tokens (e.g. USDT) require resetting the allowance to 0
+     * before setting a new non-zero allowance.
+     */
+    approveResetTx?: EvmTxData;
+    /** Present when `quote.needPermit === true`. Must be signed off-chain. */
+    permitTypedData?: PermitTypedData;
+    /** The main source-chain transaction to sign and broadcast. */
+    tx: EvmTxData;
+}
+/**
+ * Build the main unsigned source-chain transaction from a quote, mirroring the
+ * branching in `BridgeSFA.send` but producing serializable calldata instead of
+ * signing/broadcasting.
+ */
+declare const buildSendTx: (serviceType: Service, quote: any) => EvmTxData;
+/**
+ * Build the ERC20 approve transaction(s) for a quote that requires approval.
+ * On Ethereum an additional `approveResetTx` (approve 0) is returned so the
+ * integrator can reset a stale allowance before setting a new one.
+ */
+declare const buildApproveTx: (serviceType: Service, quote: any) => {
+    approveTx?: EvmTxData;
+    approveResetTx?: EvmTxData;
+};
+/**
+ * Build the EIP-712 `Permit` typed data for a permit-required route, returned
+ * unsigned. The integrator signs it with their MPC/Fireblocks signer, splits
+ * the signature into `v/r/s`, and passes the assembled `permitSignature` to
+ * `BridgeSFA.report`.
+ */
+declare const buildPermitTypedData: (params: {
+    permitToken: TokenConfig;
+    permitAmountWei: string;
+    permitSpender: string;
+    owner: string;
+}) => Promise<PermitTypedData>;
+
+/**
+ * Normalized ERC20 permit signature passed to `BridgeSFA.send` / `BridgeSFA.report`
+ * when a route requires a permit (`quote.needPermit === true`).
+ */
+interface PermitSignature {
+    amount: string;
+    deadline: number;
+    nonce: string;
+    owner: string;
+    r: string;
+    s: string;
+    v: 27 | 28;
+}
+interface GetAllQuoteParams {
+    singleService?: Service;
+    disabledServices?: Service[];
+    dry?: boolean;
+    prices: Record<string, string>;
+    fromToken: TokenConfig;
+    toToken: TokenConfig;
+    wallet: WalletConfig;
+    evmWallet?: WalletConfig | null;
+    evmAddress?: string | null;
+    recipient: string;
+    refundTo: string;
+    amountWei: string;
+    slippageTolerance: number;
+    minInputAmount?: string;
+    /** @deprecated Please migrate to oneclickParams */
+    appFees?: {
+        recipient: string;
+        fee: number;
+    }[];
+    oneclickParams?: {
+        appFees?: {
+            recipient: string;
+            fee: number;
+        }[];
+        swapType?: "EXACT_INPUT" | "EXACT_OUTPUT" | "FLEX_INPUT";
+        isProxy?: boolean;
+    };
+}
+/**
+ * Full cross-chain bridge API (multi-route quote, send, status).
+ * Install `@stableflow/bridges` alongside `@stableflow/core`.
+ */
+declare class BridgeSFA {
+    static getAllQuote(params: GetAllQuoteParams): Promise<Array<{
+        serviceType: Service;
+        quote?: any;
+        error?: string;
+    }>>;
+    static send(serviceType: Service, params: {
+        wallet: any;
+        quote: any;
+        permitSignature?: PermitSignature;
+    }): Promise<string>;
+    /**
+     * Build the backend report payload for a submitted source-chain transaction.
+     * Shared by `send` (fire-and-forget) and `report` (awaited).
+     */
+    private static buildReportData;
+    /**
+     * API-driven custody: build the serializable, unsigned transaction data for a
+     * route WITHOUT a signer. Intended for MPC wallets (e.g. Fireblocks) that sign
+     * and broadcast through their own infrastructure.
+     *
+     * Returns any required `approveTx` (and `approveResetTx` on Ethereum), the
+     * `permitTypedData` to sign off-chain when `quote.needPermit`, and the main
+     * `tx`. After the integrator broadcasts `tx`, call `BridgeSFA.report` with the
+     * resulting hash (and the permit signature, if any) so StableFlow can execute
+     * the destination leg.
+     *
+     * EVM only for now; non-EVM source chains throw.
+     */
+    static buildTransaction(serviceType: Service, params: {
+        quote: any;
+    }): Promise<BuildTransactionResult>;
+    /**
+     * API-driven custody: report an externally signed & broadcast source-chain
+     * transaction back to StableFlow so it can track and execute the destination
+     * leg. Pair with `BridgeSFA.buildTransaction`.
+     *
+     * When `quote.needPermit === true`, `permitSignature` is required.
+     */
+    static report(serviceType: Service, params: {
+        quote: any;
+        hash: string;
+        permitSignature?: PermitSignature;
+    }): CancelablePromise<SubmitDepositTxResponse>;
+    static getStatus(serviceType: Service, params: {
+        quote: any;
+        hash: string;
+    }): Promise<{
+        status: TransactionStatus;
+        toChainTxHash?: string;
+    }>;
+}
+
+interface LayerZeroChainConfig {
+    eid: number;
+    chainKey: string;
+    blockTime: number;
+}
+
+declare const getQuoteModes: (params: {
+    quoteData?: any;
+    bridgeStore?: {
+        quoteDataService: Service;
+    };
+}) => {
+    isExactOutput: boolean;
+    isOneClickService: boolean;
+    isQuoteParamDepositAddress: boolean;
+    isPermitWithNonce: boolean;
+};
+
+declare function addressToBytes32(chainType: string, address: string): string;
+
+declare const formatQuoteError: (error: any, options: {
+    service: Service;
+    fromToken: TokenConfig;
+}) => {
+    serviceType: "oneclick";
+    error: string;
+} | {
+    serviceType: "usdt0" | "cctp" | "fraxzero" | "fraxzero-oneclick" | "oneclick-fraxzero" | "usdt0-oneclick" | "oneclick-usdt0" | "native";
+    error: any;
+};
+
+declare function quoteSignature(params: any): Promise<any>;
+
+declare const formatNumber: (value: string | number | Big.Big | undefined, precision: number, isSimple?: boolean, options?: {
+    prefix?: string;
+    isLTIntegerZero?: boolean;
+    isZeroPrecision?: boolean;
+    isShort?: boolean;
+    isShortUppercase?: boolean;
+    round?: Big.RoundingMode;
+    isLessPrecision?: boolean;
+}) => any;
+
+declare const getHopMsgFee: (params: any) => Promise<bigint>;
+
+interface Usdt0Config extends LayerZeroChainConfig {
+    contractAddress: string;
+    oft?: string;
+    oftLegacy?: string;
+    oftMultiHopComposer?: string;
+    oftTetherTokenOFTExtension?: string;
+    confirmations: number;
+    lzReceiveOptionGas: number;
+    lzReceiveOptionGasLegacy: number;
+    composeOptionGas?: number;
+    oftApprovalRequired?: boolean;
+    oftLegacyApprovalRequired?: boolean;
+}
+declare const USDT0_CONFIG: Record<string, Usdt0Config>;
+declare const LZ_RECEIVE_VALUE: Record<string, any>;
+declare const USDT0_LEGACY_MESH_TRANSFTER_FEE = 0.0003;
+declare const DATA_HEX_PROTOBUF_EXTRA = 3;
+declare const SIGNATURE_SIZE = 67;
+
+declare const OFT_ABI: ({
+    inputs: never[];
+    name: string;
+    outputs: {
+        internalType: string;
+        name: string;
+        type: string;
+    }[];
+    stateMutability: string;
+    type: string;
+} | {
+    inputs: ({
+        components: {
+            internalType: string;
+            name: string;
+            type: string;
+        }[];
+        internalType: string;
+        name: string;
+        type: string;
+    } | {
+        internalType: string;
+        name: string;
+        type: string;
+        components?: undefined;
+    })[];
+    name: string;
+    outputs: {
+        components: ({
+            internalType: string;
+            name: string;
+            type: string;
+            components?: undefined;
+        } | {
+            components: {
+                internalType: string;
+                name: string;
+                type: string;
+            }[];
+            internalType: string;
+            name: string;
+            type: string;
+        })[];
+        internalType: string;
+        name: string;
+        type: string;
+    }[];
+    stateMutability: string;
+    type: string;
+})[];
+
+declare const FRAXZERO_MIDDLE_TOKEN_USDC: _stableflow_core.TokenConfig;
+declare const FRAXZERO_MIDDLE_TOKEN_FRXUSD: _stableflow_core.TokenConfig;
+
+export { BridgeSFA, type BuildTransactionResult, DATA_HEX_PROTOBUF_EXTRA, type EvmTxData, FRAXZERO_MIDDLE_TOKEN_FRXUSD, FRAXZERO_MIDDLE_TOKEN_USDC, type GetAllQuoteParams, LZ_RECEIVE_VALUE, OFT_ABI, type PermitSignature, type PermitTypedData, SIGNATURE_SIZE, ServiceMap, USDT0_CONFIG, USDT0_LEGACY_MESH_TRANSFTER_FEE, addressToBytes32, buildApproveTx, buildPermitTypedData, buildSendTx, formatNumber, formatQuoteError, getHopMsgFee, getQuoteModes, quoteSignature };