@ar.io/sdk 3.24.0 → 4.0.0-alpha.2

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

@@ -0,0 +1,480 @@
+/**
+ * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * 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 EscrowAnt, type EscrowToken } from '@ar.io/solana-contracts/ant-escrow';
+import type { ILogger } from '../common/logger.js';
+import type { SolanaRpc, SolanaRpcSubscriptions } from './types.js';
+export type EscrowProtocol = 'arweave' | 'ethereum';
+export interface EscrowAntState {
+    /** On-chain schema version, as decoded by the generated client. */
+    version: EscrowAnt['version'];
+    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. Currently unused (post-ADR-022 the SDK no longer
+     * builds a sibling `vaulted_transfer`; active vault claims are rejected
+     * with `VaultStillLocked`). Retained for forward-compat — if the active
+     * re-lock path is ever revived via the direct-CPI restoration playbook
+     * (contracts `docs/RESTORE_ACTIVE_VAULT_RELOCK.md`), this is the program
+     * the new claim ABI would need to reference. 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 {
+    /** On-chain schema version, as decoded by the generated client. */
+    version: EscrowToken['version'];
+    bump: number;
+    depositor: Address;
+    assetType: EscrowAssetType;
+    amount: bigint;
+    arioMint: Address;
+    assetId: Uint8Array;
+    recipientProtocol: EscrowProtocol;
+    recipientPubkey: Uint8Array;
+    nonce: Uint8Array;
+    depositSlot: bigint;
+    vaultEndTimestamp: bigint;
+    vaultRevocable: boolean;
+}
+/**
+ * Forward clock-skew buffer (seconds) added to `vault_end_timestamp` before
+ * the SDK considers a vault claimable. The SDK reads wall-clock time
+ * (`Date.now()`) while the on-chain gate reads Solana cluster time, and
+ * the two can disagree by several seconds. The buffer biases every skew
+ * race into the *friendly* direction: the SDK rejects when the chain
+ * would actually accept (user retries 30s later, succeeds), never the
+ * reverse (user submits a doomed tx and sees the raw on-chain error).
+ *
+ * 30s is conservative — Solana cluster clock typically drifts <2s vs
+ * wall clock — but matches the order of magnitude of the previously-used
+ * `60s` introspection tolerance in the removed `vault_introspect` module.
+ */
+export declare const CLOCK_SKEW_TOLERANCE_SECONDS = 30n;
+/**
+ * Returns `true` when a vault escrow is past its unlock timestamp by at
+ * least {@link CLOCK_SKEW_TOLERANCE_SECONDS}. Non-throwing companion to
+ * {@link assertVaultClaimable} for UI gating (e.g. enabling/disabling a
+ * Submit button without showing an error).
+ */
+export declare function isVaultClaimable(escrow: EscrowTokenState): boolean;
+/**
+ * Pre-flight the on-chain `VaultStillLocked` gate (ADR-022): refuse to build
+ * a claim tx while the vault is still locked, with a small forward
+ * {@link CLOCK_SKEW_TOLERANCE_SECONDS} buffer so wall/cluster clock skew
+ * biases into the friendly direction. Surfaces the unlock timestamp so
+ * callers / UIs can show "claimable after <date>" instead of a doomed tx.
+ *
+ * Exported for unit-testability; not part of the public SDK surface — call the
+ * high-level `claimVaultArweave` / `claimVaultEthereum` instead, which invoke
+ * this guard internally.
+ *
+ * @internal
+ */
+export declare function assertVaultClaimable(escrow: EscrowTokenState): void;
+/**
+ * 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>;
+    /**
+     * **Use {@link claimVaultArweaveIx} instead** — this single-send wrapper
+     * cannot work end-to-end for the Arweave attested vault-claim path,
+     * because the on-chain `claim_vault_arweave_attested` handler requires
+     * an Ed25519Program native sigverify ix at idx-1 of the claim ix
+     * (introspected via `instructions_sysvar`). That sigverify ix carries
+     * the attestor's Ed25519 signature over the canonical claim message
+     * and is built by the *integrator* (who calls the off-chain attestor
+     * service for the signature, per ADR-017) — the SDK has no attestor
+     * URL or client to do this for the caller.
+     *
+     * Calling this method instead of composing via
+     * {@link claimVaultArweaveIx} will hit `MissingAttestation` on-chain.
+     * It is kept only for ABI continuity; new code must use
+     * {@link claimVaultArweaveIx} and prepend the attestor sigverify ix.
+     *
+     * @deprecated cannot succeed alone — see {@link claimVaultArweaveIx}.
+     */
+    claimVaultArweave(_args: {
+        depositor: Address;
+        assetId: Uint8Array;
+        claimant: Address;
+        claimantTokenAccount: Address;
+        escrowTokenAccount: Address;
+        signature: Uint8Array;
+        saltLen?: number;
+    }): Promise<string>;
+    /**
+     * Build a `claim_vault_arweave_attested` instruction (without sending).
+     * Mirror of {@link claimTokensArweaveIx} for the vault-claim path:
+     * returns the bare claim ix so the caller can prepend the attestor's
+     * Ed25519Program sigverify ix and submit the bundle in one tx.
+     *
+     * The on-chain handler:
+     * - Reads the preceding Ed25519Program native sigverify ix from
+     *   `instructions_sysvar` to confirm the attestor signed the canonical
+     *   claim message.
+     * - Rejects with `VaultStillLocked` if `clock < vault_end_timestamp`
+     *   (ADR-022). Callers should pre-flight with {@link isVaultClaimable}
+     *   (non-throwing) or {@link assertVaultClaimable} (throws with the
+     *   unlock timestamp) before composing the tx.
+     * - On the expired path, transfers the escrowed amount liquid to
+     *   `claimantTokenAccount` and closes the escrow PDA.
+     *
+     * Composition (frontend pattern):
+     *   ```ts
+     *   const escrow = await tokenEscrow.requireVaultEscrow(depositor, assetId);
+     *   assertVaultClaimable(escrow);                       // pre-flight
+     *   const canonical = canonicalMessage({ ... });        // build message
+     *   const attestation = await attestor.attest({ ... }); // attestor service
+     *   const ed25519Ix = buildEd25519SigverifyIx(
+     *     attestation.attestorPubkey, attestation.signature, canonical,
+     *   );
+     *   const claimIx = await tokenEscrow.claimVaultArweaveIx({
+     *     depositor, assetId, claimant, claimantTokenAccount,
+     *     escrowTokenAccount, messageNonce: escrow.nonce,
+     *   });
+     *   // Idempotent-create the claimant ATA if it's the canonical derivation.
+     *   await sendTx([createAtaIx?, ed25519Ix, claimIx]);
+     *   ```
+     */
+    claimVaultArweaveIx(args: {
+        depositor: Address;
+        assetId: Uint8Array;
+        claimant: Address;
+        claimantTokenAccount: Address;
+        escrowTokenAccount: Address;
+        /** 32-byte nonce from the on-chain EscrowToken PDA (`escrow.nonce`). */
+        messageNonce: Uint8Array;
+    }): Promise<Instruction>;
+    /**
+     * Submit an Ethereum ECDSA signature to release escrowed vault tokens. See
+     * {@link claimVaultArweave} — same lock semantics: vaults are only claimable
+     * after `vault_end_timestamp`; active (still-locked) claims throw pre-flight
+     * and are rejected on-chain with `VaultStillLocked` (ADR-022 / BD-107).
+     */
+    claimVaultEthereum(args: {
+        depositor: Address;
+        assetId: Uint8Array;
+        claimant: Address;
+        claimantTokenAccount: Address;
+        escrowTokenAccount: Address;
+        signature: Uint8Array;
+    }): Promise<string>;
+    /**
+    /**
+     * Idempotent-create the claimant's canonical ATA when needed.
+     *
+     * The claim handler delivers liquid tokens directly to
+     * `claimantTokenAccount` (post-ADR-022 there's only the liquid path for
+     * vaults). 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;
+    /**
+     * 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,38 @@
+/**
+ * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * AR.IO Solana event decoders — STUB.
+ *
+ * The local event codegen pipeline has been removed. Event decoders will be
+ * restored once `@ar.io/solana-contracts` publishes them. Until then, the
+ * parse functions return empty arrays and the union types are `never`.
+ */
+import type { Rpc, Signature, SolanaRpcApi } from '@solana/kit';
+/** Placeholder — no event variants are available until the contracts package ships event decoders. */
+export type AnyArioCoreEvent = never;
+export type AnyArioGarEvent = never;
+export type AnyArioArnsEvent = never;
+export type AnyArioAntEvent = never;
+export type AnyArioAntEscrowEvent = never;
+export type AnyEvent = AnyArioCoreEvent | AnyArioGarEvent | AnyArioArnsEvent | AnyArioAntEvent | AnyArioAntEscrowEvent;
+export type EventName = never;
+export declare function parseEventsFromLogs(_logs: readonly string[]): AnyEvent[];
+export declare function parseTransactionEvents(_rpc: Rpc<SolanaRpcApi>, _signature: Signature, _opts?: {
+    commitment?: 'processed' | 'confirmed' | 'finalized';
+}): Promise<AnyEvent[]>;
+export declare function isEvent<N extends EventName>(ev: AnyEvent, _name: N): ev is Extract<AnyEvent, {
+    name: N;
+}>;