@ar.io/sdk 4.0.0-solana.9 → 4.0.0

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

@@ -1,34 +1,31 @@
 /**
- * Account deserialization for AR.IO Solana programs.
+ * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
  *
- * Reads raw account data (Borsh-encoded by Anchor) and returns SDK-compatible
- * types. Each function skips the 8-byte Anchor discriminator, then reads
- * fields in the exact order defined in the Rust structs.
+ * 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
  *
- * NOTE on discriminators: this module no longer exports a hand-rolled
- * discriminator table. The Codama-generated account modules under
- * `./generated/<program>/accounts/` already export
- * `<NAME>_DISCRIMINATOR: Uint8Array` constants pulled directly from each
- * IDL, so they're guaranteed to match the on-chain struct names.
- * Use those at the call site (see `io-readable.ts` for the
- * `getAccountsByDiscriminator` helper that bs58-encodes them for
- * `getProgramAccounts` memcmp filters).
+ *     http://www.apache.org/licenses/LICENSE-2.0
  *
- * Borsh encoding rules (Anchor default):
- *   - u8/bool: 1 byte
- *   - u16: 2 bytes LE
- *   - u32: 4 bytes LE
- *   - u64: 8 bytes LE
- *   - u128: 16 bytes LE
- *   - i64: 8 bytes LE (signed)
- *   - Pubkey: 32 bytes
- *   - String: 4-byte LE length prefix + UTF-8 bytes
- *   - Option<T>: 1-byte tag (0=None, 1=Some) + T if Some
- *   - Vec<T>: 4-byte LE length + T[] elements
- *   - Enum: 1-byte variant index
+ * 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.
+ */
+/**
+ * Thin adapter layer over Codama-generated account decoders from
+ * `@ar.io/solana-contracts`. Each function accepts a raw `Buffer` (as
+ * returned by `fetchEncodedAccount(...).data`) and returns the same
+ * SDK-compatible plain-object shape the hand-rolled BorshReader
+ * implementations used to return.
+ *
+ * The Codama decoders return `Address` (branded string) and `bigint`
+ * for numeric fields. This module maps them to plain `string` and
+ * `number` so the SDK's public API contract doesn't change.
  */
 import { type Address } from '@solana/kit';
-import type { AoArNSNameData, AoGateway, AoGatewayRegistrySettings, AoVaultData } from '../types/io.js';
+import type { ArNSNameData, Gateway, GatewayRegistrySettings, VaultData } from '../types/io.js';
 declare class BorshReader {
     private data;
     private offset;
@@ -46,6 +43,7 @@ declare class BorshReader {
     readString(): string;
     readOptionI64(): number | undefined;
     readOptionU32(): number | undefined;
+    readOptionU16(): number | undefined;
     skip(bytes: number): void;
     getOffset(): number;
     remaining(): number;
@@ -68,105 +66,38 @@ declare class BorshWriter {
     writeU64(val: bigint | number): void;
     writeI64(val: bigint | number): void;
     writePubkey(key: Address): void;
-    /** Write raw bytes without a length prefix (fixed-size fields). */
     writeFixedBytes(data: Buffer | Uint8Array): void;
     writeString(str: string): void;
     writeOptionI64(val: number | undefined): void;
     writeOptionU32(val: number | undefined): void;
     writeOptionPubkey(key: Address | undefined): void;
     writeOptionString(val: string | undefined): void;
-    /** Borsh `Option<Vec<String>>`: 0/1 tag, then u32 length + each string. */
     writeOptionStringVec(val: string[] | undefined): void;
     toBuffer(): Buffer;
     getOffset(): number;
 }
-/**
- * Internal variant of {@link deserializeGateway} that additionally surfaces
- * the on-chain `cumulative_reward_per_token` u128 accumulator. Used by the
- * live delegation balance pipeline ({@link computeLiveDelegationBalance} via
- * `getGatewayAccumulators` in `io-readable.ts`).
- *
- * Not part of the public AoGateway shape — `bigint` is not JSON-serializable
- * and would leak through `getGateway` / `getGateways`. Prefer
- * {@link deserializeGateway} everywhere except inside live-balance plumbing.
- *
- * PDA: ["gateway", operator_pubkey] in ario-gar program.
- */
-export declare function deserializeGatewayWithAccumulator(data: Buffer): AoGateway & {
+export declare function deserializeGatewayWithAccumulator(data: Buffer): Gateway & {
     operator: string;
     cumulativeRewardPerToken: bigint;
 };
-/**
- * Deserialize a Gateway account from raw bytes.
- *
- * Returns the SDK-compatible AoGateway type (plus `operator: string`).
- * The on-chain `cumulative_reward_per_token` u128 is intentionally NOT
- * surfaced on the returned object — `bigint` is not JSON-serializable,
- * and leaking it through `getGateway` / `getGateways` would break
- * downstream consumers that call `JSON.stringify` on results. Use
- * {@link deserializeGatewayWithAccumulator} from within the live-balance
- * pipeline when the accumulator value is actually needed.
- */
-export declare function deserializeGateway(data: Buffer): AoGateway & {
+export declare function deserializeGateway(data: Buffer): Gateway & {
     operator: string;
 };
-/**
- * Deserialize an ArNS record account from raw bytes.
- * PDA: ["arns_record", hash(name)] in ario-arns program.
- *
- * Field order is **load-bearing** and mirrors the on-chain
- * `ArnsRecord` struct in `contracts/programs/ario-arns/src/state/mod.rs`.
- * Every fixed-size field appears before the variable-length `name` so
- * `getProgramAccounts` callers can `memcmp`-filter on `ant` (offset
- * 72) — see `ARNS_RECORD_ANT_OFFSET` in `./constants.ts`. If you
- * touch the contract layout, both files have to move in lockstep.
- */
-export declare function deserializeArnsRecord(data: Buffer): AoArNSNameData & {
+export declare function deserializeArnsRecord(data: Buffer): ArNSNameData & {
     name: string;
     owner: string;
 };
-/**
- * Deserialize a Vault account from raw bytes.
- * PDA: ["vault", owner, vault_id] in ario-core program.
- *
- * On-chain layout (matches `state::Vault`):
- *   disc(8) + owner(Pubkey=32) + vault_id(u64=8) + amount(u64=8)
- *   + start_timestamp(i64=8) + end_timestamp(i64=8)
- *   + controller(Option<Pubkey>=33) + revocable(bool=1) + bump(u8=1)
- */
-export declare function deserializeVault(data: Buffer): AoVaultData & {
+export declare function deserializeVault(data: Buffer): VaultData & {
     owner: string;
 };
 export type DeserializedDelegation = {
     gateway: string;
     delegator: string;
-    /**
-     * Last-settled principal (raw `Delegation.amount` from on-chain state).
-     * This value is stale between epochs — see `INVARIANTS.md` in the contracts
-     * repo. Use `computeLiveDelegationBalance` (with the gateway's current
-     * `cumulativeRewardPerToken`) to get the actual current balance.
-     */
     delegatedStake: number;
     startTimestamp: number;
-    /**
-     * Snapshot of `gateway.cumulative_reward_per_token` at the last settlement.
-     * Required input to `computeLiveDelegationBalance`.
-     */
     rewardDebt: bigint;
 };
-/**
- * Deserialize a Delegation account from raw bytes.
- * PDA: ["delegation", gateway, delegator] in ario-gar program.
- */
 export declare function deserializeDelegation(data: Buffer): DeserializedDelegation;
-/**
- * Deserialize a Balance account from raw bytes.
- * PDA: ["balance", owner] in ario-core program.
- *
- * Backed by the Codama-generated decoder so the encoder
- * (`getBalanceEncoder` used by migration/snapshot) and decoder share a single
- * source of truth derived from the `ario_core` IDL.
- */
 export declare function deserializeBalance(data: Buffer): {
     owner: string;
     balance: number;
@@ -177,20 +108,12 @@ export declare function deserializeEpochSettings(data: Buffer): {
     prescribedNameCount: number;
     maxObservers: number;
 };
-/**
- * Deserialize an ArioConfig account from raw bytes.
- * PDA: ["ario_config"] in ario-core program.
- */
 export declare function deserializeArioConfig(data: Buffer): {
     totalSupply: number;
     protocolBalance: number;
     circulatingSupply: number;
     lockedSupply: number;
 };
-/**
- * Deserialize a DemandFactor account from raw bytes.
- * PDA: ["demand_factor"] in ario-arns program.
- */
 export declare function deserializeDemandFactor(data: Buffer): {
     currentDemandFactor: number;
     currentPeriod: number;
@@ -200,19 +123,11 @@ export declare function deserializeDemandFactor(data: Buffer): {
     trailingPeriodRevenues: number[];
     fees: number[];
 };
-/**
- * Deserialize a ReservedName account from raw bytes.
- * PDA: ["reserved_name", hash(name)] in ario-arns program.
- */
 export declare function deserializeReservedName(data: Buffer): {
     name: string;
     target?: string;
     endTimestamp?: number;
 };
-/**
- * Deserialize a ReturnedName account from raw bytes.
- * PDA: ["returned_name", hash(name)] in ario-arns program.
- */
 export declare function deserializeReturnedName(data: Buffer): {
     name: string;
     startTimestamp: number;
@@ -220,10 +135,6 @@ export declare function deserializeReturnedName(data: Buffer): {
     initiator: string;
     premiumMultiplier: number;
 };
-/**
- * Deserialize a Withdrawal account from raw bytes.
- * PDA: ["withdrawal", gateway, owner, withdrawal_id] in ario-gar program.
- */
 export declare function deserializeWithdrawal(data: Buffer): {
     owner: string;
     vaultId: string;
@@ -233,49 +144,24 @@ export declare function deserializeWithdrawal(data: Buffer): {
     endTimestamp: number;
     isDelegate: boolean;
 };
-/**
- * Deserialize a RedelegationRecord account from raw bytes.
- * PDA: ["redelegation", delegator] in ario-gar program.
- */
 export declare function deserializeRedelegationRecord(data: Buffer): {
     delegator: string;
     redelegationCount: number;
     lastRedelegationAt: number;
     feeResetAt: number;
 };
-/**
- * Deserialize a PrimaryNameRequest account from raw bytes.
- * PDA: ["primary_name_request", initiator] in ario-core program.
- */
 export declare function deserializePrimaryNameRequest(data: Buffer): {
     name: string;
     initiator: string;
     startTimestamp: number;
     endTimestamp: number;
 };
-/**
- * Deserialize a GarSettings account from raw bytes and return
- * the full AoGatewayRegistrySettings type.
- * PDA: ["gar_settings"] in ario-gar program.
- *
- * Fields not stored in GarSettings are filled with protocol defaults.
- */
-export declare function deserializeGarSettings(data: Buffer): AoGatewayRegistrySettings;
-/**
- * Deserialize supply counter fields from GatewaySettings account.
- * These 3 fields were added after arns_program_id, before bump.
- */
+export declare function deserializeGarSettings(data: Buffer): GatewayRegistrySettings;
 export declare function deserializeGarSupplyCounters(data: Buffer): {
     totalStaked: number;
     totalDelegated: number;
     totalWithdrawn: number;
 };
-/**
- * Deserialize the full EpochSettings account from raw bytes.
- * Unlike deserializeEpochSettings (which returns 4 fields), this reads
- * all fields from the on-chain struct.
- * PDA: ["epoch_settings"] in ario-gar program.
- */
 export declare function deserializeEpochSettingsFull(data: Buffer): {
     currentEpochIndex: number;
     genesisTimestamp: number;
@@ -289,13 +175,6 @@ export declare function deserializeEpochSettingsFull(data: Buffer): {
     observerRewardRatio: number;
     maxConsecutiveFailures: number;
 };
-/**
- * Deserialize an Epoch account from raw bytes.
- * PDA: ["epoch", epoch_index_le_bytes] in ario-gar program.
- *
- * This is a zero-copy account with #[repr(C)] layout (not Borsh).
- * Fields are at fixed offsets after the 8-byte discriminator.
- */
 export declare function deserializeEpoch(data: Buffer): {
     epochIndex: number;
     startTimestamp: number;
@@ -319,10 +198,6 @@ export declare function deserializeEpoch(data: Buffer): {
     prescribedNameHashes: Buffer[];
     hasObserved: Uint8Array;
 };
-/**
- * Deserialize an Observation account from raw bytes.
- * PDA: ["observation", epoch_index_le_bytes, observer_pubkey] in ario-gar program.
- */
 export declare function deserializeObservation(data: Buffer): {
     epochIndex: number;
     observer: string;
@@ -331,10 +206,6 @@ export declare function deserializeObservation(data: Buffer): {
     reportTxId: string;
     submittedAt: number;
 };
-/**
- * Deserialize an AntConfig account from raw bytes.
- * PDA: ["ant_config", mint] in ario-ant program.
- */
 export declare function deserializeAntConfig(data: Buffer): {
     mint: string;
     name: string;
@@ -345,18 +216,10 @@ export declare function deserializeAntConfig(data: Buffer): {
     owner: string;
     version: number;
 };
-/**
- * Deserialize an AntControllers account from raw bytes.
- * PDA: ["ant_controllers", mint] in ario-ant program.
- */
 export declare function deserializeAntControllers(data: Buffer): {
     mint: string;
     controllers: string[];
 };
-/**
- * Deserialize an AntRecord account from raw bytes.
- * PDA: ["ant_record", mint, hash(undername)] in ario-ant program.
- */
 export declare function deserializeAntRecord(data: Buffer): {
     mint: string;
     undername: string;
@@ -366,10 +229,6 @@ export declare function deserializeAntRecord(data: Buffer): {
     priority?: number;
     owner?: string;
 };
-/**
- * Deserialize an AntRecordMetadata account from raw bytes.
- * This is a separate PDA that holds optional per-record metadata fields.
- */
 export declare function deserializeAntRecordMetadata(data: Buffer): {
     mint: string;
     displayName?: string;
@@ -377,54 +236,25 @@ export declare function deserializeAntRecordMetadata(data: Buffer): {
     description?: string;
     keywords?: string[];
 };
-/**
- * Per-user ACL entry: a `(asset, role)` tuple where `role` is `0=Owner`,
- * `1=Controller` (see `AclRole` in ario-ant). The byte layout matches the
- * on-chain `AclEntry` (33 bytes).
- */
 export type DeserializedAclEntry = {
     asset: string;
     role: number;
 };
-/**
- * Deserialize an `AclConfig` account (paginated ACL head — ADR-012).
- * PDA: `["acl_config", user]` in ario-ant program.
- *
- * Holds counts but no entries. Read this first, then fan out to each
- * `AclPage` PDA (`["acl_page", user, page_idx_le]`) for the entries.
- */
 export declare function deserializeAclConfig(data: Buffer): {
     user: string;
     pageCount: bigint;
     totalEntries: bigint;
 };
-/**
- * Deserialize an `AclPage` account (paginated ACL page — ADR-012).
- * PDA: `["acl_page", user, page_idx_le]` in ario-ant program.
- *
- * Stores up to `MAX_ACL_PAGE_ENTRIES` `(asset, role)` entries. Pages can
- * be sparse mid-life (entries are removed via `swap_remove`) — the SDK's
- * append path fills the first non-full page to keep density reasonable.
- */
 export declare function deserializeAclPage(data: Buffer): {
     user: string;
     pageIdx: bigint;
     entries: DeserializedAclEntry[];
 };
-/**
- * Deserialize a PrimaryName account from raw bytes.
- * PDA: ["primary_name", owner] in ario-core program.
- */
 export declare function deserializePrimaryName(data: Buffer): {
     owner: string;
     name: string;
-    processId: string;
     startTimestamp: number;
 };
-/**
- * Deserialize an Allowlist entry account from raw bytes.
- * PDA: ["allowlist", gateway, delegate] in ario-gar program.
- */
 export declare function deserializeAllowlist(data: Buffer): {
     gateway: string;
     delegate: string;

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

@@ -1,3 +1,18 @@
+/**
+ * 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.
  *
@@ -16,11 +31,13 @@
  * 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 {
-    version: number;
+    /** On-chain schema version, as decoded by the generated client. */
+    version: EscrowAnt['version'];
     bump: number;
     depositor: Address;
     antMint: Address;
@@ -35,9 +52,13 @@ export interface ANTEscrowConfig {
     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}.
+     * 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;
@@ -164,7 +185,8 @@ export declare class ANTEscrow {
 }
 export type EscrowAssetType = 'token' | 'vault';
 export interface EscrowTokenState {
-    version: number;
+    /** On-chain schema version, as decoded by the generated client. */
+    version: EscrowToken['version'];
     bump: number;
     depositor: Address;
     assetType: EscrowAssetType;
@@ -178,6 +200,41 @@ export interface EscrowTokenState {
     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
@@ -294,32 +351,80 @@ export declare class TokenEscrow {
         messageNonce: Uint8Array;
     }): Promise<Instruction>;
     /**
-     * Submit an Arweave RSA-PSS-4096 signature to release escrowed vault tokens.
+     * **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.
      *
-     * 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.
+     * 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.
      *
-     * 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.
+     * @deprecated cannot succeed alone — see {@link claimVaultArweaveIx}.
      */
-    claimVaultArweave(args: {
+    claimVaultArweave(_args: {
         depositor: Address;
         assetId: Uint8Array;
         claimant: Address;
         claimantTokenAccount: Address;
         escrowTokenAccount: Address;
-        payerTokenAccount: 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} for the expired/active vault routing semantics.
-     * Auto-bundles the sibling `vaulted_transfer` ix for active vaults.
+     * {@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;
@@ -327,51 +432,23 @@ export declare class TokenEscrow {
         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).
+     * 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;
-    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.