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

package/lib/esm/solana/ant-writeable.js

@@ -0,0 +1,384 @@
+/**
+ * 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 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 { address, } from '@solana/kit';
+import { getAddControllerInstructionAsync, getMigrateAntInstructionAsync, getReconcileInstructionAsync, getRemoveControllerInstructionAsync, getRemoveRecordInstructionAsync, getSetDescriptionInstructionAsync, getSetKeywordsInstructionAsync, getSetLogoInstructionAsync, getSetNameInstructionAsync, getSetRecordInstructionAsync, getSetRecordMetadataInstructionAsync, getSetTickerInstructionAsync, getTransferInstructionAsync, getTransferRecordInstructionAsync, } from '@ar.io/solana-contracts/ant';
+import { SolanaANTReadable } from './ant-readable.js';
+import { SolanaANTRegistryWriteable } from './ant-registry-writeable.js';
+import { deserializeAntControllers } from './deserialize.js';
+import { getAccountInfoLegacy } from './json-rpc.js';
+import { getAntControllersPDA, getAntRecordMetadataPDA, getAntRecordPDA, } from './pda.js';
+import { sendAndConfirm } from './send.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 class SolanaANTWriteable extends SolanaANTReadable {
+    signer;
+    rpcSubscriptions;
+    constructor(config) {
+        const registry = config.registry ??
+            new SolanaANTRegistryWriteable({
+                rpc: config.rpc,
+                signer: config.signer,
+                commitment: config.commitment,
+                logger: config.logger,
+                antProgramId: config.antProgramId,
+            });
+        super({ ...config, registry });
+        this.signer = config.signer;
+        this.rpcSubscriptions = config.rpcSubscriptions;
+    }
+    /**
+     * 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.
+     */
+    async sendTransaction(instructions) {
+        return sendAndConfirm({
+            rpc: this.rpc,
+            rpcSubscriptions: this.rpcSubscriptions,
+            signer: this.signer,
+            instructions,
+            commitment: this.commitment,
+            computeUnitLimit: 400_000,
+        });
+    }
+    // =========================================
+    // Record operations
+    // =========================================
+    async setRecord(params, _options) {
+        const [recordPda] = await getAntRecordPDA(this.mint, params.undername, this.antProgram);
+        // Per-record metadata (display name / logo / description / keywords)
+        // moved out of `set_record` into a dedicated `set_record_metadata`
+        // instruction when `AntRecord` was split (ARNS-712). These fields are
+        // not part of `ANTSetUndernameRecordParams` today, but we keep the
+        // forward path here so callers can pass them on the params object and
+        // we'll bundle a `set_record_metadata` ix into the same tx.
+        const extra = params;
+        const ixs = [];
+        ixs.push(await getSetRecordInstructionAsync({
+            asset: this.mint,
+            record: recordPda,
+            caller: this.signer,
+            undername: params.undername,
+            target: params.transactionId,
+            targetProtocol: params.targetProtocol ?? 0,
+            ttlSeconds: params.ttlSeconds,
+            priority: params.priority ?? null,
+            recordOwner: params.owner ? address(params.owner) : null,
+        }, { programAddress: this.antProgram }));
+        const hasMetadata = extra.displayName !== undefined ||
+            extra.logo !== undefined ||
+            extra.description !== undefined ||
+            extra.keywords !== undefined;
+        if (hasMetadata) {
+            const [metadataPda] = await getAntRecordMetadataPDA(this.mint, params.undername, this.antProgram);
+            ixs.push(await getSetRecordMetadataInstructionAsync({
+                asset: this.mint,
+                record: recordPda,
+                recordMetadata: metadataPda,
+                caller: this.signer,
+                undername: params.undername,
+                displayName: extra.displayName ?? null,
+                recordLogo: extra.logo ?? null,
+                recordDescription: extra.description ?? null,
+                recordKeywords: extra.keywords ?? null,
+            }, { programAddress: this.antProgram }));
+        }
+        const sig = await this.sendTransaction(ixs);
+        return { id: sig };
+    }
+    async setBaseNameRecord(params, options) {
+        return this.setRecord({ ...params, undername: '@' }, options);
+    }
+    async setUndernameRecord(params, options) {
+        return this.setRecord(params, options);
+    }
+    async removeRecord(params, _options) {
+        const [recordPda] = await getAntRecordPDA(this.mint, params.undername, this.antProgram);
+        const ix = await getRemoveRecordInstructionAsync({
+            asset: this.mint,
+            record: recordPda,
+            caller: this.signer,
+        }, { programAddress: this.antProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    async removeUndernameRecord(params, options) {
+        return this.removeRecord(params, options);
+    }
+    async transferRecord(params, _options) {
+        const [recordPda] = await getAntRecordPDA(this.mint, params.undername, this.antProgram);
+        const ix = await getTransferRecordInstructionAsync({
+            asset: this.mint,
+            record: recordPda,
+            caller: this.signer,
+            newOwner: address(params.recipient),
+        }, { programAddress: this.antProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    // =========================================
+    // Controller operations
+    // =========================================
+    async addController(params, _options) {
+        const controller = address(params.controller);
+        // ADR-012 (ACL): contract `add_controller` requires the controller's
+        // `AclConfig` + a destination `AclPage` and writes the
+        // `record_controller` entry inline. Resolve them here and prepend
+        // any `register_acl_config` / `add_acl_page` bootstrap ixs needed
+        // for first-time controllers.
+        const dest = await this.registry.resolveDestinationAclAccounts({
+            user: controller,
+        });
+        const addIx = await getAddControllerInstructionAsync({
+            asset: this.mint,
+            caller: this.signer,
+            controller,
+            controllerAclConfig: dest.aclConfigPda,
+            controllerAclPage: dest.aclPagePda,
+        }, { programAddress: this.antProgram });
+        const sig = await this.sendTransaction([...dest.prepIxs, addIx]);
+        return { id: sig };
+    }
+    async removeController(params, _options) {
+        const controller = address(params.controller);
+        // ADR-012 (ACL): contract `remove_controller` requires the page
+        // currently holding `(asset, Controller)`. Resolve via the
+        // registry; if the entry can't be found we still pass page 0 as a
+        // placeholder so the on-chain handler surfaces `AclEntryNotFound`
+        // (or, more likely, the page-belongs check fails first) rather
+        // than us silently swallowing the removal.
+        const source = await this.registry.resolveSourceAclAccountsForEntry({
+            user: controller,
+            asset: this.mint,
+            role: 'controller',
+        });
+        const aclConfigPda = source?.aclConfigPda ??
+            (await this.registry.deriveAclConfigPda(controller));
+        const aclPagePda = source?.aclPagePda ??
+            (await this.registry.deriveAclPagePda(controller, 0n));
+        const removeIx = await getRemoveControllerInstructionAsync({
+            asset: this.mint,
+            caller: this.signer,
+            controller,
+            controllerAclConfig: aclConfigPda,
+            controllerAclPage: aclPagePda,
+        }, { programAddress: this.antProgram });
+        const sig = await this.sendTransaction([removeIx]);
+        return { id: sig };
+    }
+    // =========================================
+    // Metadata operations
+    // =========================================
+    async setName(params, _options) {
+        const ix = await getSetNameInstructionAsync({ asset: this.mint, caller: this.signer, name: params.name }, { programAddress: this.antProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    async setTicker(params, _options) {
+        const ix = await getSetTickerInstructionAsync({ asset: this.mint, caller: this.signer, ticker: params.ticker }, { programAddress: this.antProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    async setDescription(params, _options) {
+        const ix = await getSetDescriptionInstructionAsync({
+            asset: this.mint,
+            caller: this.signer,
+            description: params.description,
+        }, { programAddress: this.antProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    async setKeywords(params, _options) {
+        const ix = await getSetKeywordsInstructionAsync({ asset: this.mint, caller: this.signer, keywords: params.keywords }, { programAddress: this.antProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    async setLogo(params, _options) {
+        const ix = await getSetLogoInstructionAsync({ asset: this.mint, caller: this.signer, logo: params.txId }, { programAddress: this.antProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    // =========================================
+    // Transfer (wrapped ario_ant::transfer — CPI into MPL Core +
+    // inline reconcile + inline owner ACL swap)
+    // =========================================
+    async transfer(params, _options) {
+        const newOwner = address(params.target);
+        const oldOwner = this.signer.address;
+        // Resolve the new owner's destination ACL accounts (and bootstrap
+        // them if missing). The contract requires a non-full page; the
+        // registry preflight emits `register_acl_config` / `add_acl_page`
+        // ixs so the wrapped `transfer` ix's account validation succeeds.
+        const newOwnerDest = await this.registry.resolveDestinationAclAccounts({
+            user: newOwner,
+        });
+        // Resolve the old owner's source ACL accounts. If the entry is
+        // missing (e.g. the ANT was acquired via a marketplace transfer or
+        // before the ACL system existed), heal it by bootstrapping the
+        // config/page and recording the owner entry so the on-chain
+        // transfer handler can successfully remove it.
+        const oldOwnerSource = await this.registry.resolveSourceAclAccountsForEntry({
+            user: oldOwner,
+            asset: this.mint,
+            role: 'owner',
+        });
+        let oldOwnerAclConfigPda;
+        let oldOwnerAclPagePda;
+        const oldOwnerHealIxs = [];
+        if (oldOwnerSource) {
+            oldOwnerAclConfigPda = oldOwnerSource.aclConfigPda;
+            oldOwnerAclPagePda = oldOwnerSource.aclPagePda;
+        }
+        else {
+            const dest = await this.registry.resolveDestinationAclAccounts({
+                user: oldOwner,
+            });
+            oldOwnerAclConfigPda = dest.aclConfigPda;
+            oldOwnerAclPagePda = dest.aclPagePda;
+            oldOwnerHealIxs.push(...dest.prepIxs);
+            oldOwnerHealIxs.push(await this.registry.buildRecordIx({
+                user: oldOwner,
+                asset: this.mint,
+                role: 'owner',
+                pageIdx: dest.pageIdx,
+            }));
+        }
+        const transferIx = await getTransferInstructionAsync({
+            asset: this.mint,
+            caller: this.signer,
+            newOwner,
+            newOwnerAclConfig: newOwnerDest.aclConfigPda,
+            newOwnerAclPage: newOwnerDest.aclPagePda,
+            oldOwnerAclConfig: oldOwnerAclConfigPda,
+            oldOwnerAclPage: oldOwnerAclPagePda,
+        }, { programAddress: this.antProgram });
+        // Ex-controller cleanup. The wrapped contract handler clears
+        // `AntControllers` via inline reconcile, but it cannot atomically
+        // `swap_remove` each ex-controller's ACL entry (variable-length;
+        // accounts can't be cleanly variadic in Codama). Read the live
+        // controllers list before the transfer and let the registry build
+        // the cleanup ixs — same-tx so frontends never see a stale "I
+        // control this ANT" entry. Permissionless heal flows clean up any
+        // drift if a marketplace transfer bypasses this SDK entirely.
+        const [controllersPda] = await getAntControllersPDA(this.mint, this.antProgram);
+        const controllersAccount = await getAccountInfoLegacy(this.rpc, controllersPda, this.commitment);
+        const exControllers = controllersAccount
+            ? deserializeAntControllers(controllersAccount.data).controllers
+            : [];
+        const cleanupIxs = await this.registry.bulkRemoveControllerEntries({
+            asset: this.mint,
+            controllers: exControllers,
+        });
+        const sig = await this.sendTransaction([
+            ...oldOwnerHealIxs,
+            ...newOwnerDest.prepIxs,
+            transferIx,
+            ...cleanupIxs,
+        ]);
+        return { id: sig };
+    }
+    // =========================================
+    // Reconcile (Solana-specific)
+    // =========================================
+    async reconcile(_options) {
+        const ix = await getReconcileInstructionAsync({ asset: this.mint, caller: this.signer }, { programAddress: this.antProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig };
+    }
+    // =========================================
+    // AO-specific methods (not applicable on Solana)
+    // =========================================
+    async releaseName(_params, _options) {
+        throw new Error('releaseName not applicable on Solana — use ario-arns program directly');
+    }
+    async reassignName(_params, _options) {
+        throw new Error('reassignName not applicable on Solana — use ario-arns program directly');
+    }
+    async approvePrimaryNameRequest(_params, _options) {
+        throw new Error('approvePrimaryNameRequest not applicable on Solana — use ario-core program directly');
+    }
+    async removePrimaryNames(_params, _options) {
+        throw new Error('removePrimaryNames not applicable on Solana — use ario-core program directly');
+    }
+    /**
+     * 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.
+     */
+    async upgrade(_params) {
+        const needs = await this.needsMigration();
+        if (!needs) {
+            return { id: '', needsMigration: false };
+        }
+        const ix = await getMigrateAntInstructionAsync({ asset: this.mint, payer: this.signer }, { programAddress: this.antProgram });
+        const sig = await this.sendTransaction([ix]);
+        return { id: sig, needsMigration: true };
+    }
+}

package/lib/esm/solana/ata.js

@@ -0,0 +1,70 @@
+/**
+ * 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.
+ */
+/**
+ * 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 { address, getAddressEncoder, getProgramDerivedAddress, } from '@solana/kit';
+import { SYSTEM_PROGRAM_ADDRESS, TOKEN_PROGRAM_ADDRESS, } from './instruction.js';
+export const ATA_PROGRAM_ADDRESS = address('ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL');
+const addressEncoder = getAddressEncoder();
+/**
+ * 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 async function getAssociatedTokenAddressKit(mint, owner, _allowOwnerOffCurve = false) {
+    const [ata] = await getProgramDerivedAddress({
+        programAddress: ATA_PROGRAM_ADDRESS,
+        seeds: [
+            addressEncoder.encode(owner),
+            addressEncoder.encode(TOKEN_PROGRAM_ADDRESS),
+            addressEncoder.encode(mint),
+        ],
+    });
+    return ata;
+}
+/**
+ * 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 function buildCreateAtaIdempotentIx(payer, ata, owner, mint) {
+    return {
+        programAddress: ATA_PROGRAM_ADDRESS,
+        accounts: [
+            // role 3 = writable signer; role 1 = writable; role 0 = readonly
+            { address: payer, role: 3 },
+            { address: ata, role: 1 },
+            { address: owner, role: 0 },
+            { address: mint, role: 0 },
+            { address: SYSTEM_PROGRAM_ADDRESS, role: 0 },
+            { address: TOKEN_PROGRAM_ADDRESS, role: 0 },
+        ],
+        data: new Uint8Array([1]), // SPL ATA program: 1 = CreateIdempotent
+    };
+}

package/lib/esm/solana/canonical-message.js

@@ -0,0 +1,128 @@
+/**
+ * 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.
+ */
+/**
+ * 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
+ * `ario-ant-escrow/src/canonical.rs::build_ant_escrow_claim_message`
+ * (header `ANT_ESCROW_CLAIM_HEADER = "ar.io ant-escrow claim"`). The on-chain
+ * program reconstructs these exact bytes and verifies the signature against
+ * them, so any drift (header, field set, or ordering) makes every claim fail
+ * `EthereumAddressMismatch` / signature verification.
+ *
+ * Format (UTF-8, line-feed separated, no trailing newline):
+ *
+ * ```text
+ * ar.io ant-escrow claim
+ * network: <network>
+ * recipient: <base64url(sha256(recipient_pubkey)) — 43 chars, no pad>
+ * 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 { sha256 } from '@noble/hashes/sha256';
+/** Header literal — must match Rust `ANT_ESCROW_CLAIM_HEADER`. */
+const CANONICAL_HEADER = 'ar.io ant-escrow claim';
+/**
+ * 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 function canonicalMessage(input) {
+    if (input.nonce.length !== 32) {
+        throw new Error(`canonicalMessage: nonce must be 32 bytes, got ${input.nonce.length}`);
+    }
+    const text = `${CANONICAL_HEADER}\n` +
+        `network: ${input.network}\n` +
+        `recipient: ${deriveRecipientId(input.recipient)}\n` +
+        `ant: ${input.antMint}\n` +
+        `claimant: ${input.claimant}\n` +
+        `nonce: ${bytesToHexLower(input.nonce)}`;
+    return new TextEncoder().encode(text);
+}
+/** Header literal — must match Rust `ESCROW_CLAIM_HEADER`. */
+const CANONICAL_HEADER_V2 = 'ar.io escrow claim';
+/**
+ * Build the v2 canonical claim message bytes for token/vault escrows.
+ * UTF-8 encoded, no trailing newline.
+ *
+ * Format:
+ * ```text
+ * ar.io escrow claim
+ * network: <network>
+ * recipient: <base64url(sha256(recipient_pubkey)) — 43 chars, no pad>
+ * 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 function canonicalMessageV2(input) {
+    if (input.assetId.length !== 32) {
+        throw new Error(`canonicalMessageV2: assetId must be 32 bytes, got ${input.assetId.length}`);
+    }
+    if (input.nonce.length !== 32) {
+        throw new Error(`canonicalMessageV2: nonce must be 32 bytes, got ${input.nonce.length}`);
+    }
+    const text = `${CANONICAL_HEADER_V2}\n` +
+        `network: ${input.network}\n` +
+        `recipient: ${deriveRecipientId(input.recipient)}\n` +
+        `type: ${input.assetType}\n` +
+        `asset: ${bytesToHexLower(input.assetId)}\n` +
+        `amount: ${input.amount.toString()}\n` +
+        `claimant: ${input.claimant}\n` +
+        `nonce: ${bytesToHexLower(input.nonce)}`;
+    return new TextEncoder().encode(text);
+}
+// =========================================
+// Shared utilities
+// =========================================
+/**
+ * Recipient identity bound into the claim message — `base64url(sha256(bytes))`
+ * with no padding (32-byte hash → 43 chars). Byte-identical to the contract's
+ * `canonical.rs::derive_recipient_id_b64url`. Input is the recipient pubkey
+ * bytes the deposit targeted (ETH 20-byte address / Solana 32-byte pubkey /
+ * Arweave RSA modulus, etc.).
+ */
+export function deriveRecipientId(recipient) {
+    if (recipient.length === 0) {
+        throw new Error('deriveRecipientId: recipient bytes must be non-empty');
+    }
+    // Node's 'base64url' encoding is unpadded — matches the Rust no-pad alphabet.
+    return Buffer.from(sha256(recipient)).toString('base64url');
+}
+/** Lowercase-hex encoding. Matches Rust `encode_hex_lowercase`. */
+export function bytesToHexLower(bytes) {
+    let s = '';
+    for (let i = 0; i < bytes.length; i++) {
+        const b = bytes[i];
+        s += (b >>> 4).toString(16);
+        s += (b & 0x0f).toString(16);
+    }
+    return s;
+}