@ar.io/sdk 4.0.0-solana.5 → 4.0.0-solana.7

package/README.md

@@ -11,14 +11,6 @@ This is the home of the ar.io SDK. This SDK provides functionality for interacti
 - [Table of Contents](#table-of-contents)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
-- [Usage](#usage)
-- [ARIO Contract](#ario-contract)
-- [ANT Contracts](#ant-contracts)
-- [Token Conversion](#token-conversion)
-- [Logging](#logging)
-- [Pagination](#pagination)
-- [Resources](#resources)
-- [Developers](#developers)
 
 <!-- tocstop -->
 
@@ -114,7 +106,7 @@ const gateways = await ario.getGateways();
 
 ## Usage
 
-The SDK is provided in both CommonJS and ESM formats and is compatible with bundlers such as Webpack, Rollup, and ESbuild. Utilize the appropriately named exports provided by this SDK's [package.json] based on your project's configuration. Refer to the [examples] directory to see how to use the SDK in various environments.
+The SDK is published as an ES module (`"type": "module"`) and is compatible with modern bundlers such as Webpack, Rollup, ESbuild, and Vite. CommonJS consumers should migrate to ESM (Node 18+ supports ESM natively, and modern bundlers handle ESM packages out of the box). Utilize the appropriately named exports provided by this SDK's [package.json] based on your project's configuration. Refer to the [examples] directory to see how to use the SDK in various environments.
 
 ### Web
 
@@ -148,8 +140,6 @@ const gateways = await ario.getGateways();
 
 ### Node
 
-#### ESM (NodeNext)
-
 ```javascript
 import { ARIO } from "@ar.io/sdk/node";
 
@@ -159,17 +149,6 @@ const ario = ARIO.mainnet();
 const gateways = await ario.getGateways();
 ```
 
-#### CJS
-
-```javascript
-import { ARIO } from "@ar.io/sdk";
-
-// set up client
-const ario = ARIO.mainnet();
-// fetch gateways
-const gateways = await ario.getGateways();
-```
-
 ### Typescript
 
 The SDK provides TypeScript types. When you import the SDK in a TypeScript project types are exported from `./lib/types/[node/web]/index.d.ts` and should be automatically recognized by package managers, offering benefits such as type-checking and autocompletion.
@@ -3355,7 +3334,6 @@ For more information on how to use AO and AO Connect within this library, please
 - `yarn test:e2e` - runs e2e tests
 - `yarn test:unit` - runs unit tests
 - `yarn example:web` - opens up the example web page
-- `yarn example:cjs` - runs example CJS node script
 - `yarn example:esm` - runs example ESM node script
 - `yarn example:vite` - runs example Vite web page
 

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

@@ -12,11 +12,11 @@ import bs58 from 'bs58';
 // AntRecordMetadata discriminator — regenerate via `yarn codegen` after IDL rebase
 // to expose ANT_RECORD_METADATA_DISCRIMINATOR. Until then, compute inline.
 import { createHash as __createHash } from 'crypto';
+import { ANT_RECORD_DISCRIMINATOR } from '@ar.io/solana-contracts/ant';
 import { Logger } from '../common/logger.js';
 import { SolanaANTRegistryReadable } from './ant-registry-readable.js';
 import { ANT_CONFIG_VERSION, ARIO_ANT_PROGRAM_ID } from './constants.js';
 import { deserializeAntConfig, deserializeAntControllers, deserializeAntRecord, deserializeAntRecordMetadata, } from './deserialize.js';
-import { ANT_RECORD_DISCRIMINATOR } from './generated/ant/accounts/antRecord.js';
 const ANT_RECORD_METADATA_DISCRIMINATOR = new Uint8Array(__createHash('sha256')
     .update('account:AntRecordMetadata')
     .digest()

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

@@ -38,10 +38,10 @@
  * registry's signer) acts as the rent payer for everything bundled here.
  */
 import { address, } from '@solana/kit';
+import { getAddAclPageInstruction, getCloseAclConfigInstruction, getCloseAclPageInstruction, getRecordAclControllerInstructionAsync, getRecordAclOwnerInstruction, getRegisterAclConfigInstruction, getRemoveAclControllerInstructionAsync, getRemoveAclOwnerInstruction, } from '@ar.io/solana-contracts/ant';
 import { SolanaANTRegistryReadable, } from './ant-registry-readable.js';
 import { ACL_ROLE_CONTROLLER, ACL_ROLE_OWNER, MAX_ACL_PAGE_ENTRIES, } from './constants.js';
 import { deserializeAclConfig, deserializeAclPage } from './deserialize.js';
-import { getAddAclPageInstruction, getCloseAclConfigInstruction, getCloseAclPageInstruction, getRecordAclControllerInstructionAsync, getRecordAclOwnerInstruction, getRegisterAclConfigInstruction, getRemoveAclControllerInstructionAsync, getRemoveAclOwnerInstruction, } from './generated/ant/instructions/index.js';
 import { getAccountInfoLegacy, getMultipleAccountsInfoLegacy, } from './json-rpc.js';
 import { getAclConfigPDA, getAclPagePDA } from './pda.js';
 /** Map the cross-backend role string → on-chain `u8` byte. */

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

@@ -28,10 +28,10 @@
  *        if a marketplace transfer bypasses this SDK entirely.
  */
 import { address, } from '@solana/kit';
+import { getAddControllerInstructionAsync, getMigrateAntInstructionAsync, getReconcileInstructionAsync, getRemoveControllerInstructionAsync, getRemoveRecordInstructionAsync, getSetDescriptionInstructionAsync, getSetKeywordsInstructionAsync, getSetLogoInstructionAsync, getSetNameInstructionAsync, getSetRecordInstructionAsync, getSetRecordMetadataInstructionAsync, getSetTickerInstructionAsync, getTransferInstructionAsync, getTransferRecordInstructionAsync, } from '@ar.io/solana-contracts/ant';
 import { SolanaANTReadable } from './ant-readable.js';
 import { SolanaANTRegistryWriteable } from './ant-registry-writeable.js';
 import { deserializeAntControllers } from './deserialize.js';
-import { getAddControllerInstructionAsync, getMigrateAntInstructionAsync, getReconcileInstructionAsync, getRemoveControllerInstructionAsync, getRemoveRecordInstructionAsync, getSetDescriptionInstructionAsync, getSetKeywordsInstructionAsync, getSetLogoInstructionAsync, getSetNameInstructionAsync, getSetRecordInstructionAsync, getSetRecordMetadataInstructionAsync, getSetTickerInstructionAsync, getTransferInstructionAsync, getTransferRecordInstructionAsync, } from './generated/ant/instructions/index.js';
 import { getAccountInfoLegacy } from './json-rpc.js';
 import { getAntControllersPDA, getAntRecordMetadataPDA, getAntRecordPDA, } from './pda.js';
 import { sendAndConfirm } from './send.js';

package/lib/esm/solana/deserialize.js

@@ -28,8 +28,9 @@
  *   - Enum: 1-byte variant index
  */
 import { getAddressDecoder, getAddressEncoder, } from '@solana/kit';
+import { getBalanceDecoder } from '@ar.io/solana-contracts/core';
+import { getEpochDecoder } from '@ar.io/solana-contracts/gar';
 import { RATE_SCALE } from './constants.js';
-import { getBalanceDecoder } from './generated/core/accounts/balance.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/escrow.js

@@ -15,12 +15,11 @@
  * in `./generated/ant-escrow/instructions/` — they own the discriminator,
  * 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 { fetchMaybeEscrowAnt, fetchMaybeEscrowToken, getCancelDepositInstruction, getCancelTokenDepositInstruction, getCancelVaultDepositInstruction, getClaimAntArweaveInstruction, getClaimAntEthereumInstruction, getClaimTokensArweaveInstruction, getClaimTokensEthereumInstruction, getClaimVaultArweaveInstruction, getClaimVaultEthereumInstruction, getDepositAntInstruction, getDepositTokensInstruction, getDepositVaultInstruction, getUpdateRecipientInstruction, getUpdateTokenRecipientInstruction, getUpdateVaultRecipientInstruction, } from './generated/ant-escrow/index.js';
-import { fetchMaybeVaultCounter } from './generated/core/accounts/vaultCounter.js';
-import { getVaultedTransferInstructionAsync } from './generated/core/instructions/vaultedTransfer.js';
 import { getEscrowAntPDA, getEscrowTokenPDA, getEscrowVaultPDA, getVaultCounterPDA, getVaultPDA, } from './pda.js';
 import { sendAndConfirm } from './send.js';
 /** Map the Codama-generated `EscrowAnt` raw decoded type to our public
@@ -172,24 +171,37 @@ export class ANTEscrow {
         // provide comfortable headroom.
         return this.send([ix], 400_000);
     }
+    /**
+     * Build the ANT-claim-via-Arweave-attested instruction.
+     *
+     * **API note**: this method previously took user-side RSA-PSS params
+     * (`signature`, `saltLen`, `messageNonce`). The on-chain ix was
+     * renamed to `claim_ant_arweave_attested` (canonical contracts
+     * `ar-io-solana-contracts` PR-19+): verification is now via
+     * instruction-introspection of a preceding Ed25519 sigverify ix
+     * issued by the off-chain attestor (see
+     * `migration/attestor/`). Those data args are no longer fed to the
+     * builder. Callers MUST prepend the attestor's sigverify ix to the
+     * transaction or it will fail on-chain. A higher-level helper that
+     * fetches the attestor's signature and assembles the full tx is
+     * tracked as a follow-up.
+     *
+     * @deprecated Args `signature`, `saltLen`, `messageNonce` are
+     * ignored. Use the new attested flow.
+     */
     async claimArweaveIx(args) {
-        if (args.signature.length !== 512) {
-            throw new Error('arweave signature must be 512 bytes');
-        }
         if (args.messageNonce.length !== 32) {
             throw new Error('messageNonce must be 32 bytes');
         }
         const signer = this.requireSigner('claimArweave');
         const [escrow] = await getEscrowAntPDA(args.antMint, this.programId);
-        return getClaimAntArweaveInstruction({
+        return getClaimAntArweaveAttestedInstruction({
             escrow,
             antAsset: args.antMint,
             claimant: args.claimant,
             depositor: args.depositor,
             payer: signer,
             messageNonce: args.messageNonce,
-            signature: args.signature,
-            saltLen: args.saltLen,
         }, { programAddress: this.programId });
     }
     /** Submit an Ethereum ECDSA secp256k1 + EIP-191 signature. */
@@ -466,16 +478,17 @@ export class TokenEscrow {
         // RSA-PSS-4096 verification is CU-intensive; use 400K.
         return this.send(createAtaIx ? [createAtaIx, ix] : [ix], 400_000);
     }
+    /**
+     * @deprecated Args `signature`, `saltLen`, `messageNonce` are ignored.
+     * Use the new attested flow — see `claimArweaveIx` doc.
+     */
     async claimTokensArweaveIx(args) {
-        if (args.signature.length !== 512) {
-            throw new Error('arweave signature must be 512 bytes');
-        }
         if (args.messageNonce.length !== 32) {
             throw new Error('messageNonce must be 32 bytes');
         }
         const signer = this.requireSigner('claimTokensArweave');
         const [escrow] = await getEscrowTokenPDA(args.depositor, args.assetId, this.programId);
-        return getClaimTokensArweaveInstruction({
+        return getClaimTokensArweaveAttestedInstruction({
             escrow,
             escrowTokenAccount: args.escrowTokenAccount,
             claimantTokenAccount: args.claimantTokenAccount,
@@ -483,8 +496,6 @@ export class TokenEscrow {
             depositor: args.depositor,
             payer: signer,
             messageNonce: args.messageNonce,
-            signature: args.signature,
-            saltLen: args.saltLen,
         }, { programAddress: this.programId });
     }
     /**
@@ -545,7 +556,11 @@ export class TokenEscrow {
         }
         const signer = this.requireSigner('claimVaultArweave');
         const [escrowPda] = await getEscrowVaultPDA(args.depositor, args.assetId, this.programId);
-        const claimIx = getClaimVaultArweaveInstruction({
+        // `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({
             escrow: escrowPda,
             escrowTokenAccount: args.escrowTokenAccount,
             claimantTokenAccount: args.claimantTokenAccount,
@@ -554,8 +569,6 @@ export class TokenEscrow {
             depositor: args.depositor,
             payer: signer,
             messageNonce: escrow.nonce,
-            signature: args.signature,
-            saltLen: args.saltLen ?? 32,
         }, { programAddress: this.programId });
         const ixs = await this.maybeBundleVaultedTransfer(escrow, args, claimIx);
         return this.send(ixs, 400_000);

package/lib/esm/solana/events.js

@@ -28,11 +28,11 @@
  * pull-based model.
  */
 import { getBase64Encoder, } from '@solana/kit';
-import { ARIO_ANT_ESCROW_PROGRAM_ADDRESS } from './generated/ant-escrow/program-address.js';
-import { ARIO_ANT_PROGRAM_ADDRESS } from './generated/ant/program-address.js';
-import { ARIO_ARNS_PROGRAM_ADDRESS } from './generated/arns/program-address.js';
-import { ARIO_CORE_PROGRAM_ADDRESS } from './generated/core/program-address.js';
-import { ARIO_GAR_PROGRAM_ADDRESS } from './generated/gar/program-address.js';
+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';

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

@@ -29,7 +29,7 @@
  * `TooManyFundingSources` / `TooManyDelegationSources`.
  */
 import { AccountRole, fetchEncodedAccount, getAddressDecoder, } from '@solana/kit';
-import { ARIO_GAR_PROGRAM_ADDRESS as ARIO_GAR_PROGRAM_ID } from './generated/gar/program-address.js';
+import { ARIO_GAR_PROGRAM_ADDRESS as ARIO_GAR_PROGRAM_ID } from '@ar.io/solana-contracts/gar';
 import { getDelegationPDA, getGatewayPDA, getWithdrawalCounterPDA, getWithdrawalPDA, } from './pda.js';
 // ---------------------------------------------------------------------------
 // Public types

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

@@ -7,26 +7,16 @@
  */
 import { address, fetchEncodedAccount, fetchEncodedAccounts, getAddressDecoder, } from '@solana/kit';
 import bs58 from 'bs58';
+import { ARNS_RECORD_DISCRIMINATOR, RESERVED_NAME_DISCRIMINATOR, RETURNED_NAME_DISCRIMINATOR, getArnsConfigDecoder, getArnsRecordDecoder, getReservedNameDecoder, getReturnedNameDecoder, } from '@ar.io/solana-contracts/arns';
+import { PRIMARY_NAME_DISCRIMINATOR, PRIMARY_NAME_REQUEST_DISCRIMINATOR, VAULT_DISCRIMINATOR, getPrimaryNameRequestDecoder, getVaultDecoder, } from '@ar.io/solana-contracts/core';
+import { ALLOWLIST_ENTRY_DISCRIMINATOR, DELEGATION_DISCRIMINATOR, GATEWAY_DISCRIMINATOR, GatewayStatus, OBSERVATION_DISCRIMINATOR, WITHDRAWAL_DISCRIMINATOR, getDelegationDecoder, getGatewayDecoder, getWithdrawalDecoder, } from '@ar.io/solana-contracts/gar';
 import { Logger } from '../common/logger.js';
 import { SolanaANTRegistryReadable } from './ant-registry-readable.js';
 import { getAssociatedTokenAddressKit } from './ata.js';
 import { ARIO_ANT_PROGRAM_ID, ARIO_ARNS_PROGRAM_ID, ARIO_CORE_PROGRAM_ID, ARIO_GAR_PROGRAM_ID, ARNS_RECORD_ANT_OFFSET, RATE_SCALE, } from './constants.js';
 import { deserializeAllowlist, deserializeArioConfig, deserializeArnsRecord, deserializeDelegation, deserializeDemandFactor, deserializeEpoch, deserializeEpochSettings, deserializeEpochSettingsFull, deserializeGarSettings, deserializeGarSupplyCounters, deserializeGateway, deserializeObservation, deserializePrimaryName, deserializePrimaryNameRequest, deserializeRedelegationRecord, deserializeReservedName, deserializeReturnedName, deserializeVault, deserializeWithdrawal, } from './deserialize.js';
-import { getArnsConfigDecoder } from './generated/arns/accounts/arnsConfig.js';
-import { ARNS_RECORD_DISCRIMINATOR, getArnsRecordDecoder, } from './generated/arns/accounts/arnsRecord.js';
-import { RESERVED_NAME_DISCRIMINATOR, getReservedNameDecoder, } from './generated/arns/accounts/reservedName.js';
-import { RETURNED_NAME_DISCRIMINATOR, getReturnedNameDecoder, } from './generated/arns/accounts/returnedName.js';
-import { PRIMARY_NAME_DISCRIMINATOR } from './generated/core/accounts/primaryName.js';
-import { PRIMARY_NAME_REQUEST_DISCRIMINATOR, getPrimaryNameRequestDecoder, } from './generated/core/accounts/primaryNameRequest.js';
-import { VAULT_DISCRIMINATOR, getVaultDecoder, } from './generated/core/accounts/vault.js';
-import { ALLOWLIST_ENTRY_DISCRIMINATOR } from './generated/gar/accounts/allowlistEntry.js';
-import { DELEGATION_DISCRIMINATOR, getDelegationDecoder, } from './generated/gar/accounts/delegation.js';
-import { GATEWAY_DISCRIMINATOR, getGatewayDecoder, } from './generated/gar/accounts/gateway.js';
-import { OBSERVATION_DISCRIMINATOR } from './generated/gar/accounts/observation.js';
-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 +784,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 +1605,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

@@ -19,12 +19,11 @@
  *      surface for them.
  */
 import { AccountRole, address, fetchEncodedAccount, getAddressDecoder, } from '@solana/kit';
+import { PurchaseType, getBuyNameFromDelegationInstructionAsync, getBuyNameFromFundingPlanInstructionAsync, getBuyNameFromOperatorStakeInstructionAsync, getBuyNameFromWithdrawalInstructionAsync, getBuyNameInstructionAsync, getBuyReturnedNameFromDelegationInstructionAsync, getBuyReturnedNameFromFundingPlanInstructionAsync, getBuyReturnedNameFromOperatorStakeInstructionAsync, getBuyReturnedNameFromWithdrawalInstructionAsync, getBuyReturnedNameInstructionAsync, getExtendLeaseFromDelegationInstructionAsync, getExtendLeaseFromFundingPlanInstructionAsync, getExtendLeaseFromOperatorStakeInstructionAsync, getExtendLeaseFromWithdrawalInstructionAsync, getExtendLeaseInstructionAsync, getIncreaseUndernameLimitFromDelegationInstructionAsync, getIncreaseUndernameLimitFromFundingPlanInstructionAsync, getIncreaseUndernameLimitFromOperatorStakeInstructionAsync, getIncreaseUndernameLimitFromWithdrawalInstructionAsync, getIncreaseUndernameLimitInstructionAsync, getPruneExpiredNamesInstructionAsync, getPruneExpiredReservationInstruction, getPruneNameToReturnedInstructionAsync, getPruneReturnedNamesInstructionAsync, getReassignNameInstructionAsync, getReleaseNameInstructionAsync, getUpgradeNameFromDelegationInstructionAsync, getUpgradeNameFromFundingPlanInstructionAsync, getUpgradeNameFromOperatorStakeInstructionAsync, getUpgradeNameFromWithdrawalInstructionAsync, getUpgradeNameInstructionAsync, } from '@ar.io/solana-contracts/arns';
+import { FundingSourceKind as GeneratedFundingSourceKindEnum } from '@ar.io/solana-contracts/gar';
 import { buildCreateAtaIdempotentIx, getAssociatedTokenAddressKit, } from './ata.js';
 import { deserializeArnsRecord, deserializeEpochSettingsFull, } from './deserialize.js';
 import { buildFundingPlan as buildFundingPlanCore, buildFundingPlanRemainingAccounts, computeResidueIndexes, predictResidueVaults, } from './funding-plan.js';
-import { getBuyNameFromDelegationInstructionAsync, getBuyNameFromFundingPlanInstructionAsync, getBuyNameFromOperatorStakeInstructionAsync, getBuyNameFromWithdrawalInstructionAsync, getBuyNameInstructionAsync, getBuyReturnedNameFromDelegationInstructionAsync, getBuyReturnedNameFromFundingPlanInstructionAsync, getBuyReturnedNameFromOperatorStakeInstructionAsync, getBuyReturnedNameFromWithdrawalInstructionAsync, getBuyReturnedNameInstructionAsync, getExtendLeaseFromDelegationInstructionAsync, getExtendLeaseFromFundingPlanInstructionAsync, getExtendLeaseFromOperatorStakeInstructionAsync, getExtendLeaseFromWithdrawalInstructionAsync, getExtendLeaseInstructionAsync, getIncreaseUndernameLimitFromDelegationInstructionAsync, getIncreaseUndernameLimitFromFundingPlanInstructionAsync, getIncreaseUndernameLimitFromOperatorStakeInstructionAsync, getIncreaseUndernameLimitFromWithdrawalInstructionAsync, getIncreaseUndernameLimitInstructionAsync, getPruneExpiredNamesInstructionAsync, getPruneExpiredReservationInstruction, getPruneNameToReturnedInstructionAsync, getPruneReturnedNamesInstructionAsync, getReassignNameInstructionAsync, getReleaseNameInstructionAsync, getUpgradeNameFromDelegationInstructionAsync, getUpgradeNameFromFundingPlanInstructionAsync, getUpgradeNameFromOperatorStakeInstructionAsync, getUpgradeNameFromWithdrawalInstructionAsync, getUpgradeNameInstructionAsync, } from './generated/arns/instructions/index.js';
-import { PurchaseType } from './generated/arns/types/index.js';
-import { FundingSourceKind as GeneratedFundingSourceKindEnum } from './generated/gar/types/index.js';
 /** Maps the SDK's user-facing FundingSourceKind string union to the
  *  Codama-generated enum used by the on-chain ix payload. */
 function toGeneratedFundingSourceSpec(s) {
@@ -36,14 +35,12 @@ function toGeneratedFundingSourceSpec(s) {
     };
     return { kind: kindMap[s.kind], amount: s.amount };
 }
+import { getSyncAttributesInstruction } from '@ar.io/solana-contracts/ant';
+import { getApprovePrimaryNameInstructionAsync, getCloseExpiredRequestInstruction, getCreateVaultInstructionAsync, getExtendVaultInstructionAsync, getIncreaseVaultInstructionAsync, getReleaseVaultInstructionAsync, getRequestAndSetPrimaryNameFromFundingPlanInstructionAsync, getRequestPrimaryNameFromFundingPlanInstructionAsync, getRequestPrimaryNameInstructionAsync, getRevokeVaultInstructionAsync, getVaultedTransferInstructionAsync, } from '@ar.io/solana-contracts/core';
+import { getDelegationDecoder, getGatewayDecoder, } from '@ar.io/solana-contracts/gar';
+import { Protocol, 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 '@ar.io/solana-contracts/gar';
 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, 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';
-import { Protocol } from './generated/gar/types/index.js';
 import { SolanaARIOReadable } from './io-readable.js';
 import { getAntRecordPDA, getArioConfigPDA, getArnsRecordPDA, getArnsRegistryPDA, getArnsSettingsPDA, getDelegationPDA, getDemandFactorPDA, getEpochPDA, getEpochSettingsPDA, getGarSettingsPDA, getGatewayPDA, getGatewayRegistryPDA, getObservationPDA, getObserverLookupPDA, getPrimaryNamePDA, getPrimaryNameRequestPDA, getPrimaryNameReversePDA, getReservedNamePDA, getReturnedNamePDA, getVaultPDA, getWithdrawalCounterPDA, getWithdrawalPDA, hashName, } from './pda.js';
 import { sendAndConfirm } from './send.js';
@@ -111,6 +108,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;
@@ -566,22 +636,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),
@@ -1830,9 +1887,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 });