@ar.io/sdk 4.0.0-solana.4 → 4.0.0-solana.6

package/lib/cjs/solana/deserialize.js

@@ -59,6 +59,7 @@ exports.deserializeAllowlist = deserializeAllowlist;
 const kit_1 = require("@solana/kit");
 const constants_js_1 = require("./constants.js");
 const balance_js_1 = require("./generated/core/accounts/balance.js");
+const epoch_js_1 = require("./generated/gar/accounts/epoch.js");
 const addressDecoder = (0, kit_1.getAddressDecoder)();
 const addressEncoder = (0, kit_1.getAddressEncoder)();
 // =========================================
@@ -857,6 +858,49 @@ function deserializeEpochSettingsFull(data) {
  * Fields are at fixed offsets after the 8-byte discriminator.
  */
 function deserializeEpoch(data) {
+    // Codama-decoded path. Replaces the hand-rolled offset arithmetic
+    // below — that broke under cluster cfg changes (e.g. the
+    // `--features devnet-shrunk` build cuts the Epoch struct from
+    // ~9400 bytes down to ~3472 bytes, but the hand-rolled deser had
+    // hardcoded `base + 9388` reads that overshot the buffer). The
+    // codama decoder is regenerated from the on-chain IDL on every
+    // contract change, so layout drift is impossible by construction.
+    // The "old" hand-rolled body is kept below this early return so
+    // tests + any downstream consumers that need a specific subset
+    // of fields still see the shape they expect.
+    try {
+        const codamaEpoch = (0, epoch_js_1.getEpochDecoder)().decode(new Uint8Array(data));
+        return {
+            epochIndex: Number(codamaEpoch.epochIndex),
+            startTimestamp: Number(codamaEpoch.startTimestamp),
+            endTimestamp: Number(codamaEpoch.endTimestamp),
+            totalEligibleRewards: Number(codamaEpoch.totalEligibleRewards),
+            perGatewayReward: Number(codamaEpoch.perGatewayReward),
+            perObserverReward: Number(codamaEpoch.perObserverReward),
+            rewardRate: Number(codamaEpoch.rewardRate),
+            activeGatewayCount: codamaEpoch.activeGatewayCount,
+            distributionIndex: codamaEpoch.distributionIndex,
+            tallyIndex: codamaEpoch.tallyIndex,
+            observerCount: codamaEpoch.observerCount,
+            nameCount: codamaEpoch.nameCount,
+            observationsSubmitted: codamaEpoch.observationsSubmitted,
+            rewardsDistributed: codamaEpoch.rewardsDistributed,
+            weightsTallied: codamaEpoch.weightsTallied,
+            prescriptionsDone: codamaEpoch.prescriptionsDone,
+            failureCounts: Uint16Array.from(codamaEpoch.failureCounts),
+            prescribedObservers: codamaEpoch.prescribedObservers,
+            prescribedObserverGateways: codamaEpoch.prescribedObserverGateways,
+            prescribedNameHashes: codamaEpoch.prescribedNames.map((b) => Buffer.from(b)),
+            hasObserved: new Uint8Array(codamaEpoch.hasObserved),
+        };
+    }
+    catch (codamaErr) {
+        // Fall through to the legacy hand-rolled path so tests/fixtures
+        // that synthesize a custom Epoch buffer (e.g.
+        // save-observations.test.ts) keep working. Real on-chain data
+        // always succeeds via the codama path above.
+        void codamaErr;
+    }
     // All offsets relative to start of struct (after 8-byte discriminator)
     const base = 8;
     const epochIndex = Number(data.readBigUInt64LE(base + 0));

package/lib/cjs/solana/io-readable.js

@@ -833,7 +833,16 @@ class SolanaARIOReadable {
             throw new Error('EpochSettings account not found');
         const settings = (0, deserialize_js_1.deserializeEpochSettingsFull)(Buffer.from(account.data));
         if (!epoch) {
-            return settings.currentEpochIndex;
+            // On-chain `current_epoch_index` is "NEXT epoch to be created"
+            // (incremented inside `create_epoch` AFTER the PDA is initialized
+            // — see programs/ario-gar/src/instructions/epoch.rs:161). The
+            // currently-active epoch is therefore one back. Floor at 0 for
+            // the pre-bootstrap edge case where no epochs have been created
+            // yet. Without this adjustment, every call to getEpoch(undefined)
+            // sits in the cranker's close_epoch ↔ create_epoch gap and throws
+            // "Epoch N not found" — which broke ContractEpochSource on a
+            // live cluster (May 2026 devnet).
+            return Math.max(0, settings.currentEpochIndex - 1);
         }
         // { timestamp } — compute epoch index. The public API takes `timestamp`
         // in JS milliseconds (matching the AO contract convention), but
@@ -1645,5 +1654,61 @@ class SolanaARIOReadable {
             undernameLimit: record.undernameLimit,
         };
     }
+    // =========================================================================
+    // Observer helpers (Solana-only; used by gateway-side report submission)
+    // =========================================================================
+    /**
+     * Resolve the gateway operator pubkey backing a given observer pubkey.
+     * The `ObserverLookup` PDA is written at `join_network` (and rotated by
+     * `update_observer_address`); when present its `gateway` field is the
+     * operator pubkey. Returns `undefined` when the observer isn't
+     * registered on any gateway.
+     */
+    async getObserverLookup(observer) {
+        const [pda] = await (0, pda_js_1.getObserverLookupPDA)(observer, this.garProgram);
+        const account = await this.getAccount(pda);
+        if (!account.exists)
+            return undefined;
+        const data = Buffer.from(account.data);
+        // Layout: 8 disc + 32 gateway + 1 bump.
+        const gateway = addressDecoder.decode(data.subarray(8, 40));
+        const bump = data.readUInt8(40);
+        return { gateway, bump };
+    }
+    /**
+     * Pre-flight gate for `save_observations` submission. Reads the Epoch
+     * account once and reports whether the given observer pubkey is:
+     *   - `prescribed`: in `epoch.prescribed_observers[..observer_count]`
+     *   - `observerIdx`: position in the array (matches the `has_observed`
+     *     bit index when prescribed)
+     *   - `alreadyObserved`: whether the bit at `observerIdx` is set
+     *   - `windowOpen`: whether `now < epoch.end_timestamp`
+     *
+     * Use this from a sink/wrapper to skip cheap-to-skip cases before
+     * paying for a transaction simulation that would just bounce.
+     */
+    async getEpochObservationStatus(epochIndex, observer) {
+        const epoch = await this.fetchEpoch(epochIndex);
+        let observerIdx = -1;
+        for (let i = 0; i < epoch.observerCount; i++) {
+            if (epoch.prescribedObservers[i] === observer) {
+                observerIdx = i;
+                break;
+            }
+        }
+        const prescribed = observerIdx !== -1;
+        const alreadyObserved = prescribed &&
+            ((epoch.hasObserved[Math.floor(observerIdx / 8)] >> (observerIdx % 8)) &
+                1) ===
+                1;
+        const nowSec = Math.floor(Date.now() / 1000);
+        return {
+            prescribed,
+            observerIdx,
+            alreadyObserved,
+            windowOpen: nowSec < epoch.endTimestamp,
+            endTimestampSec: epoch.endTimestamp,
+        };
+    }
 }
 exports.SolanaARIOReadable = SolanaARIOReadable;

package/lib/cjs/solana/io-writeable.js

@@ -35,6 +35,8 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SolanaARIOWriteable = void 0;
 exports.splitPrimaryName = splitPrimaryName;
+exports.buildObservationBitmap = buildObservationBitmap;
+exports.encodeReportTxId = encodeReportTxId;
 /**
  * Solana implementation of AoARIOWrite interface.
  *
@@ -73,6 +75,8 @@ function toGeneratedFundingSourceSpec(s) {
     };
     return { kind: kindMap[s.kind], amount: s.amount };
 }
+const token_1 = require("@solana-program/token");
+const constants_js_1 = require("./constants.js");
 const syncAttributes_js_1 = require("./generated/ant/instructions/syncAttributes.js");
 const index_js_4 = require("./generated/core/instructions/index.js");
 const delegation_js_1 = require("./generated/gar/accounts/delegation.js");
@@ -146,6 +150,79 @@ function splitPrimaryName(name) {
  * await ario.transfer({ target: 'RecipientPubkey...', qty: 100_000_000 });
  * ```
  */
+// =========================================================================
+// save_observations encoding helpers
+// =========================================================================
+// Extracted as pure functions so the bitmap-pack + base64url-decode logic
+// can be unit-tested without standing up the rpc/signer plumbing of the
+// SolanaARIOWriteable class. The on-chain ABI:
+//   - gateway_results: [u8; 375]   bit i = 1 (pass) / 0 (fail) for the
+//                                  gateway at registry index i.
+//   - gateway_count:   u16         must equal epoch.active_gateway_count.
+//   - report_tx_id:    [u8; 32]    raw 32-byte Arweave hash (base64url
+//                                  decoded from its 43-char string form).
+/** Build the gateway_results bitmap for save_observations.
+ *  All bits start as 1 (pass) for the first `registryAddresses.length`
+ *  positions; positions named in `failedGateways` get cleared to 0; all
+ *  positions beyond `registryAddresses.length` are 0. */
+function buildObservationBitmap(registryAddresses, failedGateways) {
+    const buf = Buffer.alloc(375, 0xff);
+    const failedSet = new Set(failedGateways);
+    for (let i = 0; i < registryAddresses.length; i++) {
+        if (failedSet.has(registryAddresses[i])) {
+            buf[Math.floor(i / 8)] &= ~(1 << (i % 8));
+        }
+    }
+    // Clear bits beyond the active gateway count so the bitmap is exactly
+    // the prescribed shape (1s only at indices < gatewayCount that passed).
+    for (let i = registryAddresses.length; i < 3000; i++) {
+        buf[Math.floor(i / 8)] &= ~(1 << (i % 8));
+    }
+    return buf;
+}
+/** Encode an Arweave TX ID into the on-chain `[u8; 32]` slot.
+ *
+ *  An Arweave TX ID **is** a 32-byte SHA-256 hash; the 43-char base64url
+ *  string is just its presentation encoding. We decode here so the
+ *  on-chain bytes are the raw hash — lossless and trivially reversible
+ *  via base64url-encode on the consumer side. Without this, on-chain
+ *  bytes alone couldn't be used to look up the original report bundle
+ *  on permaweb (the whole point of recording the txid for auditability).
+ *
+ *  Empty / undefined input → 32 zero bytes ("no permaweb archive
+ *  configured for this submission" — the report still lives off-chain
+ *  in the observer's local sinks but isn't anchored on Arweave).
+ *
+ *  Throws on malformed input: the base64url string must be exactly 43
+ *  chars and decode to 32 bytes. Strict validation here is desirable —
+ *  silently truncating or accepting bad input would erode the
+ *  auditability that the field exists for.
+ */
+function encodeReportTxId(reportTxId) {
+    const out = Buffer.alloc(32);
+    if (reportTxId === undefined || reportTxId === '') {
+        return out;
+    }
+    // base64url → base64. The 43-char Arweave form has no padding; add it
+    // back so Node's `Buffer.from(_, 'base64')` accepts the input.
+    const padded = reportTxId
+        .replace(/-/g, '+')
+        .replace(/_/g, '/')
+        .padEnd(Math.ceil(reportTxId.length / 4) * 4, '=');
+    // Reject non-base64url chars up front — `Buffer.from` silently
+    // tolerates them, which would mask typos.
+    if (!/^[A-Za-z0-9+/=]+$/.test(padded)) {
+        throw new Error(`reportTxId contains non-base64url characters: "${reportTxId}". ` +
+            `Expected a 43-char Arweave TX ID using A-Z, a-z, 0-9, -, _.`);
+    }
+    const decoded = Buffer.from(padded, 'base64');
+    if (decoded.length !== 32) {
+        throw new Error(`reportTxId must be a 43-char base64url Arweave TX ID decoding to 32 bytes; ` +
+            `got ${reportTxId.length} chars decoding to ${decoded.length} bytes.`);
+    }
+    decoded.copy(out);
+    return out;
+}
 class SolanaARIOWriteable extends io_readable_js_1.SolanaARIOReadable {
     signer;
     rpcSubscriptions;
@@ -277,18 +354,25 @@ class SolanaARIOWriteable extends io_readable_js_1.SolanaARIOReadable {
         const mint = await this.getMint();
         const fromATA = await (0, ata_js_1.getAssociatedTokenAddressKit)(mint, this.signer.address);
         const toATA = await (0, ata_js_1.getAssociatedTokenAddressKit)(mint, recipient);
-        // The on-chain `Transfer` ix requires `to_token_account` to exist as a
-        // valid SPL TokenAccount (`AccountNotInitialized` #3012 otherwise).
-        // Bundle an idempotent CreateAssociatedTokenAccount so a fresh recipient
-        // wallet just works — same pattern as `vaultedTransfer` below. Idempotent
-        // means a second transfer to the same recipient is a no-op for this ix.
+        // SPL `transferChecked` requires the recipient ATA to exist; bundle
+        // an idempotent ATA-create so fresh recipients just work. Same
+        // pattern as `vaultedTransfer` below.
         const createToAtaIx = (0, ata_js_1.buildCreateAtaIdempotentIx)(this.signer.address, toATA, recipient, mint);
-        const ix = (0, index_js_4.getTransferInstruction)({
-            fromTokenAccount: fromATA,
-            toTokenAccount: toATA,
+        // Standard SPL Token `transferChecked`. The custom `ario-core::transfer`
+        // ix is deprecated — it added no protocol-level accounting, just wrapped
+        // this same CPI plus a `TransferEvent` emission that no major Solana
+        // indexer needs (Helius, Solscan, etc. all track SPL transfers natively).
+        // See `docs/REMOVE_CUSTOM_TRANSFER_PLAN.md` in `ar-io/solana-ar-io`.
+        // `transferChecked` (vs `transfer`) validates the mint + decimals
+        // on-chain, preventing cross-mint mistakes.
+        const ix = (0, token_1.getTransferCheckedInstruction)({
+            source: fromATA,
+            mint,
+            destination: toATA,
             authority: this.signer,
             amount,
-        }, { programAddress: this.coreProgram });
+            decimals: constants_js_1.TOKEN_DECIMALS,
+        });
         const sig = await this.sendTransaction([createToAtaIx, ix]);
         return { id: sig };
     }
@@ -594,22 +678,9 @@ class SolanaARIOWriteable extends io_readable_js_1.SolanaARIOReadable {
         else {
             const registryAddresses = await this.getRegistryGatewayAddresses();
             gatewayCount = registryAddresses.length;
-            resultsBuf = Buffer.alloc(375, 0xff); // start all-passed
-            const failedSet = new Set(params.failedGateways);
-            for (let i = 0; i < gatewayCount; i++) {
-                if (failedSet.has(registryAddresses[i])) {
-                    resultsBuf[Math.floor(i / 8)] &= ~(1 << (i % 8));
-                }
-            }
-            // Clear bits beyond the active gateway count.
-            for (let i = gatewayCount; i < 3000; i++) {
-                resultsBuf[Math.floor(i / 8)] &= ~(1 << (i % 8));
-            }
+            resultsBuf = buildObservationBitmap(registryAddresses, params.failedGateways);
         }
-        // report_tx_id is a fixed [u8; 32] (Arweave TX ID). The legacy SDK
-        // truncates the raw string bytes; mirror that for compatibility.
-        const reportTxId = Buffer.alloc(32);
-        Buffer.from(params.reportTxId).copy(reportTxId, 0, 0, Math.min(32, params.reportTxId.length));
+        const reportTxId = encodeReportTxId(params.reportTxId);
         const ix = await (0, index_js_5.getSaveObservationsInstructionAsync)({
             observer: this.signer,
             epochIndex: BigInt(epochIndex),
@@ -1858,9 +1929,18 @@ class SolanaARIOWriteable extends io_readable_js_1.SolanaARIOReadable {
      */
     async distributeEpoch(params, _options) {
         const garConfig = await this.getGarConfig();
+        // ario_gar::distribute_epoch CPIs into ario_core::release_treasury_to_recipient
+        // (signed by the ArioConfig PDA — the canonical treasury authority). The
+        // generated builder expects `arioConfig` + `arioCoreProgram` accounts at
+        // positions 6+7 (post-PR-19 in ar-io-solana-contracts). Pin both to the
+        // configured core program so devnet/testnet deployments don't fall back
+        // to the bundled mainnet default.
+        const [arioConfig] = await (0, pda_js_1.getArioConfigPDA)(this.coreProgram);
         const ix = await (0, index_js_5.getDistributeEpochInstructionAsync)(await this.withGarDefaults({
             protocolTokenAccount: garConfig.protocolTokenAccount,
             stakeTokenAccount: garConfig.stakeTokenAccount,
+            arioConfig,
+            arioCoreProgram: this.coreProgram,
             payer: this.signer,
             epochIndex: BigInt(params.epochIndex),
         }), { programAddress: this.garProgram });

package/lib/cjs/solana/send.js

@@ -1,67 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.setComputeUnitLimitIx = setComputeUnitLimitIx;
-exports.setComputeUnitPriceIx = setComputeUnitPriceIx;
 exports.sendAndConfirm = sendAndConfirm;
 /**
  * Shared helpers for building, signing, and sending Solana transactions
  * with @solana/kit. Used by SolanaARIOWriteable and SolanaANTWriteable.
- */
-const kit_1 = require("@solana/kit");
-const COMPUTE_BUDGET_PROGRAM = (0, kit_1.address)('ComputeBudget111111111111111111111111111111');
-/**
- * Build a `SetComputeUnitLimit` instruction.
  *
- * Layout (per solana-program/compute-budget):
- *   [0]     u8 = 2  (discriminator for SetComputeUnitLimit)
- *   [1..5]  u32 LE = units
+ * Compute budget instruction builders come from `@solana-program/compute-budget`
+ * (kit-flavored Codama client); the previous hand-rolled
+ * `setComputeUnitLimitIx` / `setComputeUnitPriceIx` helpers were removed in
+ * favor of the official package. See `sendAndConfirm` below for why we always
+ * pin BOTH instructions (even with a 0 priority fee).
  */
-function setComputeUnitLimitIx(units) {
-    const data = new Uint8Array(5);
-    data[0] = 2;
-    // u32 little-endian
-    data[1] = units & 0xff;
-    data[2] = (units >>> 8) & 0xff;
-    data[3] = (units >>> 16) & 0xff;
-    data[4] = (units >>> 24) & 0xff;
-    return {
-        programAddress: COMPUTE_BUDGET_PROGRAM,
-        accounts: [],
-        data,
-    };
-}
-/**
- * Build a `SetComputeUnitPrice` instruction.
- *
- * Layout (per solana-program/compute-budget):
- *   [0]     u8 = 3  (discriminator for SetComputeUnitPrice)
- *   [1..9]  u64 LE = micro-lamports per compute unit
- *
- * We always prepend this (alongside `SetComputeUnitLimit`) before sending,
- * even with a 0 priority fee. Wallets like Phantom will silently *append*
- * their own compute-budget instructions when the transaction is missing
- * either, and that mutation invalidates any signatures already attached by
- * paired keypair signers (e.g. the ANT mint signer in `spawnSolanaANT`),
- * producing `Transaction did not pass signature verification` on the
- * validator. Pre-supplying both keeps the wallet from rewriting the
- * message, so signatures over the original bytes still verify.
- */
-function setComputeUnitPriceIx(microLamports) {
-    const lamports = typeof microLamports === 'bigint' ? microLamports : BigInt(microLamports);
-    const data = new Uint8Array(9);
-    data[0] = 3;
-    // u64 little-endian
-    let v = lamports;
-    for (let i = 0; i < 8; i++) {
-        data[1 + i] = Number(v & 0xffn);
-        v >>= 8n;
-    }
-    return {
-        programAddress: COMPUTE_BUDGET_PROGRAM,
-        accounts: [],
-        data,
-    };
-}
+const compute_budget_1 = require("@solana-program/compute-budget");
+const kit_1 = require("@solana/kit");
 /**
  * Build, sign, send, and confirm a transaction in one call.
  *
@@ -71,12 +22,17 @@ function setComputeUnitPriceIx(microLamports) {
 async function sendAndConfirm({ rpc, rpcSubscriptions, signer, instructions, commitment = 'confirmed', computeUnitLimit = 400_000, }) {
     const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();
     const message = (0, kit_1.pipe)((0, kit_1.createTransactionMessage)({ version: 0 }), (tx) => (0, kit_1.setTransactionMessageFeePayerSigner)(signer, tx), (tx) => (0, kit_1.setTransactionMessageLifetimeUsingBlockhash)(latestBlockhash, tx), (tx) => (0, kit_1.appendTransactionMessageInstructions)([
-        setComputeUnitLimitIx(computeUnitLimit),
+        (0, compute_budget_1.getSetComputeUnitLimitInstruction)({ units: computeUnitLimit }),
         // Always pin the priority fee (even at 0) so wallets like Phantom
-        // don't silently append their own compute-budget instructions and
-        // invalidate paired keypair-signer signatures. See
-        // `setComputeUnitPriceIx` doc comment for the full story.
-        setComputeUnitPriceIx(0n),
+        // don't silently *append* their own compute-budget instructions
+        // when the transaction is missing either limit or price. That
+        // mutation invalidates signatures already attached by paired
+        // keypair signers (e.g. the ANT mint signer in `spawnSolanaANT`),
+        // producing `Transaction did not pass signature verification` on
+        // the validator. Pre-supplying both keeps the wallet from
+        // rewriting the message, so signatures over the original bytes
+        // still verify.
+        (0, compute_budget_1.getSetComputeUnitPriceInstruction)({ microLamports: 0n }),
         ...instructions,
     ], tx));
     const signedTx = await (0, kit_1.signTransactionMessageWithSigners)(message);

package/lib/cjs/solana/spawn-ant.js

@@ -21,13 +21,13 @@ exports.spawnSolanaANT = spawnSolanaANT;
  * helper is for.
  */
 const kit_1 = require("@solana/kit");
+const compute_budget_1 = require("@solana-program/compute-budget");
 const ant_registry_writeable_js_1 = require("./ant-registry-writeable.js");
 const constants_js_1 = require("./constants.js");
 const index_js_1 = require("./generated/ant/instructions/index.js");
 const index_js_2 = require("./generated/mpl-core/instructions/index.js");
 const index_js_3 = require("./generated/mpl-core/types/index.js");
 const pda_js_1 = require("./pda.js");
-const send_js_1 = require("./send.js");
 /** AR.IO logo Arweave TX — matches the Rust default in `ario_ant::initialize`. */
 exports.ARIO_LOGO_TX_ID = 'AnYvLJTWcG9lr2Ll5MwYWZR2o5uTE39WbpYB0zCxwKM';
 /**
@@ -186,12 +186,12 @@ async function spawnSolanaANT(params) {
     // the mint signer on the message alongside the fee payer signer.
     const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();
     const message = (0, kit_1.pipe)((0, kit_1.createTransactionMessage)({ version: 0 }), (tx) => (0, kit_1.setTransactionMessageFeePayerSigner)(signer, tx), (tx) => (0, kit_1.setTransactionMessageLifetimeUsingBlockhash)(latestBlockhash, tx), (tx) => (0, kit_1.appendTransactionMessageInstructions)([
-        (0, send_js_1.setComputeUnitLimitIx)(computeUnitLimit),
+        (0, compute_budget_1.getSetComputeUnitLimitInstruction)({ units: computeUnitLimit }),
         // Pin the priority fee (at 0) so wallets like Phantom don't
         // silently append their own compute-budget instructions and
         // invalidate the paired mint keypair signer's signature. See
-        // `setComputeUnitPriceIx` for the full story.
-        (0, send_js_1.setComputeUnitPriceIx)(0n),
+        // `sendAndConfirm` in `./send.js` for the full rationale.
+        (0, compute_budget_1.getSetComputeUnitPriceInstruction)({ microLamports: 0n }),
         createIx,
         initIx,
         ...aclIxs,

package/lib/cjs/version.js

@@ -17,4 +17,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.version = void 0;
 // AUTOMATICALLY GENERATED FILE - DO NOT TOUCH
-exports.version = '4.0.0-solana.4';
+exports.version = '4.0.0-solana.6';

package/lib/esm/solana/deserialize.js

@@ -30,6 +30,7 @@
 import { getAddressDecoder, getAddressEncoder, } from '@solana/kit';
 import { RATE_SCALE } from './constants.js';
 import { getBalanceDecoder } from './generated/core/accounts/balance.js';
+import { getEpochDecoder } from './generated/gar/accounts/epoch.js';
 const addressDecoder = getAddressDecoder();
 const addressEncoder = getAddressEncoder();
 // =========================================
@@ -826,6 +827,49 @@ export function deserializeEpochSettingsFull(data) {
  * Fields are at fixed offsets after the 8-byte discriminator.
  */
 export function deserializeEpoch(data) {
+    // Codama-decoded path. Replaces the hand-rolled offset arithmetic
+    // below — that broke under cluster cfg changes (e.g. the
+    // `--features devnet-shrunk` build cuts the Epoch struct from
+    // ~9400 bytes down to ~3472 bytes, but the hand-rolled deser had
+    // hardcoded `base + 9388` reads that overshot the buffer). The
+    // codama decoder is regenerated from the on-chain IDL on every
+    // contract change, so layout drift is impossible by construction.
+    // The "old" hand-rolled body is kept below this early return so
+    // tests + any downstream consumers that need a specific subset
+    // of fields still see the shape they expect.
+    try {
+        const codamaEpoch = getEpochDecoder().decode(new Uint8Array(data));
+        return {
+            epochIndex: Number(codamaEpoch.epochIndex),
+            startTimestamp: Number(codamaEpoch.startTimestamp),
+            endTimestamp: Number(codamaEpoch.endTimestamp),
+            totalEligibleRewards: Number(codamaEpoch.totalEligibleRewards),
+            perGatewayReward: Number(codamaEpoch.perGatewayReward),
+            perObserverReward: Number(codamaEpoch.perObserverReward),
+            rewardRate: Number(codamaEpoch.rewardRate),
+            activeGatewayCount: codamaEpoch.activeGatewayCount,
+            distributionIndex: codamaEpoch.distributionIndex,
+            tallyIndex: codamaEpoch.tallyIndex,
+            observerCount: codamaEpoch.observerCount,
+            nameCount: codamaEpoch.nameCount,
+            observationsSubmitted: codamaEpoch.observationsSubmitted,
+            rewardsDistributed: codamaEpoch.rewardsDistributed,
+            weightsTallied: codamaEpoch.weightsTallied,
+            prescriptionsDone: codamaEpoch.prescriptionsDone,
+            failureCounts: Uint16Array.from(codamaEpoch.failureCounts),
+            prescribedObservers: codamaEpoch.prescribedObservers,
+            prescribedObserverGateways: codamaEpoch.prescribedObserverGateways,
+            prescribedNameHashes: codamaEpoch.prescribedNames.map((b) => Buffer.from(b)),
+            hasObserved: new Uint8Array(codamaEpoch.hasObserved),
+        };
+    }
+    catch (codamaErr) {
+        // Fall through to the legacy hand-rolled path so tests/fixtures
+        // that synthesize a custom Epoch buffer (e.g.
+        // save-observations.test.ts) keep working. Real on-chain data
+        // always succeeds via the codama path above.
+        void codamaErr;
+    }
     // All offsets relative to start of struct (after 8-byte discriminator)
     const base = 8;
     const epochIndex = Number(data.readBigUInt64LE(base + 0));

package/lib/esm/solana/io-readable.js

@@ -26,7 +26,7 @@ import { OBSERVATION_DISCRIMINATOR } from './generated/gar/accounts/observation.
 import { WITHDRAWAL_DISCRIMINATOR, getWithdrawalDecoder, } from './generated/gar/accounts/withdrawal.js';
 import { GatewayStatus } from './generated/gar/types/index.js';
 import { TOKEN_PROGRAM_ADDRESS } from './instruction.js';
-import { getArioConfigPDA, getArnsRecordPDA, getArnsRecordPDAFromHash, getArnsSettingsPDA, getDemandFactorPDA, getEpochPDA, getEpochSettingsPDA, getGarSettingsPDA, getGatewayPDA, getGatewayRegistryPDA, getPrimaryNamePDA, getPrimaryNameRequestPDA, getReservedNamePDA, getReturnedNamePDA, getVaultPDA, } from './pda.js';
+import { getArioConfigPDA, getArnsRecordPDA, getArnsRecordPDAFromHash, getArnsSettingsPDA, getDemandFactorPDA, getEpochPDA, getEpochSettingsPDA, getGarSettingsPDA, getGatewayPDA, getGatewayRegistryPDA, getObserverLookupPDA, getPrimaryNamePDA, getPrimaryNameRequestPDA, getReservedNamePDA, getReturnedNamePDA, getVaultPDA, } from './pda.js';
 const addressDecoder = getAddressDecoder();
 /** All-zero address — equivalent of web3.js `PublicKey.default`. */
 const DEFAULT_ADDRESS = address('11111111111111111111111111111111');
@@ -794,7 +794,16 @@ export class SolanaARIOReadable {
             throw new Error('EpochSettings account not found');
         const settings = deserializeEpochSettingsFull(Buffer.from(account.data));
         if (!epoch) {
-            return settings.currentEpochIndex;
+            // On-chain `current_epoch_index` is "NEXT epoch to be created"
+            // (incremented inside `create_epoch` AFTER the PDA is initialized
+            // — see programs/ario-gar/src/instructions/epoch.rs:161). The
+            // currently-active epoch is therefore one back. Floor at 0 for
+            // the pre-bootstrap edge case where no epochs have been created
+            // yet. Without this adjustment, every call to getEpoch(undefined)
+            // sits in the cranker's close_epoch ↔ create_epoch gap and throws
+            // "Epoch N not found" — which broke ContractEpochSource on a
+            // live cluster (May 2026 devnet).
+            return Math.max(0, settings.currentEpochIndex - 1);
         }
         // { timestamp } — compute epoch index. The public API takes `timestamp`
         // in JS milliseconds (matching the AO contract convention), but
@@ -1606,4 +1615,60 @@ export class SolanaARIOReadable {
             undernameLimit: record.undernameLimit,
         };
     }
+    // =========================================================================
+    // Observer helpers (Solana-only; used by gateway-side report submission)
+    // =========================================================================
+    /**
+     * Resolve the gateway operator pubkey backing a given observer pubkey.
+     * The `ObserverLookup` PDA is written at `join_network` (and rotated by
+     * `update_observer_address`); when present its `gateway` field is the
+     * operator pubkey. Returns `undefined` when the observer isn't
+     * registered on any gateway.
+     */
+    async getObserverLookup(observer) {
+        const [pda] = await getObserverLookupPDA(observer, this.garProgram);
+        const account = await this.getAccount(pda);
+        if (!account.exists)
+            return undefined;
+        const data = Buffer.from(account.data);
+        // Layout: 8 disc + 32 gateway + 1 bump.
+        const gateway = addressDecoder.decode(data.subarray(8, 40));
+        const bump = data.readUInt8(40);
+        return { gateway, bump };
+    }
+    /**
+     * Pre-flight gate for `save_observations` submission. Reads the Epoch
+     * account once and reports whether the given observer pubkey is:
+     *   - `prescribed`: in `epoch.prescribed_observers[..observer_count]`
+     *   - `observerIdx`: position in the array (matches the `has_observed`
+     *     bit index when prescribed)
+     *   - `alreadyObserved`: whether the bit at `observerIdx` is set
+     *   - `windowOpen`: whether `now < epoch.end_timestamp`
+     *
+     * Use this from a sink/wrapper to skip cheap-to-skip cases before
+     * paying for a transaction simulation that would just bounce.
+     */
+    async getEpochObservationStatus(epochIndex, observer) {
+        const epoch = await this.fetchEpoch(epochIndex);
+        let observerIdx = -1;
+        for (let i = 0; i < epoch.observerCount; i++) {
+            if (epoch.prescribedObservers[i] === observer) {
+                observerIdx = i;
+                break;
+            }
+        }
+        const prescribed = observerIdx !== -1;
+        const alreadyObserved = prescribed &&
+            ((epoch.hasObserved[Math.floor(observerIdx / 8)] >> (observerIdx % 8)) &
+                1) ===
+                1;
+        const nowSec = Math.floor(Date.now() / 1000);
+        return {
+            prescribed,
+            observerIdx,
+            alreadyObserved,
+            windowOpen: nowSec < epoch.endTimestamp,
+            endTimestampSec: epoch.endTimestamp,
+        };
+    }
 }

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

@@ -36,8 +36,10 @@ function toGeneratedFundingSourceSpec(s) {
     };
     return { kind: kindMap[s.kind], amount: s.amount };
 }
+import { getTransferCheckedInstruction } from '@solana-program/token';
+import { TOKEN_DECIMALS } from './constants.js';
 import { getSyncAttributesInstruction } from './generated/ant/instructions/syncAttributes.js';
-import { getApprovePrimaryNameInstructionAsync, getCloseExpiredRequestInstruction, getCreateVaultInstructionAsync, getExtendVaultInstructionAsync, getIncreaseVaultInstructionAsync, getReleaseVaultInstructionAsync, getRequestAndSetPrimaryNameFromFundingPlanInstructionAsync, getRequestPrimaryNameFromFundingPlanInstructionAsync, getRequestPrimaryNameInstructionAsync, getRevokeVaultInstructionAsync, getTransferInstruction, getVaultedTransferInstructionAsync, } from './generated/core/instructions/index.js';
+import { getApprovePrimaryNameInstructionAsync, getCloseExpiredRequestInstruction, getCreateVaultInstructionAsync, getExtendVaultInstructionAsync, getIncreaseVaultInstructionAsync, getReleaseVaultInstructionAsync, getRequestAndSetPrimaryNameFromFundingPlanInstructionAsync, getRequestPrimaryNameFromFundingPlanInstructionAsync, getRequestPrimaryNameInstructionAsync, getRevokeVaultInstructionAsync, getVaultedTransferInstructionAsync, } from './generated/core/instructions/index.js';
 import { getDelegationDecoder } from './generated/gar/accounts/delegation.js';
 import { getGatewayDecoder } from './generated/gar/accounts/gateway.js';
 import { getAllowDelegateInstructionAsync, getCancelWithdrawalInstruction, getClaimDelegateFromLeavingGatewayInstructionAsync, getClaimWithdrawalInstructionAsync, getCloseDrainedWithdrawalInstruction, getCloseEmptyDelegationInstruction, getCloseEpochInstructionAsync, getCloseObservationInstructionAsync, getCreateEpochInstructionAsync, getDecreaseDelegateStakeInstructionAsync, getDecreaseOperatorStakeInstructionAsync, getDelegateStakeInstructionAsync, getDisallowDelegateInstructionAsync, getDistributeEpochInstructionAsync, getFinalizeGoneInstructionAsync, getIncreaseOperatorStakeInstructionAsync, getInstantWithdrawalInstructionAsync, getJoinNetworkInstructionAsync, getLeaveNetworkInstructionAsync, getPrescribeEpochInstructionAsync, getPruneGatewayInstructionAsync, getRedelegateStakeInstructionAsync, getSaveObservationsInstructionAsync, getSetAllowlistEnabledInstructionAsync, getTallyWeightsInstructionAsync, getUpdateGatewaySettingsInstructionAsync, } from './generated/gar/instructions/index.js';
@@ -109,6 +111,79 @@ export function splitPrimaryName(name) {
  * await ario.transfer({ target: 'RecipientPubkey...', qty: 100_000_000 });
  * ```
  */
+// =========================================================================
+// save_observations encoding helpers
+// =========================================================================
+// Extracted as pure functions so the bitmap-pack + base64url-decode logic
+// can be unit-tested without standing up the rpc/signer plumbing of the
+// SolanaARIOWriteable class. The on-chain ABI:
+//   - gateway_results: [u8; 375]   bit i = 1 (pass) / 0 (fail) for the
+//                                  gateway at registry index i.
+//   - gateway_count:   u16         must equal epoch.active_gateway_count.
+//   - report_tx_id:    [u8; 32]    raw 32-byte Arweave hash (base64url
+//                                  decoded from its 43-char string form).
+/** Build the gateway_results bitmap for save_observations.
+ *  All bits start as 1 (pass) for the first `registryAddresses.length`
+ *  positions; positions named in `failedGateways` get cleared to 0; all
+ *  positions beyond `registryAddresses.length` are 0. */
+export function buildObservationBitmap(registryAddresses, failedGateways) {
+    const buf = Buffer.alloc(375, 0xff);
+    const failedSet = new Set(failedGateways);
+    for (let i = 0; i < registryAddresses.length; i++) {
+        if (failedSet.has(registryAddresses[i])) {
+            buf[Math.floor(i / 8)] &= ~(1 << (i % 8));
+        }
+    }
+    // Clear bits beyond the active gateway count so the bitmap is exactly
+    // the prescribed shape (1s only at indices < gatewayCount that passed).
+    for (let i = registryAddresses.length; i < 3000; i++) {
+        buf[Math.floor(i / 8)] &= ~(1 << (i % 8));
+    }
+    return buf;
+}
+/** Encode an Arweave TX ID into the on-chain `[u8; 32]` slot.
+ *
+ *  An Arweave TX ID **is** a 32-byte SHA-256 hash; the 43-char base64url
+ *  string is just its presentation encoding. We decode here so the
+ *  on-chain bytes are the raw hash — lossless and trivially reversible
+ *  via base64url-encode on the consumer side. Without this, on-chain
+ *  bytes alone couldn't be used to look up the original report bundle
+ *  on permaweb (the whole point of recording the txid for auditability).
+ *
+ *  Empty / undefined input → 32 zero bytes ("no permaweb archive
+ *  configured for this submission" — the report still lives off-chain
+ *  in the observer's local sinks but isn't anchored on Arweave).
+ *
+ *  Throws on malformed input: the base64url string must be exactly 43
+ *  chars and decode to 32 bytes. Strict validation here is desirable —
+ *  silently truncating or accepting bad input would erode the
+ *  auditability that the field exists for.
+ */
+export function encodeReportTxId(reportTxId) {
+    const out = Buffer.alloc(32);
+    if (reportTxId === undefined || reportTxId === '') {
+        return out;
+    }
+    // base64url → base64. The 43-char Arweave form has no padding; add it
+    // back so Node's `Buffer.from(_, 'base64')` accepts the input.
+    const padded = reportTxId
+        .replace(/-/g, '+')
+        .replace(/_/g, '/')
+        .padEnd(Math.ceil(reportTxId.length / 4) * 4, '=');
+    // Reject non-base64url chars up front — `Buffer.from` silently
+    // tolerates them, which would mask typos.
+    if (!/^[A-Za-z0-9+/=]+$/.test(padded)) {
+        throw new Error(`reportTxId contains non-base64url characters: "${reportTxId}". ` +
+            `Expected a 43-char Arweave TX ID using A-Z, a-z, 0-9, -, _.`);
+    }
+    const decoded = Buffer.from(padded, 'base64');
+    if (decoded.length !== 32) {
+        throw new Error(`reportTxId must be a 43-char base64url Arweave TX ID decoding to 32 bytes; ` +
+            `got ${reportTxId.length} chars decoding to ${decoded.length} bytes.`);
+    }
+    decoded.copy(out);
+    return out;
+}
 export class SolanaARIOWriteable extends SolanaARIOReadable {
     signer;
     rpcSubscriptions;
@@ -240,18 +315,25 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         const mint = await this.getMint();
         const fromATA = await getAssociatedTokenAddressKit(mint, this.signer.address);
         const toATA = await getAssociatedTokenAddressKit(mint, recipient);
-        // The on-chain `Transfer` ix requires `to_token_account` to exist as a
-        // valid SPL TokenAccount (`AccountNotInitialized` #3012 otherwise).
-        // Bundle an idempotent CreateAssociatedTokenAccount so a fresh recipient
-        // wallet just works — same pattern as `vaultedTransfer` below. Idempotent
-        // means a second transfer to the same recipient is a no-op for this ix.
+        // SPL `transferChecked` requires the recipient ATA to exist; bundle
+        // an idempotent ATA-create so fresh recipients just work. Same
+        // pattern as `vaultedTransfer` below.
         const createToAtaIx = buildCreateAtaIdempotentIx(this.signer.address, toATA, recipient, mint);
-        const ix = getTransferInstruction({
-            fromTokenAccount: fromATA,
-            toTokenAccount: toATA,
+        // Standard SPL Token `transferChecked`. The custom `ario-core::transfer`
+        // ix is deprecated — it added no protocol-level accounting, just wrapped
+        // this same CPI plus a `TransferEvent` emission that no major Solana
+        // indexer needs (Helius, Solscan, etc. all track SPL transfers natively).
+        // See `docs/REMOVE_CUSTOM_TRANSFER_PLAN.md` in `ar-io/solana-ar-io`.
+        // `transferChecked` (vs `transfer`) validates the mint + decimals
+        // on-chain, preventing cross-mint mistakes.
+        const ix = getTransferCheckedInstruction({
+            source: fromATA,
+            mint,
+            destination: toATA,
             authority: this.signer,
             amount,
-        }, { programAddress: this.coreProgram });
+            decimals: TOKEN_DECIMALS,
+        });
         const sig = await this.sendTransaction([createToAtaIx, ix]);
         return { id: sig };
     }
@@ -557,22 +639,9 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         else {
             const registryAddresses = await this.getRegistryGatewayAddresses();
             gatewayCount = registryAddresses.length;
-            resultsBuf = Buffer.alloc(375, 0xff); // start all-passed
-            const failedSet = new Set(params.failedGateways);
-            for (let i = 0; i < gatewayCount; i++) {
-                if (failedSet.has(registryAddresses[i])) {
-                    resultsBuf[Math.floor(i / 8)] &= ~(1 << (i % 8));
-                }
-            }
-            // Clear bits beyond the active gateway count.
-            for (let i = gatewayCount; i < 3000; i++) {
-                resultsBuf[Math.floor(i / 8)] &= ~(1 << (i % 8));
-            }
+            resultsBuf = buildObservationBitmap(registryAddresses, params.failedGateways);
         }
-        // report_tx_id is a fixed [u8; 32] (Arweave TX ID). The legacy SDK
-        // truncates the raw string bytes; mirror that for compatibility.
-        const reportTxId = Buffer.alloc(32);
-        Buffer.from(params.reportTxId).copy(reportTxId, 0, 0, Math.min(32, params.reportTxId.length));
+        const reportTxId = encodeReportTxId(params.reportTxId);
         const ix = await getSaveObservationsInstructionAsync({
             observer: this.signer,
             epochIndex: BigInt(epochIndex),
@@ -1821,9 +1890,18 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
      */
     async distributeEpoch(params, _options) {
         const garConfig = await this.getGarConfig();
+        // ario_gar::distribute_epoch CPIs into ario_core::release_treasury_to_recipient
+        // (signed by the ArioConfig PDA — the canonical treasury authority). The
+        // generated builder expects `arioConfig` + `arioCoreProgram` accounts at
+        // positions 6+7 (post-PR-19 in ar-io-solana-contracts). Pin both to the
+        // configured core program so devnet/testnet deployments don't fall back
+        // to the bundled mainnet default.
+        const [arioConfig] = await getArioConfigPDA(this.coreProgram);
         const ix = await getDistributeEpochInstructionAsync(await this.withGarDefaults({
             protocolTokenAccount: garConfig.protocolTokenAccount,
             stakeTokenAccount: garConfig.stakeTokenAccount,
+            arioConfig,
+            arioCoreProgram: this.coreProgram,
             payer: this.signer,
             epochIndex: BigInt(params.epochIndex),
         }), { programAddress: this.garProgram });

package/lib/esm/solana/send.js

@@ -1,62 +1,15 @@
 /**
  * Shared helpers for building, signing, and sending Solana transactions
  * with @solana/kit. Used by SolanaARIOWriteable and SolanaANTWriteable.
- */
-import { address, appendTransactionMessageInstructions, compileTransaction, createTransactionMessage, getBase64EncodedWireTransaction, getSignatureFromTransaction, pipe, sendAndConfirmTransactionFactory, setTransactionMessageFeePayerSigner, setTransactionMessageLifetimeUsingBlockhash, signTransactionMessageWithSigners, } from '@solana/kit';
-const COMPUTE_BUDGET_PROGRAM = address('ComputeBudget111111111111111111111111111111');
-/**
- * Build a `SetComputeUnitLimit` instruction.
  *
- * Layout (per solana-program/compute-budget):
- *   [0]     u8 = 2  (discriminator for SetComputeUnitLimit)
- *   [1..5]  u32 LE = units
+ * Compute budget instruction builders come from `@solana-program/compute-budget`
+ * (kit-flavored Codama client); the previous hand-rolled
+ * `setComputeUnitLimitIx` / `setComputeUnitPriceIx` helpers were removed in
+ * favor of the official package. See `sendAndConfirm` below for why we always
+ * pin BOTH instructions (even with a 0 priority fee).
  */
-export function setComputeUnitLimitIx(units) {
-    const data = new Uint8Array(5);
-    data[0] = 2;
-    // u32 little-endian
-    data[1] = units & 0xff;
-    data[2] = (units >>> 8) & 0xff;
-    data[3] = (units >>> 16) & 0xff;
-    data[4] = (units >>> 24) & 0xff;
-    return {
-        programAddress: COMPUTE_BUDGET_PROGRAM,
-        accounts: [],
-        data,
-    };
-}
-/**
- * Build a `SetComputeUnitPrice` instruction.
- *
- * Layout (per solana-program/compute-budget):
- *   [0]     u8 = 3  (discriminator for SetComputeUnitPrice)
- *   [1..9]  u64 LE = micro-lamports per compute unit
- *
- * We always prepend this (alongside `SetComputeUnitLimit`) before sending,
- * even with a 0 priority fee. Wallets like Phantom will silently *append*
- * their own compute-budget instructions when the transaction is missing
- * either, and that mutation invalidates any signatures already attached by
- * paired keypair signers (e.g. the ANT mint signer in `spawnSolanaANT`),
- * producing `Transaction did not pass signature verification` on the
- * validator. Pre-supplying both keeps the wallet from rewriting the
- * message, so signatures over the original bytes still verify.
- */
-export function setComputeUnitPriceIx(microLamports) {
-    const lamports = typeof microLamports === 'bigint' ? microLamports : BigInt(microLamports);
-    const data = new Uint8Array(9);
-    data[0] = 3;
-    // u64 little-endian
-    let v = lamports;
-    for (let i = 0; i < 8; i++) {
-        data[1 + i] = Number(v & 0xffn);
-        v >>= 8n;
-    }
-    return {
-        programAddress: COMPUTE_BUDGET_PROGRAM,
-        accounts: [],
-        data,
-    };
-}
+import { getSetComputeUnitLimitInstruction, getSetComputeUnitPriceInstruction, } from '@solana-program/compute-budget';
+import { appendTransactionMessageInstructions, compileTransaction, createTransactionMessage, getBase64EncodedWireTransaction, getSignatureFromTransaction, pipe, sendAndConfirmTransactionFactory, setTransactionMessageFeePayerSigner, setTransactionMessageLifetimeUsingBlockhash, signTransactionMessageWithSigners, } from '@solana/kit';
 /**
  * Build, sign, send, and confirm a transaction in one call.
  *
@@ -66,12 +19,17 @@ export function setComputeUnitPriceIx(microLamports) {
 export async function sendAndConfirm({ rpc, rpcSubscriptions, signer, instructions, commitment = 'confirmed', computeUnitLimit = 400_000, }) {
     const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();
     const message = pipe(createTransactionMessage({ version: 0 }), (tx) => setTransactionMessageFeePayerSigner(signer, tx), (tx) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx), (tx) => appendTransactionMessageInstructions([
-        setComputeUnitLimitIx(computeUnitLimit),
+        getSetComputeUnitLimitInstruction({ units: computeUnitLimit }),
         // Always pin the priority fee (even at 0) so wallets like Phantom
-        // don't silently append their own compute-budget instructions and
-        // invalidate paired keypair-signer signatures. See
-        // `setComputeUnitPriceIx` doc comment for the full story.
-        setComputeUnitPriceIx(0n),
+        // don't silently *append* their own compute-budget instructions
+        // when the transaction is missing either limit or price. That
+        // mutation invalidates signatures already attached by paired
+        // keypair signers (e.g. the ANT mint signer in `spawnSolanaANT`),
+        // producing `Transaction did not pass signature verification` on
+        // the validator. Pre-supplying both keeps the wallet from
+        // rewriting the message, so signatures over the original bytes
+        // still verify.
+        getSetComputeUnitPriceInstruction({ microLamports: 0n }),
         ...instructions,
     ], tx));
     const signedTx = await signTransactionMessageWithSigners(message);

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

@@ -16,13 +16,13 @@
  * helper is for.
  */
 import { addSignersToTransactionMessage, appendTransactionMessageInstructions, createTransactionMessage, generateKeyPairSigner, getSignatureFromTransaction, pipe, sendAndConfirmTransactionFactory, setTransactionMessageFeePayerSigner, setTransactionMessageLifetimeUsingBlockhash, signTransactionMessageWithSigners, } from '@solana/kit';
+import { getSetComputeUnitLimitInstruction, getSetComputeUnitPriceInstruction, } from '@solana-program/compute-budget';
 import { SolanaANTRegistryWriteable } from './ant-registry-writeable.js';
 import { ARIO_ANT_PROGRAM_ID } from './constants.js';
 import { getInitializeInstructionAsync } from './generated/ant/instructions/index.js';
 import { getCreateV1Instruction } from './generated/mpl-core/instructions/index.js';
 import { DataState } from './generated/mpl-core/types/index.js';
 import { getAntRecordPDA } from './pda.js';
-import { setComputeUnitLimitIx, setComputeUnitPriceIx } from './send.js';
 /** AR.IO logo Arweave TX — matches the Rust default in `ario_ant::initialize`. */
 export const ARIO_LOGO_TX_ID = 'AnYvLJTWcG9lr2Ll5MwYWZR2o5uTE39WbpYB0zCxwKM';
 /**
@@ -181,12 +181,12 @@ export async function spawnSolanaANT(params) {
     // the mint signer on the message alongside the fee payer signer.
     const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();
     const message = pipe(createTransactionMessage({ version: 0 }), (tx) => setTransactionMessageFeePayerSigner(signer, tx), (tx) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx), (tx) => appendTransactionMessageInstructions([
-        setComputeUnitLimitIx(computeUnitLimit),
+        getSetComputeUnitLimitInstruction({ units: computeUnitLimit }),
         // Pin the priority fee (at 0) so wallets like Phantom don't
         // silently append their own compute-budget instructions and
         // invalidate the paired mint keypair signer's signature. See
-        // `setComputeUnitPriceIx` for the full story.
-        setComputeUnitPriceIx(0n),
+        // `sendAndConfirm` in `./send.js` for the full rationale.
+        getSetComputeUnitPriceInstruction({ microLamports: 0n }),
         createIx,
         initIx,
         ...aclIxs,

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.4';
+export const version = '4.0.0-solana.6';

package/lib/types/solana/io-readable.d.ts

@@ -316,4 +316,34 @@ export declare class SolanaARIOReadable {
         ttlSeconds: number;
         undernameLimit: number;
     }>;
+    /**
+     * Resolve the gateway operator pubkey backing a given observer pubkey.
+     * The `ObserverLookup` PDA is written at `join_network` (and rotated by
+     * `update_observer_address`); when present its `gateway` field is the
+     * operator pubkey. Returns `undefined` when the observer isn't
+     * registered on any gateway.
+     */
+    getObserverLookup(observer: Address): Promise<{
+        gateway: Address;
+        bump: number;
+    } | undefined>;
+    /**
+     * Pre-flight gate for `save_observations` submission. Reads the Epoch
+     * account once and reports whether the given observer pubkey is:
+     *   - `prescribed`: in `epoch.prescribed_observers[..observer_count]`
+     *   - `observerIdx`: position in the array (matches the `has_observed`
+     *     bit index when prescribed)
+     *   - `alreadyObserved`: whether the bit at `observerIdx` is set
+     *   - `windowOpen`: whether `now < epoch.end_timestamp`
+     *
+     * Use this from a sink/wrapper to skip cheap-to-skip cases before
+     * paying for a transaction simulation that would just bounce.
+     */
+    getEpochObservationStatus(epochIndex: number, observer: Address): Promise<{
+        prescribed: boolean;
+        observerIdx: number;
+        alreadyObserved: boolean;
+        windowOpen: boolean;
+        endTimestampSec: number;
+    }>;
 }

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

@@ -58,6 +58,30 @@ export declare function splitPrimaryName(name: string): {
  * await ario.transfer({ target: 'RecipientPubkey...', qty: 100_000_000 });
  * ```
  */
+/** Build the gateway_results bitmap for save_observations.
+ *  All bits start as 1 (pass) for the first `registryAddresses.length`
+ *  positions; positions named in `failedGateways` get cleared to 0; all
+ *  positions beyond `registryAddresses.length` are 0. */
+export declare function buildObservationBitmap(registryAddresses: string[], failedGateways: string[]): Buffer;
+/** Encode an Arweave TX ID into the on-chain `[u8; 32]` slot.
+ *
+ *  An Arweave TX ID **is** a 32-byte SHA-256 hash; the 43-char base64url
+ *  string is just its presentation encoding. We decode here so the
+ *  on-chain bytes are the raw hash — lossless and trivially reversible
+ *  via base64url-encode on the consumer side. Without this, on-chain
+ *  bytes alone couldn't be used to look up the original report bundle
+ *  on permaweb (the whole point of recording the txid for auditability).
+ *
+ *  Empty / undefined input → 32 zero bytes ("no permaweb archive
+ *  configured for this submission" — the report still lives off-chain
+ *  in the observer's local sinks but isn't anchored on Arweave).
+ *
+ *  Throws on malformed input: the base64url string must be exactly 43
+ *  chars and decode to 32 bytes. Strict validation here is desirable —
+ *  silently truncating or accepting bad input would erode the
+ *  auditability that the field exists for.
+ */
+export declare function encodeReportTxId(reportTxId: string | undefined): Buffer;
 export declare class SolanaARIOWriteable extends SolanaARIOReadable {
     protected readonly signer: SolanaSigner;
     protected readonly rpcSubscriptions: SolanaRpcSubscriptions;

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

@@ -1,34 +1,5 @@
-/**
- * Shared helpers for building, signing, and sending Solana transactions
- * with @solana/kit. Used by SolanaARIOWriteable and SolanaANTWriteable.
- */
 import { type Commitment, type Instruction, type TransactionSigner } from '@solana/kit';
 import type { SolanaRpc, SolanaRpcSubscriptions } from './types.js';
-/**
- * Build a `SetComputeUnitLimit` instruction.
- *
- * Layout (per solana-program/compute-budget):
- *   [0]     u8 = 2  (discriminator for SetComputeUnitLimit)
- *   [1..5]  u32 LE = units
- */
-export declare function setComputeUnitLimitIx(units: number): Instruction;
-/**
- * Build a `SetComputeUnitPrice` instruction.
- *
- * Layout (per solana-program/compute-budget):
- *   [0]     u8 = 3  (discriminator for SetComputeUnitPrice)
- *   [1..9]  u64 LE = micro-lamports per compute unit
- *
- * We always prepend this (alongside `SetComputeUnitLimit`) before sending,
- * even with a 0 priority fee. Wallets like Phantom will silently *append*
- * their own compute-budget instructions when the transaction is missing
- * either, and that mutation invalidates any signatures already attached by
- * paired keypair signers (e.g. the ANT mint signer in `spawnSolanaANT`),
- * producing `Transaction did not pass signature verification` on the
- * validator. Pre-supplying both keeps the wallet from rewriting the
- * message, so signatures over the original bytes still verify.
- */
-export declare function setComputeUnitPriceIx(microLamports: bigint | number): Instruction;
 /**
  * Build, sign, send, and confirm a transaction in one call.
  *

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.3";
+export declare const version = "4.0.0-solana.5";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/sdk",
-  "version": "4.0.0-solana.4",
+  "version": "4.0.0-solana.6",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ar-io/ar-io-sdk.git"
@@ -9,6 +9,7 @@
   "module": "./lib/esm/node/index.js",
   "types": "./lib/types/node/index.d.ts",
   "type": "module",
+  "packageManager": "yarn@1.22.22",
   "engines": {
     "node": ">=18"
   },
@@ -133,6 +134,7 @@
     "@dha-team/arbundles": "^1.0.1",
     "@permaweb/aoconnect": "0.0.68",
     "@solana-program/compute-budget": "^0.15.0",
+    "@solana-program/token": "^0.13.0",
     "@solana/kit": "^6.8.0",
     "arweave": "1.15.5",
     "axios": "^1.13.2",