@ar.io/sdk 3.24.0 → 4.0.0-solana.10

package/lib/types/solana/escrow.d.ts

@@ -0,0 +1,403 @@
+/**
+ * Solana ANT-escrow and Token-escrow clients — `ario-ant-escrow` program.
+ *
+ * ANTEscrow holds a Metaplex Core ANT NFT in trustless custody and
+ * releases it after on-chain verification of an Arweave RSA-PSS-4096 or
+ * Ethereum ECDSA signature over a canonical claim message.
+ *
+ * TokenEscrow holds ARIO SPL tokens (liquid or vaulted) in trustless
+ * custody with the same multi-protocol claim flow.
+ *
+ * Design: `docs/ANT_ESCROW_DESIGN.md` (account model, canonical message
+ * format, threat model). Plan: `docs/ANT_ESCROW_IMPLEMENTATION_PLAN.md`.
+ *
+ * All instruction encoding is delegated to the Codama-generated builders
+ * in `./generated/ant-escrow/instructions/` — they own the discriminator,
+ * Borsh codec, and account-meta wiring derived from the on-chain IDL.
+ */
+import { type Address, type Commitment, type Instruction, type TransactionSigner } from '@solana/kit';
+import type { ILogger } from '../common/logger.js';
+import type { SolanaRpc, SolanaRpcSubscriptions } from './types.js';
+export type EscrowProtocol = 'arweave' | 'ethereum';
+export interface EscrowAntState {
+    version: number;
+    bump: number;
+    depositor: Address;
+    antMint: Address;
+    recipientProtocol: EscrowProtocol;
+    recipientPubkey: Uint8Array;
+    nonce: Uint8Array;
+    depositSlot: bigint;
+}
+export interface ANTEscrowConfig {
+    rpc: SolanaRpc;
+    rpcSubscriptions?: SolanaRpcSubscriptions;
+    signer?: TransactionSigner;
+    programId?: Address;
+    /**
+     * ario-core program id, used by `TokenEscrow` to build the sibling
+     * `vaulted_transfer` instruction when claiming an active (still-locked)
+     * vault escrow. Defaults to {@link ARIO_CORE_PROGRAM_ID}.
+     */
+    coreProgram?: Address;
+    commitment?: Commitment;
+    logger?: ILogger;
+}
+/**
+ * Solana-backed client for the trustless ANT-escrow program. All write
+ * methods require both `rpcSubscriptions` and `signer`; read methods
+ * only need `rpc`.
+ */
+export declare class ANTEscrow {
+    protected readonly rpc: SolanaRpc;
+    protected readonly rpcSubscriptions?: SolanaRpcSubscriptions;
+    protected readonly signer?: TransactionSigner;
+    readonly programId: Address;
+    protected readonly commitment: Commitment;
+    protected readonly logger: ILogger;
+    constructor(config: ANTEscrowConfig);
+    static init(config: ANTEscrowConfig): ANTEscrow;
+    /** Fetch the on-chain `EscrowAnt` for an ANT mint, or `null` if no
+     *  active escrow exists. Uses the Codama-generated decoder. */
+    get(antMint: Address): Promise<EscrowAntState | null>;
+    /** Address of the EscrowAnt PDA for an ANT mint (no RPC call). */
+    getPda(antMint: Address): Promise<Address>;
+    /**
+     * Lock an ANT into escrow. The signer (depositor) must currently own
+     * the asset; mpl-core's TransferV1 CPI enforces this.
+     *
+     * `recipient.publicKey` length must match `recipient.protocol`:
+     * - `'arweave'` → 512-byte RSA-4096 modulus (the JWK `n` field)
+     * - `'ethereum'` → 20-byte address
+     */
+    deposit(args: {
+        antMint: Address;
+        recipient: {
+            protocol: EscrowProtocol;
+            publicKey: Uint8Array;
+        };
+    }): Promise<string>;
+    depositIx(args: {
+        antMint: Address;
+        recipient: {
+            protocol: EscrowProtocol;
+            publicKey: Uint8Array;
+        };
+    }, depositor: TransactionSigner): Promise<Instruction>;
+    /**
+     * Re-target the escrow at a new recipient identity. Rotates the
+     * on-chain nonce, invalidating any in-flight claim signatures bound
+     * to the prior recipient.
+     */
+    updateRecipient(args: {
+        antMint: Address;
+        newRecipient: {
+            protocol: EscrowProtocol;
+            publicKey: Uint8Array;
+        };
+    }): Promise<string>;
+    /**
+     * Pull an escrowed ANT back to the depositor. Closes the escrow PDA
+     * and refunds rent.
+     */
+    cancel(args: {
+        antMint: Address;
+    }): Promise<string>;
+    /**
+     * Submit an Arweave RSA-PSS-4096 signature to release the ANT.
+     * Anyone can submit (the fee payer = `signer`); only `claimant`
+     * receives the ANT, and only the original `depositor` receives rent.
+     */
+    claimArweave(args: {
+        antMint: Address;
+        claimant: Address;
+        signature: Uint8Array;
+        saltLen?: number;
+    }): Promise<string>;
+    /**
+     * Build the ANT-claim-via-Arweave-attested instruction.
+     *
+     * **API note**: this method previously took user-side RSA-PSS params
+     * (`signature`, `saltLen`, `messageNonce`). The on-chain ix was
+     * renamed to `claim_ant_arweave_attested` (canonical contracts
+     * `ar-io-solana-contracts` PR-19+): verification is now via
+     * instruction-introspection of a preceding Ed25519 sigverify ix
+     * issued by the off-chain attestor (see
+     * `migration/attestor/`). Those data args are no longer fed to the
+     * builder. Callers MUST prepend the attestor's sigverify ix to the
+     * transaction or it will fail on-chain. A higher-level helper that
+     * fetches the attestor's signature and assembles the full tx is
+     * tracked as a follow-up.
+     *
+     * @deprecated Args `signature`, `saltLen`, `messageNonce` are
+     * ignored. Use the new attested flow.
+     */
+    claimArweaveIx(args: {
+        antMint: Address;
+        claimant: Address;
+        /** @deprecated unused — superseded by attestor sigverify ix */
+        signature?: Uint8Array;
+        /** @deprecated unused — superseded by attestor sigverify ix */
+        saltLen?: number;
+        depositor: Address;
+        /** 32-byte nonce from the on-chain Escrow PDA; still part of the
+         *  canonical claim payload that the attestor signs. */
+        messageNonce: Uint8Array;
+    }): Promise<Instruction>;
+    /** Submit an Ethereum ECDSA secp256k1 + EIP-191 signature. */
+    claimEthereum(args: {
+        antMint: Address;
+        claimant: Address;
+        signature: Uint8Array;
+    }): Promise<string>;
+    claimEthereumIx(args: {
+        antMint: Address;
+        claimant: Address;
+        signature: Uint8Array;
+        depositor: Address;
+        messageNonce: Uint8Array;
+    }): Promise<Instruction>;
+    private send;
+    private requireSigner;
+    private requireEscrow;
+    private assertPubkeyLen;
+}
+export type EscrowAssetType = 'token' | 'vault';
+export interface EscrowTokenState {
+    version: number;
+    bump: number;
+    depositor: Address;
+    assetType: EscrowAssetType;
+    amount: bigint;
+    arioMint: Address;
+    assetId: Uint8Array;
+    recipientProtocol: EscrowProtocol;
+    recipientPubkey: Uint8Array;
+    nonce: Uint8Array;
+    depositSlot: bigint;
+    vaultEndTimestamp: bigint;
+    vaultRevocable: boolean;
+}
+/**
+ * Solana-backed client for the trustless token/vault escrow program. All
+ * write methods require both `rpcSubscriptions` and `signer`; read methods
+ * only need `rpc`.
+ *
+ * Uses the same config shape as {@link ANTEscrow}.
+ */
+export declare class TokenEscrow {
+    protected readonly rpc: SolanaRpc;
+    protected readonly rpcSubscriptions?: SolanaRpcSubscriptions;
+    protected readonly signer?: TransactionSigner;
+    readonly programId: Address;
+    readonly coreProgram: Address;
+    protected readonly commitment: Commitment;
+    protected readonly logger: ILogger;
+    constructor(config: ANTEscrowConfig);
+    static init(config: ANTEscrowConfig): TokenEscrow;
+    /**
+     * Fetch the on-chain `EscrowToken` for a depositor and asset ID, or
+     * `null` if no active escrow exists. Uses the Codama-generated decoder.
+     */
+    get(depositor: Address, assetId: Uint8Array): Promise<EscrowTokenState | null>;
+    /**
+     * Fetch the on-chain `EscrowToken` for a vault escrow, or `null` if
+     * no active escrow exists.
+     */
+    getVault(depositor: Address, assetId: Uint8Array): Promise<EscrowTokenState | null>;
+    /** Address of the EscrowToken PDA (no RPC call). */
+    getTokenPda(depositor: Address, assetId: Uint8Array): Promise<Address>;
+    /** Address of the EscrowVault PDA (no RPC call). */
+    getVaultPda(depositor: Address, assetId: Uint8Array): Promise<Address>;
+    /**
+     * Deposit liquid ARIO tokens into escrow for a designated Arweave or
+     * Ethereum recipient. Prepends a create-ATA-idempotent instruction for
+     * the escrow PDA's token account in the same transaction.
+     */
+    depositTokens(args: {
+        assetId: Uint8Array;
+        amount: bigint;
+        arioMint: Address;
+        depositorTokenAccount: Address;
+        recipient: {
+            protocol: EscrowProtocol;
+            publicKey: Uint8Array;
+        };
+    }): Promise<string>;
+    /**
+     * Deposit ARIO tokens into escrow as a vaulted (time-locked) position.
+     * Same as `depositTokens` but additionally records the lock duration
+     * and revocability flag. Uses the vault PDA seed.
+     */
+    depositVault(args: {
+        assetId: Uint8Array;
+        amount: bigint;
+        arioMint: Address;
+        lockDurationSeconds: bigint;
+        revocable: boolean;
+        depositorTokenAccount: Address;
+        recipient: {
+            protocol: EscrowProtocol;
+            publicKey: Uint8Array;
+        };
+    }): Promise<string>;
+    /**
+     * Submit an Arweave RSA-PSS-4096 signature to release escrowed tokens.
+     * Anyone can submit (fee payer = `signer`); only `claimant` receives
+     * the tokens, and `depositor` receives rent.
+     */
+    claimTokensArweave(args: {
+        depositor: Address;
+        assetId: Uint8Array;
+        claimant: Address;
+        claimantTokenAccount: Address;
+        escrowTokenAccount: Address;
+        signature: Uint8Array;
+        saltLen?: number;
+    }): Promise<string>;
+    /**
+     * @deprecated Args `signature`, `saltLen`, `messageNonce` are ignored.
+     * Use the new attested flow — see `claimArweaveIx` doc.
+     */
+    claimTokensArweaveIx(args: {
+        depositor: Address;
+        assetId: Uint8Array;
+        claimant: Address;
+        claimantTokenAccount: Address;
+        escrowTokenAccount: Address;
+        /** @deprecated unused — superseded by attestor sigverify ix */
+        signature?: Uint8Array;
+        /** @deprecated unused — superseded by attestor sigverify ix */
+        saltLen?: number;
+        /** 32-byte nonce from the on-chain Escrow PDA. */
+        messageNonce: Uint8Array;
+    }): Promise<Instruction>;
+    /**
+     * Submit an Ethereum ECDSA secp256k1 + EIP-191 signature to release
+     * escrowed tokens.
+     */
+    claimTokensEthereum(args: {
+        depositor: Address;
+        assetId: Uint8Array;
+        claimant: Address;
+        claimantTokenAccount: Address;
+        escrowTokenAccount: Address;
+        signature: Uint8Array;
+    }): Promise<string>;
+    claimTokensEthereumIx(args: {
+        depositor: Address;
+        assetId: Uint8Array;
+        claimant: Address;
+        claimantTokenAccount: Address;
+        escrowTokenAccount: Address;
+        signature: Uint8Array;
+        messageNonce: Uint8Array;
+    }): Promise<Instruction>;
+    /**
+     * Submit an Arweave RSA-PSS-4096 signature to release escrowed vault tokens.
+     *
+     * The on-chain handler routes by vault state via instructions-sysvar
+     * introspection: an expired vault sends tokens straight to
+     * `claimantTokenAccount`; an active (still-locked) vault routes them to
+     * `payerTokenAccount` and requires a matching `ario_core::vaulted_transfer`
+     * sibling instruction in the same transaction.
+     *
+     * This method auto-detects the path from `vaultEndTimestamp` and bundles
+     * the sibling `vaulted_transfer` ix automatically when the vault is still
+     * active — callers do not need to construct it themselves.
+     */
+    claimVaultArweave(args: {
+        depositor: Address;
+        assetId: Uint8Array;
+        claimant: Address;
+        claimantTokenAccount: Address;
+        escrowTokenAccount: Address;
+        payerTokenAccount: Address;
+        signature: Uint8Array;
+        saltLen?: number;
+    }): Promise<string>;
+    /**
+     * Submit an Ethereum ECDSA signature to release escrowed vault tokens. See
+     * {@link claimVaultArweave} for the expired/active vault routing semantics.
+     * Auto-bundles the sibling `vaulted_transfer` ix for active vaults.
+     */
+    claimVaultEthereum(args: {
+        depositor: Address;
+        assetId: Uint8Array;
+        claimant: Address;
+        claimantTokenAccount: Address;
+        escrowTokenAccount: Address;
+        payerTokenAccount: Address;
+        signature: Uint8Array;
+    }): Promise<string>;
+    /**
+     * If the vault escrow is still locked (`vaultEndTimestamp` in the future),
+     * return `[claimIx, vaultedTransferIx]` so the on-chain claim handler can
+     * see the sibling (via `instructions_sysvar`) and re-vault tokens for the
+     * claimant. If the vault has expired, just `[claimIx]` — the on-chain
+     * handler delivers tokens directly to `claimantTokenAccount`.
+     *
+     * **Ordering matters at runtime**: `claim` must execute first so it can
+     * move tokens `escrow → payerTokenAccount`. `vaulted_transfer` then pulls
+     * from `payerTokenAccount` into the new vault. Reversing the order makes
+     * `vaulted_transfer` fail with `insufficient funds` because nothing has
+     * funded `payerTokenAccount` yet. The introspection check in
+     * `vault_introspect::verify_vaulted_transfer_in_tx` is presence-based
+     * (reads `instructions_sysvar`) so the *sibling* ordering doesn't matter
+     * for the check itself — only for atomic execution.
+     *
+     * `lockDurationSeconds` is set to the SDK-local `remaining` value. The
+     * on-chain handler accepts `lock_duration >= remaining_at_execution - 60s`
+     * (see the introspection function's tolerance), so any modest clock skew
+     * between client and chain is absorbed.
+     */
+    /**
+     * Idempotent-create the claimant's canonical ATA when needed.
+     *
+     * The on-chain claim handler delivers liquid tokens directly to
+     * `claimantTokenAccount` for expired vaults AND for token escrows.
+     * For active vaults, the `claim_vault_*` Anchor Accounts struct still
+     * declares `claimant_token_account: Account<TokenAccount>`, which forces
+     * Anchor's account-load-time validation to require the account exist
+     * even though the active path doesn't write to it. Either way: if the
+     * claimant is a fresh wallet that has never held this mint, the ATA
+     * doesn't exist and the tx fails with `AccountNotInitialized` (#3012).
+     *
+     * Returns `null` when the caller passed a non-canonical
+     * `claimantTokenAccount` (manually-created non-ATA token account,
+     * presumably already exists — caller's responsibility).
+     */
+    private _createClaimantAtaIfCanonical;
+    private maybeBundleVaultedTransfer;
+    /** Read the recipient's `VaultCounter.nextId`, defaulting to 0n if the
+     *  counter PDA hasn't been initialised yet (first vault for that owner). */
+    private getNextVaultId;
+    /**
+     * Cancel a token or vault escrow deposit and return the tokens to the
+     * depositor. Only callable by the original depositor.
+     */
+    cancel(args: {
+        assetId: Uint8Array;
+        assetType: EscrowAssetType;
+        depositorTokenAccount: Address;
+        escrowTokenAccount: Address;
+    }): Promise<string>;
+    /**
+     * Re-target the escrow at a new recipient identity. Rotates the
+     * on-chain nonce, invalidating any in-flight claim signatures.
+     */
+    updateRecipient(args: {
+        assetId: Uint8Array;
+        assetType: EscrowAssetType;
+        newRecipient: {
+            protocol: EscrowProtocol;
+            publicKey: Uint8Array;
+        };
+    }): Promise<string>;
+    private send;
+    private requireSigner;
+    private requireTokenEscrow;
+    private requireVaultEscrow;
+    private assertPubkeyLen;
+    private assertAssetIdLen;
+}

package/lib/types/solana/events.d.ts

@@ -0,0 +1,156 @@
+/**
+ * AR.IO Solana event decoders — consumer-facing API.
+ *
+ * Anchor `#[event]` emits surface as `Program data: <base64>` log lines
+ * inside the surrounding instruction's logs. The base64 blob is
+ * `[discriminator(8) || borsh_payload]`, where the discriminator is
+ * `sha256("event:<EventName>")[..8]`.
+ *
+ * This module wraps the per-program codecs in
+ * `sdk/src/solana/generated/<program>/events/` (auto-emitted by
+ * `sdk/scripts/events-codegen.mjs`) into:
+ *   - a discriminated union `AnyEvent` covering every event the
+ *     AR.IO contracts emit
+ *   - per-program union types for filtering
+ *   - log-walking utilities that route `Program data:` lines back to
+ *     the program that emitted them (so events emitted from a CPI'd
+ *     handler get attributed to the correct program)
+ *   - a typed `parseTransactionEvents(rpc, signature)` helper
+ *
+ * Event payloads are returned with `bigint` for u64 / i64 fields and
+ * `Address` for pubkey fields, matching the rest of the kit-native
+ * SDK. To narrow on a specific event, use the `name` discriminator or
+ * the per-event type guards exported alongside the union.
+ *
+ * Live event subscription (websocket / Helius / Geyser) is out of
+ * scope here — this module is the decoder layer that all those
+ * mechanisms can build on. See `parseTransactionEvents` for the
+ * pull-based model.
+ */
+import { type Rpc, type Signature, type SolanaRpcApi } from '@solana/kit';
+import { ARIO_ANT_PROGRAM_ADDRESS } from '@ar.io/solana-contracts/ant';
+import { ARIO_ANT_ESCROW_PROGRAM_ADDRESS } from '@ar.io/solana-contracts/ant-escrow';
+import { ARIO_ARNS_PROGRAM_ADDRESS } from '@ar.io/solana-contracts/arns';
+import { ARIO_CORE_PROGRAM_ADDRESS } from '@ar.io/solana-contracts/core';
+import { ARIO_GAR_PROGRAM_ADDRESS } from '@ar.io/solana-contracts/gar';
+import * as escrowEvents from './generated/ant-escrow/events/index.js';
+import * as antEvents from './generated/ant/events/index.js';
+import * as arnsEvents from './generated/arns/events/index.js';
+import * as coreEvents from './generated/core/events/index.js';
+import * as garEvents from './generated/gar/events/index.js';
+/** Maps event-name → decoded payload type, per program. */
+type CoreEventByName = {
+    [K in keyof typeof coreEvents as K extends `get${infer N}Decoder` ? N : never]: typeof coreEvents extends Record<`get${string & K}Decoder`, () => infer D> ? D extends {
+        decode(b: Uint8Array): infer P;
+    } ? P : never : never;
+};
+type GarEventByName = {
+    [K in keyof typeof garEvents as K extends `get${infer N}Decoder` ? N : never]: typeof garEvents extends Record<`get${string & K}Decoder`, () => infer D> ? D extends {
+        decode(b: Uint8Array): infer P;
+    } ? P : never : never;
+};
+type ArnsEventByName = {
+    [K in keyof typeof arnsEvents as K extends `get${infer N}Decoder` ? N : never]: typeof arnsEvents extends Record<`get${string & K}Decoder`, () => infer D> ? D extends {
+        decode(b: Uint8Array): infer P;
+    } ? P : never : never;
+};
+type AntEventByName = {
+    [K in keyof typeof antEvents as K extends `get${infer N}Decoder` ? N : never]: typeof antEvents extends Record<`get${string & K}Decoder`, () => infer D> ? D extends {
+        decode(b: Uint8Array): infer P;
+    } ? P : never : never;
+};
+type EscrowEventByName = {
+    [K in keyof typeof escrowEvents as K extends `get${infer N}Decoder` ? N : never]: typeof escrowEvents extends Record<`get${string & K}Decoder`, () => infer D> ? D extends {
+        decode(b: Uint8Array): infer P;
+    } ? P : never : never;
+};
+/** Per-program decoded-event union (each variant tagged by `name`). */
+export type AnyArioCoreEvent = {
+    [K in keyof CoreEventByName]: {
+        programId: typeof ARIO_CORE_PROGRAM_ADDRESS;
+        name: K;
+        data: CoreEventByName[K];
+    };
+}[keyof CoreEventByName];
+export type AnyArioGarEvent = {
+    [K in keyof GarEventByName]: {
+        programId: typeof ARIO_GAR_PROGRAM_ADDRESS;
+        name: K;
+        data: GarEventByName[K];
+    };
+}[keyof GarEventByName];
+export type AnyArioArnsEvent = {
+    [K in keyof ArnsEventByName]: {
+        programId: typeof ARIO_ARNS_PROGRAM_ADDRESS;
+        name: K;
+        data: ArnsEventByName[K];
+    };
+}[keyof ArnsEventByName];
+export type AnyArioAntEvent = {
+    [K in keyof AntEventByName]: {
+        programId: typeof ARIO_ANT_PROGRAM_ADDRESS;
+        name: K;
+        data: AntEventByName[K];
+    };
+}[keyof AntEventByName];
+export type AnyArioAntEscrowEvent = {
+    [K in keyof EscrowEventByName]: {
+        programId: typeof ARIO_ANT_ESCROW_PROGRAM_ADDRESS;
+        name: K;
+        data: EscrowEventByName[K];
+    };
+}[keyof EscrowEventByName];
+/** Top-level union covering every event from every AR.IO program. */
+export type AnyEvent = AnyArioCoreEvent | AnyArioGarEvent | AnyArioArnsEvent | AnyArioAntEvent | AnyArioAntEscrowEvent;
+/** All event-name strings that can appear as `AnyEvent.name`. */
+export type EventName = AnyEvent['name'];
+/**
+ * Parse every AR.IO event from a transaction's `log_messages` array.
+ *
+ * The logs are walked top-down. We track the current program by
+ * pushing on `Program <id> invoke [N]` and popping on `Program <id>
+ * success` / `failed`. Each `Program data: <base64>` line is attributed
+ * to the program at the top of the stack — so a `StakePaymentEvent`
+ * emitted by ario-gar from inside an ario-arns CPI is correctly
+ * attributed to ario-gar.
+ *
+ * Lines whose discriminator doesn't match any known AR.IO event are
+ * silently skipped — they may be from another program in the same tx
+ * (e.g., SPL Token's debit/credit logs aren't event emissions, but
+ * other Anchor programs in the same tx might emit unrelated events).
+ *
+ * Failed instructions inside a tx still emit logs up to the failure
+ * point. We don't filter those out — caller can cross-reference the
+ * tx's `meta.err` if it cares.
+ */
+export declare function parseEventsFromLogs(logs: readonly string[]): AnyEvent[];
+export declare function parseEventsFromLogs<N extends EventName>(logs: readonly string[], filter: N): Array<Extract<AnyEvent, {
+    name: N;
+}>>;
+/**
+ * Fetch a transaction by signature and return its decoded events.
+ *
+ * Uses `getTransaction` with `maxSupportedTransactionVersion: 0` and
+ * `commitment: 'confirmed'` by default. Returns `[]` if the tx is
+ * still pending, missing, or had no logs (rare — Anchor programs
+ * always log).
+ */
+export declare function parseTransactionEvents(rpc: Rpc<SolanaRpcApi>, signature: Signature, opts?: {
+    commitment?: 'processed' | 'confirmed' | 'finalized';
+}): Promise<AnyEvent[]>;
+/**
+ * Generic type-narrowing predicate for any event name.
+ *
+ * ```ts
+ * for (const ev of events) {
+ *   if (isEvent(ev, 'NamePurchasedEvent')) {
+ *     // ev.data is typed as NamePurchasedEvent here
+ *     console.log(ev.data.buyer, ev.data.cost);
+ *   }
+ * }
+ * ```
+ */
+export declare function isEvent<N extends EventName>(ev: AnyEvent, name: N): ev is Extract<AnyEvent, {
+    name: N;
+}>;
+export {};