@ar.io/sdk 4.0.0-solana.18 → 4.0.0-solana.20

package/lib/esm/solana/escrow.js

@@ -274,10 +274,36 @@ export class ANTEscrow {
         }
     }
 }
+/**
+ * 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 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 function isVaultClaimable(escrow) {
+    const nowSeconds = BigInt(Math.floor(Date.now() / 1000));
+    return nowSeconds >= escrow.vaultEndTimestamp + CLOCK_SKEW_TOLERANCE_SECONDS;
+}
 /**
  * Pre-flight the on-chain `VaultStillLocked` gate (ADR-022): refuse to build
- * a claim tx while the vault is still locked. Surfaces the unlock timestamp
- * so callers / UIs can show "claimable after <date>" instead of a doomed tx.
+ * 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
@@ -286,14 +312,15 @@ export class ANTEscrow {
  * @internal
  */
 export function assertVaultClaimable(escrow) {
-    const nowSeconds = BigInt(Math.floor(Date.now() / 1000));
-    if (escrow.vaultEndTimestamp > nowSeconds) {
+    if (!isVaultClaimable(escrow)) {
         const unlockIso = new Date(Number(escrow.vaultEndTimestamp) * 1000).toISOString();
         throw new Error(`Vault escrow is still locked until ${unlockIso} ` +
-            `(vault_end_timestamp=${escrow.vaultEndTimestamp}). ` +
-            `Active (still-locked) vault claims are not supported (ADR-022 / ` +
-            `VaultStillLocked) — wait until after the unlock timestamp, then ` +
-            `claim again to receive the tokens liquid.`);
+            `(vault_end_timestamp=${escrow.vaultEndTimestamp}; ` +
+            `the SDK adds a ${CLOCK_SKEW_TOLERANCE_SECONDS}s clock-skew buffer ` +
+            `before allowing a claim). Active (still-locked) vault claims are ` +
+            `rejected on-chain with VaultStillLocked (ADR-022) — wait until ` +
+            `after the unlock timestamp + buffer, then claim again to receive ` +
+            `the tokens liquid.`);
     }
 }
 /** Map the Codama-generated `EscrowToken` raw decoded type to our public
@@ -558,47 +585,85 @@ export class TokenEscrow {
         }, { programAddress: this.programId });
     }
     /**
-     * Submit an Arweave attestor's Ed25519 signature to release escrowed vault
-     * tokens. The on-chain handler delivers liquid tokens directly to
-     * `claimantTokenAccount`.
+     * **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.
      *
-     * **Vaults are only claimable after `vault_end_timestamp`.** Active
-     * (still-locked) vault claims are rejected on-chain with `VaultStillLocked`
-     * (ADR-022 / BD-107: the former active re-lock path was removed because its
-     * sibling-`vaulted_transfer` introspection had no 1:1 claim↔re-lock binding
-     * → reuse / relayer skim). This method pre-flights the same gate and throws
-     * a clear `vault still locked until <ISO>` error rather than building a tx
-     * that will fail on-chain. To revive "claim early, stay locked" see the
-     * restoration playbook in the contracts repo
-     * (`docs/RESTORE_ACTIVE_VAULT_RELOCK.md`).
+     * @deprecated cannot succeed alone — see {@link claimVaultArweaveIx}.
      */
-    async claimVaultArweave(args) {
-        const escrow = await this.requireVaultEscrow(args.depositor, args.assetId);
-        if (escrow.recipientProtocol !== 'arweave') {
-            throw new Error(`escrow recipient is ${escrow.recipientProtocol}, not arweave`);
+    async claimVaultArweave(_args) {
+        throw new Error('claimVaultArweave cannot complete the Arweave attested vault-claim ' +
+            'in a single SDK call: the on-chain handler requires an ' +
+            'Ed25519Program sigverify ix at idx-1 of the claim ix, which ' +
+            'must carry the attestor service’s signature over the canonical ' +
+            'claim message (ADR-017). The SDK does not know your attestor URL. ' +
+            'Use claimVaultArweaveIx() instead and bundle the sigverify ix ' +
+            'yourself: ' +
+            '[createAtaIx?, ed25519SigverifyIx, claimVaultArweaveIx, ...]. ' +
+            'See ar-io-solana-escrow-app/src/pages/ClaimPage.tsx for the ' +
+            'reference composition, and ADR-022 / VaultStillLocked for the ' +
+            'still-locked rejection (use isVaultClaimable() to pre-flight).');
+    }
+    /**
+     * 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]);
+     *   ```
+     */
+    async claimVaultArweaveIx(args) {
+        if (args.messageNonce.length !== 32) {
+            throw new Error('messageNonce must be 32 bytes');
         }
-        // ADR-022 / VaultStillLocked: pre-flight the on-chain lock gate.
-        assertVaultClaimable(escrow);
-        const signer = this.requireSigner('claimVaultArweave');
+        const signer = this.requireSigner('claimVaultArweaveIx');
         const [escrowPda] = await getEscrowVaultPDA(args.depositor, args.assetId, this.programId);
-        // `args.signature` and `args.saltLen` are no longer fed to the
-        // builder — the on-chain `claim_vault_arweave_attested` ix verifies
-        // the attestor's Ed25519 signature via instruction-introspection
-        // of a preceding sigverify ix. See doc on `claimArweaveIx`.
-        const claimIx = getClaimVaultArweaveAttestedInstruction({
+        return getClaimVaultArweaveAttestedInstruction({
             escrow: escrowPda,
             escrowTokenAccount: args.escrowTokenAccount,
             claimantTokenAccount: args.claimantTokenAccount,
             claimant: args.claimant,
             depositor: args.depositor,
             payer: signer,
-            messageNonce: escrow.nonce,
+            messageNonce: args.messageNonce,
         }, { programAddress: this.programId });
-        const createClaimantAtaIx = await this._createClaimantAtaIfCanonical(args.claimant, args.claimantTokenAccount, escrow.arioMint);
-        const ixs = createClaimantAtaIx
-            ? [createClaimantAtaIx, claimIx]
-            : [claimIx];
-        return this.send(ixs, 400_000);
     }
     /**
      * Submit an Ethereum ECDSA signature to release escrowed vault tokens. See

package/lib/esm/solana/index.js

@@ -68,7 +68,13 @@ export { SolanaANTWriteable } from './ant-writeable.js';
 export { SolanaANTRegistryReadable } from './ant-registry-readable.js';
 export { SolanaANTRegistryWriteable } from './ant-registry-writeable.js';
 // ANT-escrow client (trustless multi-protocol custody — Arweave RSA-PSS / Ethereum ECDSA)
-export { ANTEscrow, TokenEscrow } from './escrow.js';
+export { ANTEscrow, TokenEscrow, 
+// Vault-claim pre-flight helpers (ADR-022 / VaultStillLocked).
+// Exported so downstream UIs can gate their Submit buttons using the
+// SAME forward CLOCK_SKEW_TOLERANCE_SECONDS buffer the SDK's
+// assertVaultClaimable throws use — keeping pre-flight and UI gates
+// in lock-step so users never see a raw on-chain error.
+assertVaultClaimable, isVaultClaimable, CLOCK_SKEW_TOLERANCE_SECONDS, } from './escrow.js';
 // Canonical claim-message helper (byte-equivalent to Rust impl)
 export { canonicalMessage, canonicalMessageV2, bytesToHexLower, } from './canonical-message.js';
 // ANT spawn (mint MPL Core asset + initialize ario-ant state in one tx)

package/lib/esm/version.js

@@ -14,4 +14,4 @@
  * limitations under the License.
  */
 // AUTOMATICALLY GENERATED FILE - DO NOT TOUCH
-export const version = '4.0.0-solana.18';
+export const version = '4.0.0-solana.20';

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

@@ -185,10 +185,33 @@ 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. Surfaces the unlock timestamp
- * so callers / UIs can show "claimable after <date>" instead of a doomed tx.
+ * 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
@@ -313,21 +336,24 @@ export declare class TokenEscrow {
         messageNonce: Uint8Array;
     }): Promise<Instruction>;
     /**
-     * Submit an Arweave attestor's Ed25519 signature to release escrowed vault
-     * tokens. The on-chain handler delivers liquid tokens directly to
-     * `claimantTokenAccount`.
+     * **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.
      *
-     * **Vaults are only claimable after `vault_end_timestamp`.** Active
-     * (still-locked) vault claims are rejected on-chain with `VaultStillLocked`
-     * (ADR-022 / BD-107: the former active re-lock path was removed because its
-     * sibling-`vaulted_transfer` introspection had no 1:1 claim↔re-lock binding
-     * → reuse / relayer skim). This method pre-flights the same gate and throws
-     * a clear `vault still locked until <ISO>` error rather than building a tx
-     * that will fail on-chain. To revive "claim early, stay locked" see the
-     * restoration playbook in the contracts repo
-     * (`docs/RESTORE_ACTIVE_VAULT_RELOCK.md`).
+     * 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: {
+    claimVaultArweave(_args: {
         depositor: Address;
         assetId: Uint8Array;
         claimant: Address;
@@ -336,6 +362,49 @@ export declare class TokenEscrow {
         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

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

@@ -51,7 +51,7 @@ export type { SolanaANTRegistryConfig } from './ant-registry-readable.js';
 export { SolanaANTRegistryWriteable } from './ant-registry-writeable.js';
 export type { SolanaANTRegistryWriteableConfig } from './ant-registry-writeable.js';
 export type { AclMaintenanceOp, AclMaintenanceRole, } from '../types/ant-registry.js';
-export { ANTEscrow, TokenEscrow } from './escrow.js';
+export { ANTEscrow, TokenEscrow, assertVaultClaimable, isVaultClaimable, CLOCK_SKEW_TOLERANCE_SECONDS, } from './escrow.js';
 export type { ANTEscrowConfig, EscrowAntState, EscrowAssetType, EscrowProtocol, EscrowTokenState, } from './escrow.js';
 export { canonicalMessage, canonicalMessageV2, bytesToHexLower, } from './canonical-message.js';
 export type { CanonicalMessageInput, CanonicalMessageV2Input, EscrowNetwork, } from './canonical-message.js';

package/lib/types/version.d.ts

@@ -13,4 +13,4 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export declare const version = "4.0.0-solana.17";
+export declare const version = "4.0.0-solana.19";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/sdk",
-  "version": "4.0.0-solana.18",
+  "version": "4.0.0-solana.20",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ar-io/ar-io-sdk.git"