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

package/lib/types/solana/ant-registry-readable.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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
+ */
+/**
+ * Solana implementation of the ANT Registry read interface.
+ *
+ * Backed by the per-user paginated ACL (ADR-012): a head `AclConfig` PDA
+ * and N content-addressable `AclPage` PDAs, each holding up to
+ * `MAX_ACL_PAGE_ENTRIES` `(asset, role)` tuples. Frontends can fetch a
+ * user's ANTs in two RPC calls — one `getAccountInfo` for `AclConfig` plus
+ * one `getMultipleAccountsInfo` for every page — instead of a
+ * `getProgramAccounts` scan, a DAS provider, or a foundation-hosted
+ * indexer.
+ *
+ * Usage:
+ * ```ts
+ * import { createSolanaRpc } from '@solana/kit';
+ * import { ANTRegistry } from '@ar.io/sdk';
+ *
+ * const registry = ANTRegistry.init({
+ *   backend: 'solana',
+ *   rpc: createSolanaRpc('https://api.mainnet-beta.solana.com'),
+ * });
+ *
+ * const { Owned, Controlled } = await registry.accessControlList({
+ *   address: 'SomeSolanaWalletAddress...',
+ * });
+ * ```
+ *
+ * When a user has no on-chain `AclConfig` (never registered / not yet
+ * populated), both lists return empty. The write path (SDK ANT write
+ * methods + migration tooling) is responsible for keeping the ACL in sync
+ * as owners / controllers change.
+ */
+import { type Address, type Commitment } from '@solana/kit';
+import { type ILogger } from '../common/logger.js';
+import type { AoANTRegistryRead } from '../types/ant-registry.js';
+import type { SolanaRpc } from './types.js';
+export type SolanaANTRegistryConfig = {
+    rpc: SolanaRpc;
+    commitment?: Commitment;
+    logger?: ILogger;
+    /**
+     * Override the ario-ant program ID. Required against any cluster other
+     * than mainnet — devnet, localnet, and the Surfpool harness all deploy
+     * programs at addresses derived from per-cluster keypair files.
+     */
+    antProgramId?: Address;
+};
+export declare class SolanaANTRegistryReadable implements AoANTRegistryRead {
+    protected readonly rpc: SolanaRpc;
+    protected readonly commitment: Commitment;
+    /** Deployed `ario-ant` program id this registry talks to. */
+    readonly antProgram: Address;
+    protected readonly logger: ILogger;
+    constructor(config: SolanaANTRegistryConfig);
+    /**
+     * Read a user's `AclConfig` head plus every `AclPage` and return owned +
+     * controlled ANT mint lists. Returns empty lists if the head PDA does not
+     * exist yet.
+     *
+     * **Note:** This is an eventually-consistent secondary index, not a
+     * canonical source of truth. Marketplace transfers update NFT ownership
+     * on-chain immediately but the ACL is only updated when someone calls
+     * `record_acl_owner` / `remove_acl_owner`. For real-time accuracy on a
+     * specific ANT, check the Metaplex Core asset owner directly.
+     */
+    accessControlList({ address: addr, }: {
+        address: string;
+    }): Promise<{
+        Owned: string[];
+        Controlled: string[];
+    }>;
+    /**
+     * Cleaner alias for `accessControlList` — matches the AO backend so
+     * consumers can switch backends without renaming calls.
+     */
+    getAntsForAddress({ address, }: {
+        address: string;
+    }): Promise<{
+        Owned: string[];
+        Controlled: string[];
+    }>;
+}

package/lib/types/solana/ant-registry-writeable.d.ts

@@ -0,0 +1,234 @@
+/**
+ * Solana implementation of the ANT Registry write interface.
+ *
+ * This class owns the per-user paginated ACL surface (ADR-012). After
+ * the on-chain hardening pass, the *primary* contract handlers
+ * (`add_controller`, `remove_controller`, `transfer`) write the ACL
+ * inline as part of their own instruction — Codama renders the ACL
+ * accounts as required, so callers cannot bypass them. The registry's
+ * job is therefore split in two:
+ *
+ *   1. **Preflight resolution.** Pick the right `AclConfig` + `AclPage`
+ *      to pass for a record / remove operation, and emit the
+ *      `register_acl_config` / `add_acl_page` ixs needed to bootstrap
+ *      missing accounts. See `resolveDestinationAclAccounts` and
+ *      `resolveSourceAclAccountsForEntry`.
+ *   2. **Bulk maintenance.** For operations the contract can't bundle
+ *      atomically (notably the variable-length ex-controller cleanup
+ *      after a transfer, plus any caller-driven heal flows), expose
+ *      `planAclMaintenance` + the standalone `record_acl_*` /
+ *      `remove_acl_*` instruction builders. `SolanaANTWriteable`
+ *      forwards an `aclOps` array to `sendTransaction` for these.
+ *
+ * Why the registry, not `SolanaANTWriteable`?
+ *   The ACL is a per-user structure shared across every ANT a user
+ *   touches, so the right home for the page-selection / preflight logic
+ *   is the registry itself. `SolanaANTWriteable` composes a
+ *   `SolanaANTRegistryWriteable` and delegates ACL planning to it.
+ *
+ * Per-user ACL layout (recap):
+ *   - `AclConfig` head at `["acl_config", user]` tracks `page_count` +
+ *     `total_entries`.
+ *   - Each `AclPage` is a content-addressable PDA at
+ *     `["acl_page", user, page_idx_le]` holding up to
+ *     `MAX_ACL_PAGE_ENTRIES` `(asset, role)` tuples.
+ *
+ * NOTE: `register_acl_config` and `add_acl_page` are permissionless —
+ * anyone can pay rent on behalf of any user. `payer` (the writeable
+ * registry's signer) acts as the rent payer for everything bundled here.
+ */
+import { type Address, type Instruction, type TransactionSigner } from '@solana/kit';
+import type { AclMaintenanceOp, AclMaintenanceRole, AoANTRegistryWrite } from '../types/ant-registry.js';
+import type { AoMessageResult } from '../types/common.js';
+import { type SolanaANTRegistryConfig, SolanaANTRegistryReadable } from './ant-registry-readable.js';
+export type SolanaANTRegistryWriteableConfig = SolanaANTRegistryConfig & {
+    /** Pays rent on `register_acl_config` / `add_acl_page` and authorises ix bundles. */
+    signer: TransactionSigner;
+};
+export declare class SolanaANTRegistryWriteable extends SolanaANTRegistryReadable implements AoANTRegistryWrite {
+    protected readonly signer: TransactionSigner;
+    constructor(config: SolanaANTRegistryWriteableConfig);
+    /**
+     * The Solana ANT registry does not have a centralised "register" step —
+     * `AclConfig` is created lazily the first time a user becomes an owner
+     * or controller (via `register_acl_config`, which `planAclMaintenance`
+     * emits automatically). This method exists only to satisfy the
+     * cross-backend `AoANTRegistryWrite` interface.
+     */
+    register(_params: {
+        processId: string;
+    }): Promise<AoMessageResult>;
+    /**
+     * Pure PDA derivation — no RPC. Useful for callers that already
+     * resolved the page via `resolveSourceAclAccountsForEntry` and need a
+     * fallback PDA (e.g. `removeController` when the entry can't be found
+     * but we still need to pass *some* page address to the contract so
+     * the on-chain handler returns the right error).
+     */
+    deriveAclConfigPda(user: Address): Promise<Address>;
+    /** Pure PDA derivation — see {@link deriveAclConfigPda}. */
+    deriveAclPagePda(user: Address, pageIdx: bigint): Promise<Address>;
+    /**
+     * Pick the `AclConfig` + destination `AclPage` to wire into a contract
+     * handler that is about to **record** an entry for `user` (e.g.
+     * `ario-ant::add_controller`, `ario-ant::transfer`'s new-owner side).
+     *
+     * Behaviour mirrors the planner's record path:
+     *   - If `AclConfig(user)` does not exist yet, emit
+     *     `register_acl_config` so the on-chain handler's seed-binding
+     *     resolves.
+     *   - If every existing `AclPage` is at `MAX_ACL_PAGE_ENTRIES`, emit
+     *     `add_acl_page` for `page_idx == page_count` and use it as the
+     *     destination.
+     *   - Otherwise pick the **first non-full page** so density recovers
+     *     after a `swap_remove` left a mid-life page sparse (see
+     *     `docs/ACCOUNT_SCALING_PATTERNS.md` § Pattern C).
+     *
+     * Returns the resolved PDAs plus any prep ixs the caller must
+     * **prepend** to the bundle. Idempotent: safe to call again on a
+     * partially-bootstrapped ACL — only the missing prep ixs come back.
+     *
+     * The on-chain handler still validates `acl_config.user == user` and
+     * the page seed binding, so a stale resolution simply fails the tx;
+     * over-emission is bounded by the current page layout.
+     */
+    resolveDestinationAclAccounts(params: {
+        user: Address;
+    }): Promise<{
+        aclConfigPda: Address;
+        aclPagePda: Address;
+        pageIdx: bigint;
+        prepIxs: Instruction[];
+    }>;
+    /**
+     * Locate the `AclPage` that currently holds `(asset, role)` for
+     * `user`, so a contract handler that is about to **remove** the entry
+     * (`ario-ant::remove_controller`, `ario-ant::transfer`'s old-owner
+     * side) can be wired with the right page accounts.
+     *
+     * Returns `null` if `user` has no `AclConfig` head or no matching
+     * entry — callers that want strict semantics should treat that as "no
+     * record to remove" and either skip the wrapped ix entirely (when the
+     * primary mutation is also unnecessary) or fall back to the standalone
+     * `remove_acl_*` heal flow.
+     *
+     * The on-chain handler does the strict check via `position_of` on
+     * the supplied page, so a wrong / stale resolution fails the tx with
+     * `AclEntryNotFound` rather than corrupting state.
+     */
+    resolveSourceAclAccountsForEntry(params: {
+        user: Address;
+        asset: Address;
+        role: AclMaintenanceRole;
+    }): Promise<{
+        aclConfigPda: Address;
+        aclPagePda: Address;
+        pageIdx: bigint;
+    } | null>;
+    /**
+     * Build a `register_acl_config` instruction. Permissionless: any wallet
+     * can pay to bootstrap an ACL head for any user.
+     */
+    buildRegisterAclConfigIx(params: {
+        user: Address;
+    }): Promise<Instruction>;
+    /**
+     * Build an `add_acl_page` instruction that appends the next page (i.e.
+     * page `page_count`) to a user's ACL. Caller must derive `pageIdx` from
+     * a fresh read of `AclConfig.page_count` to avoid colliding with an
+     * existing PDA — `planAclMaintenance` does this for you.
+     */
+    buildAddAclPageIx(params: {
+        user: Address;
+        pageIdx: bigint;
+    }): Promise<Instruction>;
+    /** Build a `record_acl_*` instruction for the given role. */
+    buildRecordIx(params: {
+        user: Address;
+        asset: Address;
+        role: AclMaintenanceRole;
+        pageIdx: bigint;
+    }): Promise<Instruction>;
+    /** Build a `remove_acl_*` instruction for the given role. */
+    buildRemoveIx(params: {
+        user: Address;
+        asset: Address;
+        role: AclMaintenanceRole;
+        pageIdx: bigint;
+    }): Promise<Instruction>;
+    /**
+     * Close the trailing `AclPage` (must be the last page and empty).
+     * Returns rent to `beneficiary`, which the on-chain handler enforces
+     * equals `acl_config.user`.
+     */
+    buildCloseAclPageIx(params: {
+        user: Address;
+        pageIdx: bigint;
+        beneficiary: Address;
+    }): Promise<Instruction>;
+    /**
+     * Close `AclConfig` once `page_count == 0` and `total_entries == 0`.
+     * Returns rent to `beneficiary`, which must equal `acl_config.user`
+     * on-chain.
+     */
+    buildCloseAclConfigIx(params: {
+        user: Address;
+        beneficiary: Address;
+    }): Promise<Instruction>;
+    /**
+     * Build the ACL ixs needed to bootstrap a freshly-spawned ANT's
+     * paginated owner ACL. The on-chain `initialize` handler seeds
+     * `ant_controllers = vec![owner]` (matches the Lua source), so the
+     * owner is recorded under **both** roles: `Owner` (for "ANTs I own"
+     * lookups) and `Controller` (for "ANTs I can manage" lookups).
+     *
+     * Returns the instructions in dependency order — `register_acl_config`
+     * → `add_acl_page` → `record_acl_owner` → `record_acl_controller`.
+     * Caller bundles them into the same tx as the MPL Core create + ANT
+     * `initialize` ixs so the ACL is atomic with the spawn.
+     */
+    bootstrapOwnerOnSpawn(params: {
+        owner: Address;
+        asset: Address;
+    }): Promise<Instruction[]>;
+    /**
+     * Build the `remove_acl_controller` ixs needed to clean up an ANT's
+     * ex-controller ACL entries after a transfer. The contract handler
+     * for `transfer` cannot atomically `swap_remove` each ex-controller
+     * (variable-length, no clean Codama representation), so the SDK
+     * bundles them via this helper instead.
+     *
+     * Idempotent (skips controllers whose ACL entry is already absent),
+     * so it's safe to call against a stale snapshot of `AntControllers`.
+     */
+    bulkRemoveControllerEntries(params: {
+        asset: Address;
+        controllers: ReadonlyArray<string>;
+    }): Promise<Instruction[]>;
+    /**
+     * Resolve an array of desired ACL mutations into the minimum
+     * instruction set needed to make them happen. For each unique user:
+     *   - reads the `AclConfig` head once (and all `AclPage`s in one
+     *     `getMultipleAccountsInfo` round trip)
+     *   - prepends `register_acl_config` if the head is missing AND any
+     *     `action: 'record'` op targets that user
+     *   - emits `add_acl_page` whenever the existing pages have no room
+     *   - drops `action: 'record'` ops where the entry already exists (no-op)
+     *   - drops `action: 'remove'` ops where the entry is already absent (no-op)
+     *
+     * Returned instructions preserve the dependency order:
+     * `register_acl_config` → `add_acl_page` → record/remove ixs that
+     * target the new page.
+     *
+     * Page selection on append: we fill the **first non-full page** so
+     * density recovers naturally after a `swap_remove` made a mid-life
+     * page sparse (see `docs/ACCOUNT_SCALING_PATTERNS.md` § Pattern C).
+     *
+     * `protected` so subclasses (and the workflow helpers above) can call
+     * it, but external callers go through `bootstrapOwnerOnSpawn` /
+     * `bulkRemoveControllerEntries` instead.
+     */
+    protected planAclMaintenance(ops: AclMaintenanceOp[]): Promise<Instruction[]>;
+    /** Load the head + every page for `user` in two RPC calls. */
+    private loadAclState;
+}

package/lib/types/solana/ant-writeable.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Solana implementation of ANT (Arweave Name Token) write interface.
+ *
+ * Extends SolanaANTReadable with write operations that build and send
+ * Solana transactions to the ario-ant program.
+ *
+ * All instruction encoding is delegated to the Codama-generated builders in
+ * `./generated/ant/instructions/` — they own the discriminator + Borsh codec
+ * + account-meta wiring derived from the on-chain IDL.
+ *
+ * ACL maintenance (ADR-012, paginated per-user ACL):
+ *   The on-chain handlers for `add_controller`, `remove_controller`, and
+ *   `transfer` *require* the controller / new-owner / old-owner ACL
+ *   accounts as instruction inputs and write the ACL inline as part of
+ *   the same atomic ix. This SDK's job is therefore reduced to two
+ *   things:
+ *     1. **Preflight resolution** — ask the composed
+ *        `SolanaANTRegistryWriteable` to pick the right page and emit
+ *        any `register_acl_config` / `add_acl_page` ixs that need to be
+ *        prepended so the contract's account validation succeeds.
+ *     2. **Ex-controller cleanup on transfer** — a wrapped transfer
+ *        cannot atomically `swap_remove` every ex-controller's ACL
+ *        entry (variable cardinality, no clean way to express variadic
+ *        accounts in Codama). The SDK reads the controllers list and
+ *        delegates to `registry.bulkRemoveControllerEntries`, which
+ *        produces the right `remove_acl_controller` ixs to append into
+ *        the transfer tx. Permissionless heal flows clean up any drift
+ *        if a marketplace transfer bypasses this SDK entirely.
+ */
+import { type Address, type Commitment, type Instruction } from '@solana/kit';
+import type { ILogger } from '../common/logger.js';
+import type { AoANTRegistryRead } from '../types/ant-registry.js';
+import type { AoANTSetBaseNameRecordParams, AoANTSetUndernameRecordParams } from '../types/ant.js';
+import type { AoMessageResult, WriteOptions } from '../types/common.js';
+import { SolanaANTReadable } from './ant-readable.js';
+import { SolanaANTRegistryWriteable } from './ant-registry-writeable.js';
+import type { SolanaRpc, SolanaRpcSubscriptions, SolanaSigner } from './types.js';
+/**
+ * Solana-backed read-write client for a single ANT (Arweave Name Token).
+ *
+ * Usage:
+ * ```ts
+ * import { createSolanaRpc, createSolanaRpcSubscriptions, createKeyPairSignerFromBytes } from '@solana/kit';
+ * import { SolanaANTWriteable } from '@ar.io/sdk/solana';
+ *
+ * const rpc = createSolanaRpc('https://api.mainnet-beta.solana.com');
+ * const rpcSubscriptions = createSolanaRpcSubscriptions('wss://api.mainnet-beta.solana.com');
+ * const signer = await createKeyPairSignerFromBytes(secretKeyBytes);
+ * const ant = new SolanaANTWriteable({
+ *   rpc,
+ *   rpcSubscriptions,
+ *   processId: 'MetaplexCoreAssetAddress...',
+ *   signer,
+ * });
+ *
+ * await ant.setRecord({ undername: 'docs', transactionId: '...', ttlSeconds: 3600 });
+ * ```
+ */
+export declare class SolanaANTWriteable extends SolanaANTReadable {
+    protected readonly signer: SolanaSigner;
+    protected readonly rpcSubscriptions: SolanaRpcSubscriptions;
+    /**
+     * Override the readable's registry with the writeable variant — gives
+     * us the preflight resolvers + the spawn / ex-controller workflow
+     * helpers, while preserving `accessControlList` reads from the
+     * parent's `AoANTRegistryRead` surface.
+     */
+    readonly registry: SolanaANTRegistryWriteable & AoANTRegistryRead;
+    constructor(config: {
+        rpc: SolanaRpc;
+        rpcSubscriptions: SolanaRpcSubscriptions;
+        processId: string;
+        signer: SolanaSigner;
+        commitment?: Commitment;
+        logger?: ILogger;
+        antProgramId?: Address;
+        /**
+         * Pre-built writeable registry to compose. When omitted we build one
+         * from `rpc` / `signer` / `commitment` / `antProgramId` so the simple
+         * single-arg call site keeps working.
+         */
+        registry?: SolanaANTRegistryWriteable;
+    });
+    /**
+     * Build, sign, and send a transaction.
+     *
+     * Plain pass-through to `sendAndConfirm` — every ANT write whose ACL
+     * footprint is bounded (controllers add/remove, owner swap on
+     * transfer) is handled inline by the contract handlers. Variable-
+     * length cleanup (notably ex-controller wipe after transfer) is
+     * pre-built by the caller via `registry.bulkRemoveControllerEntries`
+     * and appended into the same `instructions` array, so this method
+     * doesn't need its own ACL plumbing.
+     */
+    protected sendTransaction(instructions: Instruction[]): Promise<string>;
+    setRecord(params: AoANTSetUndernameRecordParams, _options?: WriteOptions): Promise<AoMessageResult>;
+    setBaseNameRecord(params: AoANTSetBaseNameRecordParams, options?: WriteOptions): Promise<AoMessageResult>;
+    setUndernameRecord(params: AoANTSetUndernameRecordParams, options?: WriteOptions): Promise<AoMessageResult>;
+    removeRecord(params: {
+        undername: string;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    removeUndernameRecord(params: {
+        undername: string;
+    }, options?: WriteOptions): Promise<AoMessageResult>;
+    transferRecord(params: {
+        undername: string;
+        recipient: string;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    addController(params: {
+        controller: string;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    removeController(params: {
+        controller: string;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    setName(params: {
+        name: string;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    setTicker(params: {
+        ticker: string;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    setDescription(params: {
+        description: string;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    setKeywords(params: {
+        keywords: string[];
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    setLogo(params: {
+        txId: string;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    transfer(params: {
+        target: string;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    reconcile(_options?: WriteOptions): Promise<AoMessageResult>;
+    releaseName(_params: {
+        name: string;
+        arioProcessId: string;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    reassignName(_params: {
+        name: string;
+        arioProcessId: string;
+        antProcessId: string;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    approvePrimaryNameRequest(_params: {
+        name: string;
+        address: string;
+        arioProcessId: string;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    removePrimaryNames(_params: {
+        names: string[];
+        arioProcessId: string;
+        notifyOwners?: boolean;
+    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    /**
+     * Migrate this ANT's on-chain state to the latest schema version.
+     * On Solana, "upgrade" means per-ANT data migration, not process forking.
+     * Returns the transaction signature if migration was needed.
+     */
+    upgrade(_params?: any): Promise<{
+        id: string;
+        needsMigration: boolean;
+    }>;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Associated Token Account derivation, kit-native.
+ * Mirrors the classic SPL `getAssociatedTokenAddress` function but returns
+ * a kit `Address` without the web3.js dependency.
+ *
+ * TODO(C7): replace with `findAssociatedTokenPda` from `@solana-program/associated-token`
+ * once that package is added as a dependency.
+ */
+import { type Address, type Instruction } from '@solana/kit';
+export declare const ATA_PROGRAM_ADDRESS: Address;
+/**
+ * Derive the Associated Token Account (ATA) address for a given owner + mint.
+ *
+ * @param mint — the SPL token mint address
+ * @param owner — the owner's wallet address (or a PDA if `allowOwnerOffCurve = true`)
+ * @param allowOwnerOffCurve — unused; kit derives regardless of curve. Kept for
+ *   parity with the old `@solana/spl-token` signature so call sites don't change.
+ */
+export declare function getAssociatedTokenAddressKit(mint: Address, owner: Address, _allowOwnerOffCurve?: boolean): Promise<Address>;
+/**
+ * Build an idempotent CreateAssociatedTokenAccount instruction. Safe to
+ * include in any tx — if the ATA already exists, the SPL ATA program
+ * silently succeeds.
+ *
+ * Used to pre-create vault / escrow ATAs in the same tx as the program
+ * instruction that consumes them. Anchor's `Account<TokenAccount>` constraint
+ * does NOT init the account, so the caller is responsible.
+ */
+export declare function buildCreateAtaIdempotentIx(payer: Address, ata: Address, owner: Address, mint: Address): Instruction;

package/lib/types/solana/canonical-message.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Canonical claim-message helper for `ario-ant-escrow`.
+ *
+ * Produces the EXACT bytes a recipient signs to release an escrowed
+ * ANT. Output MUST be byte-identical to the Rust implementation in
+ * `contracts/programs/ario-ant-escrow/src/canonical.rs::build_canonical_message`.
+ * Cross-language equivalence is asserted by `canonical-message.test.ts`
+ * which spawns the Rust `canonical` example binary and diffs the bytes.
+ *
+ * Format (UTF-8, line-feed separated, no trailing newline):
+ *
+ * ```text
+ * ar.io ant-escrow claim v1
+ * network: <network>
+ * ant: <ant_mint_base58>
+ * claimant: <claimant_solana_pubkey_base58>
+ * nonce: <nonce_hex_lowercase>
+ * ```
+ *
+ * Wallets sign these bytes directly:
+ * - Arweave: `wallet.signMessage(bytes)` → 512-byte RSA-PSS sig
+ * - Ethereum: `wallet.signMessage(bytes)` → 65-byte ECDSA + EIP-191 sig
+ *   (the wallet applies the EIP-191 prefix; on-chain code re-applies it).
+ */
+import type { Address } from '@solana/kit';
+/** Network bound into the canonical message at compile-time on the Rust
+ * side. Frontend / SDK callers pass it explicitly so a single SDK build
+ * works against either deployment. */
+export type EscrowNetwork = 'solana-mainnet' | 'solana-devnet';
+export interface CanonicalMessageInput {
+    /** Must match the program's compile-time network string. */
+    network: EscrowNetwork;
+    /** ANT mint pubkey — matches `escrow.ant_mint`. */
+    antMint: Address;
+    /** Solana pubkey that will receive the ANT on claim. Bound into the
+     *  signature so front-runners can't redirect. */
+    claimant: Address;
+    /** 32-byte anti-replay nonce — read from the EscrowAnt account. */
+    nonce: Uint8Array;
+}
+/**
+ * Build the canonical claim message bytes. UTF-8 encoded, no trailing
+ * newline, exactly the format shown in the docstring.
+ *
+ * @throws if `nonce` isn't exactly 32 bytes — guards against accidentally
+ * passing a hex string or a different-sized buffer.
+ */
+export declare function canonicalMessage(input: CanonicalMessageInput): Uint8Array;
+export interface CanonicalMessageV2Input {
+    /** Must match the program's compile-time network string. */
+    network: EscrowNetwork;
+    /** `'token'` for liquid ARIO, `'vault'` for time-locked positions. */
+    assetType: 'token' | 'vault';
+    /** 32-byte client-supplied unique identifier for the escrowed asset. */
+    assetId: Uint8Array;
+    /** Amount of ARIO (mARIO) held in escrow. */
+    amount: bigint;
+    /** Solana pubkey that will receive the tokens on claim. */
+    claimant: Address;
+    /** 32-byte anti-replay nonce — read from the EscrowToken account. */
+    nonce: Uint8Array;
+}
+/**
+ * Build the v2 canonical claim message bytes for token/vault escrows.
+ * UTF-8 encoded, no trailing newline.
+ *
+ * Format:
+ * ```text
+ * ar.io escrow claim v2
+ * network: <network>
+ * type: <token|vault>
+ * asset: <asset_id_hex_lowercase_64chars>
+ * amount: <u64_decimal>
+ * claimant: <base58>
+ * nonce: <hex_lowercase_64chars>
+ * ```
+ *
+ * @throws if `assetId` or `nonce` aren't exactly 32 bytes.
+ */
+export declare function canonicalMessageV2(input: CanonicalMessageV2Input): Uint8Array;
+/** Lowercase-hex encoding. Matches Rust `encode_hex_lowercase`. */
+export declare function bytesToHexLower(bytes: Uint8Array): string;

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

@@ -0,0 +1,62 @@
+/**
+ * Cluster-specific deployment constants for AR.IO programs.
+ *
+ * Mainnet IDs are baked into the IDL at codegen time and surfaced via the
+ * placeholder constants in `./constants.ts` (e.g. `ARIO_CORE_PROGRAM_ID`).
+ * This module exposes the same values for *other* clusters where the
+ * programs are deployed at non-default addresses — primarily devnet.
+ *
+ * Source of truth: `/devnet-config.json` at the repo root. Keep these
+ * exports in sync when devnet is redeployed; the bundled drift test
+ * (`clusters.test.ts`) will fail CI on mismatch.
+ *
+ * Usage:
+ * ```ts
+ * import { ARIO } from '@ar.io/sdk';
+ * import { DEVNET_PROGRAM_IDS, DEVNET_RPC_URL } from '@ar.io/sdk/solana';
+ * import { createSolanaRpc, createSolanaRpcSubscriptions } from '@solana/kit';
+ *
+ * const rpc = createSolanaRpc(DEVNET_RPC_URL);
+ * const rpcSubscriptions = createSolanaRpcSubscriptions(
+ *   DEVNET_RPC_URL.replace(/^https/, 'wss'),
+ * );
+ * const ario = ARIO.init({
+ *   backend: 'solana',
+ *   rpc,
+ *   rpcSubscriptions,
+ *   programIds: DEVNET_PROGRAM_IDS,
+ * });
+ * ```
+ */
+import { type Address } from '@solana/kit';
+/**
+ * Default JSON-RPC URL for the Solana devnet cluster.
+ *
+ * Public devnet rate-limits aggressively — for high-volume work, swap in
+ * a premium RPC (QuickNode / Helius / Triton). Derive the WS URL with
+ * `DEVNET_RPC_URL.replace(/^https/, 'wss')`.
+ */
+export declare const DEVNET_RPC_URL = "https://api.devnet.solana.com";
+/**
+ * AR.IO program IDs deployed on Solana devnet.
+ *
+ * Shape matches the `programIds` argument of
+ * `ARIO.init({ backend: 'solana', programIds, ... })`.
+ *
+ * `antEscrow` is `null` because `ario-ant-escrow` is not deployed on
+ * devnet — the `sol_big_mod_exp` syscall it depends on is inactive on
+ * all public clusters today.
+ */
+export declare const DEVNET_PROGRAM_IDS: {
+    readonly core: Address<"83CQLP848zzCgnZ4LTq87g6hvxTooNLX7YXXkUUGv5ig">;
+    readonly gar: Address<"AF8QAEaR4hzsqeUDwEdeTXMYtdyFegTENBdnJro6WVLR">;
+    readonly arns: Address<"2HgSCKYjcapJPdHRKqkLrGXm7kvBmCP45ZyhWEm87oM1">;
+    readonly ant: Address<"8ZMuXhiK7DorjPUg8RB1rzu7CvsABMk38WDJRbM62y2C">;
+    readonly antEscrow: Address | null;
+};
+/** ARIO SPL Token mint on devnet. */
+export declare const DEVNET_ARIO_MINT: Address;
+/** Protocol treasury token account on devnet (owner = ArioConfig PDA). */
+export declare const DEVNET_TREASURY_TOKEN_ACCOUNT: Address;
+/** Protocol stake token account on devnet (owner = GatewaySettings PDA). */
+export declare const DEVNET_STAKE_TOKEN_ACCOUNT: Address;