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

package/lib/esm/solana/escrow.js

@@ -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,10 @@
  * Borsh codec, and account-meta wiring derived from the on-chain IDL.
  */
 import { fetchMaybeEscrowAnt, fetchMaybeEscrowToken, getCancelDepositInstruction, getCancelTokenDepositInstruction, getCancelVaultDepositInstruction, getClaimAntArweaveAttestedInstruction, getClaimAntEthereumInstruction, getClaimTokensArweaveAttestedInstruction, getClaimTokensEthereumInstruction, getClaimVaultArweaveAttestedInstruction, getClaimVaultEthereumInstruction, getDepositAntInstruction, getDepositTokensInstruction, getDepositVaultInstruction, getUpdateRecipientInstruction, getUpdateTokenRecipientInstruction, getUpdateVaultRecipientInstruction, } from '@ar.io/solana-contracts/ant-escrow';
-import { fetchMaybeVaultCounter, getVaultedTransferInstructionAsync, } from '@ar.io/solana-contracts/core';
 import { Logger } from '../common/logger.js';
 import { getAssociatedTokenAddressKit } from './ata.js';
 import { ARIO_ANT_ESCROW_PROGRAM_ID, ARIO_CORE_PROGRAM_ID, ESCROW_ARWEAVE_PUBKEY_LEN, ESCROW_ASSET_TYPE_VAULT, ESCROW_ETHEREUM_PUBKEY_LEN, ESCROW_PROTOCOL_ARWEAVE, ESCROW_PROTOCOL_ETHEREUM, } from './constants.js';
-import { getEscrowAntPDA, getEscrowTokenPDA, getEscrowVaultPDA, getVaultCounterPDA, getVaultPDA, } from './pda.js';
+import { getEscrowAntPDA, getEscrowTokenPDA, getEscrowVaultPDA, } from './pda.js';
 import { sendAndConfirm } from './send.js';
 /** Map the Codama-generated `EscrowAnt` raw decoded type to our public
  *  `EscrowAntState` with protocol enum + active-prefix pubkey slice. */
@@ -275,6 +289,55 @@ 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, 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 function assertVaultClaimable(escrow) {
+    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}; ` +
+            `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
  *  `EscrowTokenState` with protocol enum + active-prefix pubkey slice. */
 function toEscrowTokenState(raw) {
@@ -537,100 +600,125 @@ export class TokenEscrow {
         }, { programAddress: this.programId });
     }
     /**
-     * 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}.
      */
-    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');
         }
-        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,
-            payerTokenAccount: args.payerTokenAccount,
             claimant: args.claimant,
             depositor: args.depositor,
             payer: signer,
-            messageNonce: escrow.nonce,
+            messageNonce: args.messageNonce,
         }, { programAddress: this.programId });
-        const ixs = await this.maybeBundleVaultedTransfer(escrow, args, claimIx);
-        return this.send(ixs, 400_000);
     }
     /**
      * 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).
      */
     async claimVaultEthereum(args) {
         const escrow = await this.requireVaultEscrow(args.depositor, args.assetId);
         if (escrow.recipientProtocol !== 'ethereum') {
             throw new Error(`escrow recipient is ${escrow.recipientProtocol}, not ethereum`);
         }
+        assertVaultClaimable(escrow);
         const signer = this.requireSigner('claimVaultEthereum');
         const [escrowPda] = await getEscrowVaultPDA(args.depositor, args.assetId, this.programId);
         const claimIx = getClaimVaultEthereumInstruction({
             escrow: escrowPda,
             escrowTokenAccount: args.escrowTokenAccount,
             claimantTokenAccount: args.claimantTokenAccount,
-            payerTokenAccount: args.payerTokenAccount,
             claimant: args.claimant,
             depositor: args.depositor,
             payer: signer,
             messageNonce: escrow.nonce,
             signature: args.signature,
         }, { programAddress: this.programId });
-        const ixs = await this.maybeBundleVaultedTransfer(escrow, args, claimIx);
+        const createClaimantAtaIx = await this._createClaimantAtaIfCanonical(args.claimant, args.claimantTokenAccount, escrow.arioMint);
+        const ixs = createClaimantAtaIx
+            ? [createClaimantAtaIx, claimIx]
+            : [claimIx];
         return this.send(ixs);
     }
     /**
-     * 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,
@@ -643,52 +731,6 @@ export class TokenEscrow {
         const signer = this.requireSigner('createClaimantAtaIfCanonical');
         return buildCreateAtaIdempotentIx(signer.address, canonical, claimant, mint);
     }
-    async maybeBundleVaultedTransfer(escrow, args, claimIx) {
-        const nowSeconds = BigInt(Math.floor(Date.now() / 1000));
-        const remaining = escrow.vaultEndTimestamp - nowSeconds;
-        if (remaining <= 0n) {
-            // Expired vault → claim handler delivers liquid to claimantTokenAccount.
-            // Idempotent-create that ATA if it's the canonical derivation so a
-            // first-time recipient just works.
-            const createClaimantAtaIx = await this._createClaimantAtaIfCanonical(args.claimant, args.claimantTokenAccount, escrow.arioMint);
-            return createClaimantAtaIx ? [createClaimantAtaIx, claimIx] : [claimIx];
-        }
-        const signer = this.requireSigner('maybeBundleVaultedTransfer');
-        const nextId = await this.getNextVaultId(args.claimant);
-        const [vaultPda] = await getVaultPDA(args.claimant, nextId, this.coreProgram);
-        const vaultATA = await getAssociatedTokenAddressKit(escrow.arioMint, vaultPda, true);
-        // Active-vault path: `claim_vault_*` still validates the claimant ATA
-        // at account-load-time (Anchor `Account<TokenAccount>` constraint),
-        // even though no liquid is written to it. Idempotent-create so a fresh
-        // claimant doesn't fail the ix with AccountNotInitialized (#3012).
-        const createClaimantAtaIx = await this._createClaimantAtaIfCanonical(args.claimant, args.claimantTokenAccount, escrow.arioMint);
-        // The new vault PDA's ATA must exist before `vaulted_transfer` reads it
-        // (else `AccountNotInitialized` #3012). Idempotent so a retry after a
-        // partial-failure tx is safe. Placed after the claim ix to preserve
-        // the "claim first" tx ordering invariant.
-        const createVaultAtaIx = buildCreateAtaIdempotentIx(signer.address, vaultATA, vaultPda, escrow.arioMint);
-        const vaultedIx = await getVaultedTransferInstructionAsync({
-            vault: vaultPda,
-            senderTokenAccount: args.payerTokenAccount,
-            vaultTokenAccount: vaultATA,
-            recipient: args.claimant,
-            sender: signer,
-            amount: escrow.amount,
-            lockDurationSeconds: remaining,
-            revocable: escrow.vaultRevocable,
-        }, { programAddress: this.coreProgram });
-        const head = createClaimantAtaIx ? [createClaimantAtaIx] : [];
-        return [...head, claimIx, createVaultAtaIx, vaultedIx];
-    }
-    /** Read the recipient's `VaultCounter.nextId`, defaulting to 0n if the
-     *  counter PDA hasn't been initialised yet (first vault for that owner). */
-    async getNextVaultId(owner) {
-        const [counterPda] = await getVaultCounterPDA(owner, this.coreProgram);
-        const account = await fetchMaybeVaultCounter(this.rpc, counterPda, {
-            commitment: this.commitment,
-        });
-        return account.exists ? account.data.nextId : 0n;
-    }
     // -------------------------------------------------------------------
     // Write — cancel
     // -------------------------------------------------------------------

package/lib/esm/solana/events.js

@@ -1,210 +1,31 @@
 /**
- * AR.IO Solana event decoders — consumer-facing API.
+ * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
  *
- * Anchor `#[event]` emits surface as `Program data: <base64>` log lines
- * inside the surrounding instruction's logs. The base64 blob is
- * `[discriminator(8) || borsh_payload]`, where the discriminator is
- * `sha256("event:<EventName>")[..8]`.
+ * 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
  *
- * This module wraps the per-program codecs in
- * `sdk/src/solana/generated/<program>/events/` (auto-emitted by
- * `sdk/scripts/events-codegen.mjs`) into:
- *   - a discriminated union `AnyEvent` covering every event the
- *     AR.IO contracts emit
- *   - per-program union types for filtering
- *   - log-walking utilities that route `Program data:` lines back to
- *     the program that emitted them (so events emitted from a CPI'd
- *     handler get attributed to the correct program)
- *   - a typed `parseTransactionEvents(rpc, signature)` helper
+ *     http://www.apache.org/licenses/LICENSE-2.0
  *
- * Event payloads are returned with `bigint` for u64 / i64 fields and
- * `Address` for pubkey fields, matching the rest of the kit-native
- * SDK. To narrow on a specific event, use the `name` discriminator or
- * the per-event type guards exported alongside the union.
- *
- * Live event subscription (websocket / Helius / Geyser) is out of
- * scope here — this module is the decoder layer that all those
- * mechanisms can build on. See `parseTransactionEvents` for the
- * pull-based model.
+ * 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.
  */
-import { getBase64Encoder, } from '@solana/kit';
-import { ARIO_ANT_PROGRAM_ADDRESS } from '@ar.io/solana-contracts/ant';
-import { ARIO_ANT_ESCROW_PROGRAM_ADDRESS } from '@ar.io/solana-contracts/ant-escrow';
-import { ARIO_ARNS_PROGRAM_ADDRESS } from '@ar.io/solana-contracts/arns';
-import { ARIO_CORE_PROGRAM_ADDRESS } from '@ar.io/solana-contracts/core';
-import { ARIO_GAR_PROGRAM_ADDRESS } from '@ar.io/solana-contracts/gar';
-import * as escrowEvents from './generated/ant-escrow/events/index.js';
-import * as antEvents from './generated/ant/events/index.js';
-import * as arnsEvents from './generated/arns/events/index.js';
-import * as coreEvents from './generated/core/events/index.js';
-import * as garEvents from './generated/gar/events/index.js';
-const PROGRAM_DATA_PREFIX = 'Program data: ';
-let DISPATCH = null;
-function buildDispatch() {
-    const table = new Map();
-    const groups = [
-        [ARIO_CORE_PROGRAM_ADDRESS, coreEvents],
-        [ARIO_GAR_PROGRAM_ADDRESS, garEvents],
-        [ARIO_ARNS_PROGRAM_ADDRESS, arnsEvents],
-        [ARIO_ANT_PROGRAM_ADDRESS, antEvents],
-        [ARIO_ANT_ESCROW_PROGRAM_ADDRESS, escrowEvents],
-    ];
-    for (const [programId, mod] of groups) {
-        for (const [exportName, exportValue] of Object.entries(mod)) {
-            // Discriminators export as `EVENT_NAME_DISCRIMINATOR` constants of
-            // type Uint8Array. The matching decoder is `getEventNameDecoder`.
-            if (!exportName.endsWith('_DISCRIMINATOR') ||
-                !(exportValue instanceof Uint8Array)) {
-                continue;
-            }
-            // Recover the event PascalCase name from the SCREAMING_SNAKE
-            // discriminator constant: TRANSFER_EVENT_DISCRIMINATOR → TransferEvent
-            const eventName = screamingSnakeToPascal(exportName.slice(0, -'_DISCRIMINATOR'.length));
-            const decoderKey = `get${eventName}Decoder`;
-            const decoderFactory = mod[decoderKey];
-            if (typeof decoderFactory !== 'function') {
-                // Should never happen — codegen always emits both consts together —
-                // but skip defensively rather than crash at import time.
-                continue;
-            }
-            const decoder = decoderFactory.call(null);
-            const hex = bytesToHex(exportValue);
-            table.set(hex, {
-                name: eventName,
-                programId,
-                decode: (blob) => decoder.decode(blob),
-            });
-        }
-    }
-    return table;
-}
-function dispatch() {
-    if (DISPATCH === null)
-        DISPATCH = buildDispatch();
-    return DISPATCH;
-}
-export function parseEventsFromLogs(logs, filter) {
-    const table = dispatch();
-    const stack = [];
-    const out = [];
-    for (const line of logs) {
-        // Track CPI nesting via the standard Solana log format:
-        //   "Program <pubkey> invoke [N]"
-        //   "Program <pubkey> success"
-        //   "Program <pubkey> failed: ..."
-        const invoke = line.match(/^Program ([A-HJ-NP-Za-km-z1-9]{32,44}) invoke \[\d+\]$/);
-        if (invoke) {
-            stack.push(invoke[1]);
-            continue;
-        }
-        const ended = line.match(/^Program ([A-HJ-NP-Za-km-z1-9]{32,44}) (success|failed:.*)$/);
-        if (ended) {
-            // Pop the matching stack frame. Solana guarantees these are
-            // properly nested.
-            const top = stack.length > 0 ? stack[stack.length - 1] : undefined;
-            if (top === ended[1])
-                stack.pop();
-            continue;
-        }
-        if (!line.startsWith(PROGRAM_DATA_PREFIX))
-            continue;
-        const blob = decodeBase64(line.slice(PROGRAM_DATA_PREFIX.length).trim());
-        if (blob === null || blob.length < 8)
-            continue;
-        const hex = bytesToHex(blob.subarray(0, 8));
-        const entry = table.get(hex);
-        if (!entry)
-            continue;
-        // Use the program at the top of the stack as the emitter. If for
-        // some reason the stack is empty (malformed logs), fall back to
-        // the dispatch entry's programId (matches the discriminator's
-        // declared owner).
-        const programId = stack.length > 0 ? stack[stack.length - 1] : entry.programId;
-        const data = entry.decode(blob);
-        out.push({ programId, name: entry.name, data });
-    }
-    if (filter !== undefined) {
-        return out.filter((e) => e.name === filter);
-    }
-    return out;
-}
 /**
- * Fetch a transaction by signature and return its decoded events.
+ * AR.IO Solana event decoders — STUB.
  *
- * Uses `getTransaction` with `maxSupportedTransactionVersion: 0` and
- * `commitment: 'confirmed'` by default. Returns `[]` if the tx is
- * still pending, missing, or had no logs (rare — Anchor programs
- * always log).
+ * The local event codegen pipeline has been removed. Event decoders will be
+ * restored once `@ar.io/solana-contracts` publishes them. Until then, the
+ * parse functions return empty arrays and the union types are `never`.
  */
-export async function parseTransactionEvents(rpc, signature, opts = {}) {
-    const commitment = opts.commitment ?? 'confirmed';
-    const tx = await rpc
-        .getTransaction(signature, {
-        commitment,
-        maxSupportedTransactionVersion: 0,
-        encoding: 'json',
-    })
-        .send();
-    const logs = tx?.meta?.logMessages ?? [];
-    return parseEventsFromLogs(logs);
-}
-// ---------------------------------------------------------------------------
-// Type guards — sugar so `if (isNamePurchasedEvent(ev)) { ev.data.cost ... }`
-// narrows correctly without writing `ev.name === 'NamePurchasedEvent'`.
-// One per event would be 73 lines of boilerplate; we expose a
-// generic `isEvent<N>(ev, name)` instead. Consumers can wrap if they
-// want a specific named guard.
-// ---------------------------------------------------------------------------
-/**
- * Generic type-narrowing predicate for any event name.
- *
- * ```ts
- * for (const ev of events) {
- *   if (isEvent(ev, 'NamePurchasedEvent')) {
- *     // ev.data is typed as NamePurchasedEvent here
- *     console.log(ev.data.buyer, ev.data.cost);
- *   }
- * }
- * ```
- */
-export function isEvent(ev, name) {
-    return ev.name === name;
-}
-// ---------------------------------------------------------------------------
-// Internal helpers (not exported)
-// ---------------------------------------------------------------------------
-function bytesToHex(bytes) {
-    let s = '';
-    for (const b of bytes)
-        s += b.toString(16).padStart(2, '0');
-    return s;
+export function parseEventsFromLogs(_logs) {
+    return [];
 }
-function screamingSnakeToPascal(s) {
-    // TRANSFER_EVENT → TransferEvent
-    return s
-        .split('_')
-        .filter((p) => p.length > 0)
-        .map((p) => p.charAt(0).toUpperCase() + p.slice(1).toLowerCase())
-        .join('');
+export async function parseTransactionEvents(_rpc, _signature, _opts) {
+    return [];
 }
-function decodeBase64(b64) {
-    // @solana/kit's getBase64Encoder is a codec helper for the *string*
-    // representation; for raw decoding we use Buffer when running on Node
-    // (the SDK targets Node 18+) and atob otherwise. Wrap it so callers
-    // get a predictable Uint8Array regardless of runtime.
-    try {
-        if (typeof Buffer !== 'undefined') {
-            return new Uint8Array(Buffer.from(b64, 'base64'));
-        }
-        // Browser path — atob returns a binary string we then unpack.
-        const bin = atob(b64);
-        const out = new Uint8Array(bin.length);
-        for (let i = 0; i < bin.length; i++)
-            out[i] = bin.charCodeAt(i);
-        return out;
-    }
-    catch {
-        void getBase64Encoder; // keep the import alive for future kit-native variants
-        return null;
-    }
+export function isEvent(ev, _name) {
+    return ev.name === _name;
 }

package/lib/esm/solana/funding-plan.js

@@ -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.
+ */
 /**
  * Multi-source, multi-gateway funding plan builder + executor for the AR.IO
  * Solana SDK.
@@ -552,6 +567,7 @@ async function fetchUserWithdrawals(rpc, owner, garProgram) {
     //   106..107 is_protected: bool   — BD-102: protected min-stake exit
     //                                    vaults are skipped (cannot fund-from)
     //   107..108 bump: u8
+    //   108..111 version: SchemaVersion { major, minor, patch }
     try {
         const result = await rpc
             .getProgramAccounts(garProgram, {
@@ -559,7 +575,7 @@ async function fetchUserWithdrawals(rpc, owner, garProgram) {
                 {
                     memcmp: { offset: 8n, bytes: owner, encoding: 'base58' },
                 },
-                { dataSize: BigInt(8 + 32 + 8 + 32 + 8 + 8 + 8 + 1 + 1 + 1 + 1) },
+                { dataSize: BigInt(8 + 32 + 8 + 32 + 8 + 8 + 8 + 1 + 1 + 1 + 1 + 3) },
             ],
             encoding: 'base64',
         })
@@ -607,6 +623,7 @@ async function fetchUserDelegations(rpc, owner, garProgram) {
     //   80..88   start_timestamp: i64
     //   88..104  reward_debt: u128
     //   104..105 bump: u8
+    //   105..108 version: SchemaVersion { major, minor, patch }
     try {
         const result = await rpc
             .getProgramAccounts(garProgram, {
@@ -614,7 +631,7 @@ async function fetchUserDelegations(rpc, owner, garProgram) {
                 {
                     memcmp: { offset: 40n, bytes: owner, encoding: 'base58' },
                 },
-                { dataSize: BigInt(8 + 32 + 32 + 8 + 8 + 16 + 1) },
+                { dataSize: BigInt(8 + 32 + 32 + 8 + 8 + 16 + 1 + 3) },
             ],
             encoding: 'base64',
         })