@usewhisk/cctp 0.0.0 → 0.1.1

package/dist/attestation-D52iUV0y.d.cts

@@ -0,0 +1,188 @@
+type Network = "mainnet" | "testnet";
+type Ecosystem = "evm" | "solana" | "stellar" | "starknet";
+/** Assigned by Circle. Mainnet and testnet share a domain; Iris tells them apart by host. */
+type CctpDomain = number;
+type EvmChainId = number;
+type Address = `0x${string}`;
+type SolanaPubkey = string;
+type SolanaCluster = "mainnet-beta" | "devnet";
+/** G (account), M (muxed account) or C (contract). */
+type StellarStrkey = string;
+type StellarNetwork = "public" | "testnet";
+type StarknetNetwork = "mainnet" | "sepolia";
+type StarknetFelt = `0x${string}`;
+/** From Circle's CCTP tables, per chain. */
+interface ChainCapabilities {
+    /** Fast Transfer is offered with this chain as the source. */
+    fastSource: boolean;
+    /** Circle's Forwarding Service can mint on this chain. */
+    forwardingDestination: boolean;
+    /** Iris quotes an upfront fee for burns from this chain. */
+    upfrontFeeSource: boolean;
+    /**
+     * TokenMessengerV2 has `getMinFeeAmount`, which can make a Standard burn
+     * cost more than Iris says. On the other chains the call reverts.
+     */
+    standardFeeSwitch: boolean;
+}
+interface ChainBase {
+    /** Circle App Kit `Blockchain` string, such as "Arc" or "Base_Sepolia". */
+    id: string;
+    label: string;
+    network: Network;
+    cctpDomain: CctpDomain;
+    usdcDecimals: 6 | 7;
+    nativeCurrency: {
+        symbol: string;
+        decimals: number;
+    };
+    defaultRpcUrls: readonly string[];
+    explorerUrl: string;
+    /** Appended to explorer links, for explorers that serve several networks. */
+    explorerQuery?: string;
+    capabilities: ChainCapabilities;
+}
+interface EvmChain extends ChainBase {
+    ecosystem: "evm";
+    evmChainId: EvmChainId;
+    usdc: Address;
+    tokenMessenger: Address;
+    messageTransmitter: Address;
+    /** Present exactly when `capabilities.upfrontFeeSource` is true. */
+    tokenMessengerWithFees?: Address;
+}
+interface SolanaChain extends ChainBase {
+    ecosystem: "solana";
+    cluster: SolanaCluster;
+    usdc: SolanaPubkey;
+    /** Solana merges TokenMessenger and TokenMinter into one program. */
+    tokenMessengerMinter: SolanaPubkey;
+    messageTransmitter: SolanaPubkey;
+}
+interface StellarChain extends ChainBase {
+    ecosystem: "stellar";
+    stellarNetwork: StellarNetwork;
+    networkPassphrase: string;
+    usdcIssuer: StellarStrkey;
+    /** The USDC Stellar Asset Contract, derived from the issuer and passphrase. */
+    usdc: StellarStrkey;
+    tokenMessengerMinter: StellarStrkey;
+    messageTransmitter: StellarStrkey;
+    /**
+     * Every burn to Stellar must name this contract as both `mintRecipient` and
+     * `destinationCaller`, with the real recipient in hookData. A user key as
+     * `mintRecipient` loses the funds.
+     */
+    cctpForwarder: StellarStrkey;
+}
+interface StarknetChain extends ChainBase {
+    ecosystem: "starknet";
+    starknetNetwork: StarknetNetwork;
+    /** Shortstring felt, such as `SN_SEPOLIA`, that wallets check when signing. */
+    chainId: StarknetFelt;
+    usdc: StarknetFelt;
+    tokenMessengerMinter: StarknetFelt;
+    messageTransmitter: StarknetFelt;
+}
+type CctpChain = EvmChain | SolanaChain | StellarChain | StarknetChain;
+
+/** Fast Transfer attests after a block or two, before hard finality. */
+declare const FINALITY_FAST: 1000;
+/** Standard Transfer attests after hard finality. */
+declare const FINALITY_STANDARD: 2000;
+type FinalityThreshold = typeof FINALITY_FAST | typeof FINALITY_STANDARD;
+type TransferSpeed = "fast" | "standard";
+/**
+ * Forwarder fee levels returned per finality level, in USDC subunits.
+ * Circle recommends `med` or higher.
+ */
+type ForwarderFeeTier = {
+    low: bigint;
+    med: bigint;
+    high: bigint;
+};
+/**
+ * A Fast or Standard row of the `/v2/burn/USDC/fees/{src}/{dst}` response, parsed.
+ *
+ * `minimumFee` is in hundredths of a basis point: Iris's `1.3` is `130n`.
+ * `forwardFee` is present only when `?forward=true` is set on the request.
+ */
+type BurnFeeTier = {
+    finalityThreshold: FinalityThreshold;
+    minimumFee: bigint;
+    forwardFee?: ForwarderFeeTier;
+};
+/** Iris never reports a failed attestation; a slow one stays pending. */
+type IrisAttestationStatus = "pending_confirmations" | "complete";
+/** Why a message is slower than asked. None of these is a failure. */
+type IrisDelayReason = "insufficient_fee" | "amount_above_max" | "insufficient_allowance_available";
+/**
+ * Circle Orbit forwarder lifecycle status. Present only when the burn
+ * was triggered with the forwarder hookData.
+ *
+ * - `PENDING`: relayer is processing.
+ * - `CONFIRMED`: relayer submitted the mint, waiting on finality.
+ * - `COMPLETE`: mint finalized.
+ * - `FAILED`: relayer rejected; fall back to manual mint.
+ */
+type ForwardState = "PENDING" | "CONFIRMED" | "COMPLETE" | "FAILED";
+/**
+ * Single message returned by `/v2/messages/{srcDomain}`.
+ */
+type IrisMessage = {
+    /** Raw 0x-prefixed CCTP message bytes; pass to receiveMessage. */
+    message: `0x${string}`;
+    /** Raw 0x-prefixed attestation bytes; pass to receiveMessage. */
+    attestation: `0x${string}`;
+    /** Decimal string. */
+    eventNonce: string;
+    status: IrisAttestationStatus;
+    cctpVersion: 2;
+    /** Present when burn included forwarder hookData. */
+    forwardState?: ForwardState | null;
+    /** Destination tx hash when forwardState is CONFIRMED or COMPLETE. */
+    forwardTxHash?: string | null;
+    delayReason?: IrisDelayReason | null;
+    /** Decoded message and message body, if Iris can decode them. */
+    decodedMessage?: {
+        sourceDomain: string;
+        destinationDomain: string;
+        nonce: `0x${string}`;
+        sender: string | null;
+        recipient: string | null;
+        destinationCaller: string | null;
+        minFinalityThreshold: string;
+        finalityThresholdExecuted: string;
+        messageBody: `0x${string}`;
+        decodedMessageBody?: {
+            burnToken: string | null;
+            mintRecipient: string | null;
+            amount: string;
+            messageSender: string | null;
+            maxFee: string;
+            feeExecuted: string;
+            expirationBlock: string;
+            hookData: `0x${string}` | null;
+        };
+    };
+};
+type IrisMessagesResponse = {
+    messages: IrisMessage[];
+};
+/**
+ * Filters for getMessages. Pass at least one of `transactionHash` or `nonce`.
+ */
+type GetMessagesQuery = {
+    sourceDomain: CctpDomain;
+    transactionHash?: string;
+    nonce?: string;
+};
+
+type SecondsRange = {
+    min: number;
+    max: number;
+};
+/** How long Circle takes to attest a burn from `chain`. The mint comes after. */
+declare function attestationSeconds(chain: CctpChain, speed: TransferSpeed): SecondsRange;
+
+export { type Address as A, type BurnFeeTier as B, type CctpChain as C, type EvmChain as E, type ForwarderFeeTier as F, type GetMessagesQuery as G, type IrisAttestationStatus as I, type Network as N, type StarknetChain as S, type TransferSpeed as T, type StellarChain as a, type FinalityThreshold as b, type StarknetFelt as c, type SolanaChain as d, type CctpDomain as e, type ChainCapabilities as f, type Ecosystem as g, type EvmChainId as h, FINALITY_FAST as i, FINALITY_STANDARD as j, type ForwardState as k, type IrisDelayReason as l, type IrisMessage as m, type IrisMessagesResponse as n, type SecondsRange as o, type SolanaCluster as p, type SolanaPubkey as q, type StarknetNetwork as r, type StellarNetwork as s, type StellarStrkey as t, attestationSeconds as u };

package/dist/attestation-D52iUV0y.d.ts

@@ -0,0 +1,188 @@
+type Network = "mainnet" | "testnet";
+type Ecosystem = "evm" | "solana" | "stellar" | "starknet";
+/** Assigned by Circle. Mainnet and testnet share a domain; Iris tells them apart by host. */
+type CctpDomain = number;
+type EvmChainId = number;
+type Address = `0x${string}`;
+type SolanaPubkey = string;
+type SolanaCluster = "mainnet-beta" | "devnet";
+/** G (account), M (muxed account) or C (contract). */
+type StellarStrkey = string;
+type StellarNetwork = "public" | "testnet";
+type StarknetNetwork = "mainnet" | "sepolia";
+type StarknetFelt = `0x${string}`;
+/** From Circle's CCTP tables, per chain. */
+interface ChainCapabilities {
+    /** Fast Transfer is offered with this chain as the source. */
+    fastSource: boolean;
+    /** Circle's Forwarding Service can mint on this chain. */
+    forwardingDestination: boolean;
+    /** Iris quotes an upfront fee for burns from this chain. */
+    upfrontFeeSource: boolean;
+    /**
+     * TokenMessengerV2 has `getMinFeeAmount`, which can make a Standard burn
+     * cost more than Iris says. On the other chains the call reverts.
+     */
+    standardFeeSwitch: boolean;
+}
+interface ChainBase {
+    /** Circle App Kit `Blockchain` string, such as "Arc" or "Base_Sepolia". */
+    id: string;
+    label: string;
+    network: Network;
+    cctpDomain: CctpDomain;
+    usdcDecimals: 6 | 7;
+    nativeCurrency: {
+        symbol: string;
+        decimals: number;
+    };
+    defaultRpcUrls: readonly string[];
+    explorerUrl: string;
+    /** Appended to explorer links, for explorers that serve several networks. */
+    explorerQuery?: string;
+    capabilities: ChainCapabilities;
+}
+interface EvmChain extends ChainBase {
+    ecosystem: "evm";
+    evmChainId: EvmChainId;
+    usdc: Address;
+    tokenMessenger: Address;
+    messageTransmitter: Address;
+    /** Present exactly when `capabilities.upfrontFeeSource` is true. */
+    tokenMessengerWithFees?: Address;
+}
+interface SolanaChain extends ChainBase {
+    ecosystem: "solana";
+    cluster: SolanaCluster;
+    usdc: SolanaPubkey;
+    /** Solana merges TokenMessenger and TokenMinter into one program. */
+    tokenMessengerMinter: SolanaPubkey;
+    messageTransmitter: SolanaPubkey;
+}
+interface StellarChain extends ChainBase {
+    ecosystem: "stellar";
+    stellarNetwork: StellarNetwork;
+    networkPassphrase: string;
+    usdcIssuer: StellarStrkey;
+    /** The USDC Stellar Asset Contract, derived from the issuer and passphrase. */
+    usdc: StellarStrkey;
+    tokenMessengerMinter: StellarStrkey;
+    messageTransmitter: StellarStrkey;
+    /**
+     * Every burn to Stellar must name this contract as both `mintRecipient` and
+     * `destinationCaller`, with the real recipient in hookData. A user key as
+     * `mintRecipient` loses the funds.
+     */
+    cctpForwarder: StellarStrkey;
+}
+interface StarknetChain extends ChainBase {
+    ecosystem: "starknet";
+    starknetNetwork: StarknetNetwork;
+    /** Shortstring felt, such as `SN_SEPOLIA`, that wallets check when signing. */
+    chainId: StarknetFelt;
+    usdc: StarknetFelt;
+    tokenMessengerMinter: StarknetFelt;
+    messageTransmitter: StarknetFelt;
+}
+type CctpChain = EvmChain | SolanaChain | StellarChain | StarknetChain;
+
+/** Fast Transfer attests after a block or two, before hard finality. */
+declare const FINALITY_FAST: 1000;
+/** Standard Transfer attests after hard finality. */
+declare const FINALITY_STANDARD: 2000;
+type FinalityThreshold = typeof FINALITY_FAST | typeof FINALITY_STANDARD;
+type TransferSpeed = "fast" | "standard";
+/**
+ * Forwarder fee levels returned per finality level, in USDC subunits.
+ * Circle recommends `med` or higher.
+ */
+type ForwarderFeeTier = {
+    low: bigint;
+    med: bigint;
+    high: bigint;
+};
+/**
+ * A Fast or Standard row of the `/v2/burn/USDC/fees/{src}/{dst}` response, parsed.
+ *
+ * `minimumFee` is in hundredths of a basis point: Iris's `1.3` is `130n`.
+ * `forwardFee` is present only when `?forward=true` is set on the request.
+ */
+type BurnFeeTier = {
+    finalityThreshold: FinalityThreshold;
+    minimumFee: bigint;
+    forwardFee?: ForwarderFeeTier;
+};
+/** Iris never reports a failed attestation; a slow one stays pending. */
+type IrisAttestationStatus = "pending_confirmations" | "complete";
+/** Why a message is slower than asked. None of these is a failure. */
+type IrisDelayReason = "insufficient_fee" | "amount_above_max" | "insufficient_allowance_available";
+/**
+ * Circle Orbit forwarder lifecycle status. Present only when the burn
+ * was triggered with the forwarder hookData.
+ *
+ * - `PENDING`: relayer is processing.
+ * - `CONFIRMED`: relayer submitted the mint, waiting on finality.
+ * - `COMPLETE`: mint finalized.
+ * - `FAILED`: relayer rejected; fall back to manual mint.
+ */
+type ForwardState = "PENDING" | "CONFIRMED" | "COMPLETE" | "FAILED";
+/**
+ * Single message returned by `/v2/messages/{srcDomain}`.
+ */
+type IrisMessage = {
+    /** Raw 0x-prefixed CCTP message bytes; pass to receiveMessage. */
+    message: `0x${string}`;
+    /** Raw 0x-prefixed attestation bytes; pass to receiveMessage. */
+    attestation: `0x${string}`;
+    /** Decimal string. */
+    eventNonce: string;
+    status: IrisAttestationStatus;
+    cctpVersion: 2;
+    /** Present when burn included forwarder hookData. */
+    forwardState?: ForwardState | null;
+    /** Destination tx hash when forwardState is CONFIRMED or COMPLETE. */
+    forwardTxHash?: string | null;
+    delayReason?: IrisDelayReason | null;
+    /** Decoded message and message body, if Iris can decode them. */
+    decodedMessage?: {
+        sourceDomain: string;
+        destinationDomain: string;
+        nonce: `0x${string}`;
+        sender: string | null;
+        recipient: string | null;
+        destinationCaller: string | null;
+        minFinalityThreshold: string;
+        finalityThresholdExecuted: string;
+        messageBody: `0x${string}`;
+        decodedMessageBody?: {
+            burnToken: string | null;
+            mintRecipient: string | null;
+            amount: string;
+            messageSender: string | null;
+            maxFee: string;
+            feeExecuted: string;
+            expirationBlock: string;
+            hookData: `0x${string}` | null;
+        };
+    };
+};
+type IrisMessagesResponse = {
+    messages: IrisMessage[];
+};
+/**
+ * Filters for getMessages. Pass at least one of `transactionHash` or `nonce`.
+ */
+type GetMessagesQuery = {
+    sourceDomain: CctpDomain;
+    transactionHash?: string;
+    nonce?: string;
+};
+
+type SecondsRange = {
+    min: number;
+    max: number;
+};
+/** How long Circle takes to attest a burn from `chain`. The mint comes after. */
+declare function attestationSeconds(chain: CctpChain, speed: TransferSpeed): SecondsRange;
+
+export { type Address as A, type BurnFeeTier as B, type CctpChain as C, type EvmChain as E, type ForwarderFeeTier as F, type GetMessagesQuery as G, type IrisAttestationStatus as I, type Network as N, type StarknetChain as S, type TransferSpeed as T, type StellarChain as a, type FinalityThreshold as b, type StarknetFelt as c, type SolanaChain as d, type CctpDomain as e, type ChainCapabilities as f, type Ecosystem as g, type EvmChainId as h, FINALITY_FAST as i, FINALITY_STANDARD as j, type ForwardState as k, type IrisDelayReason as l, type IrisMessage as m, type IrisMessagesResponse as n, type SecondsRange as o, type SolanaCluster as p, type SolanaPubkey as q, type StarknetNetwork as r, type StellarNetwork as s, type StellarStrkey as t, attestationSeconds as u };