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

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/constants.js

@@ -16,6 +16,12 @@ export const MPL_CORE_PROGRAM_ID = address('CoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH
 export const TOKEN_DECIMALS = 6;
 export const ONE_TOKEN = 1_000_000; // 1 ARIO = 1,000,000 mARIO
 export const RATE_SCALE = 1_000_000;
+/**
+ * Scaling factor for the per-share reward accumulator
+ * `Gateway.cumulative_reward_per_token` in `ario-gar`. Must match the
+ * `REWARD_PRECISION` constant in `programs/ario-gar/src/state/mod.rs`.
+ */
+export const REWARD_PRECISION = 1000000000000000000n; // 1e18
 // =========================================
 // PDA Seeds — ario-core
 // =========================================

package/lib/esm/solana/delegation-math.js

@@ -0,0 +1,63 @@
+/**
+ * Delegation balance math.
+ *
+ * On-chain, `Delegation.amount` is the last-settled principal. Pending rewards
+ * are tracked separately via the gateway's per-share accumulator
+ * (`Gateway.cumulative_reward_per_token`) and the delegate's snapshot of that
+ * accumulator at the last settlement (`Delegation.reward_debt`). The
+ * `distribute_epoch` instruction advances the accumulator but does NOT touch
+ * per-`Delegation.amount` — that field is updated lazily on the next
+ * delegation interaction (or via the permissionless
+ * `compound_delegation_rewards` instruction).
+ *
+ * Off-chain readers (indexers, wallets, the network portal) that want to show
+ * a delegate's current balance must therefore compute the live value from the
+ * accumulator + reward_debt; reading `Delegation.amount` directly under-reports
+ * every epoch of pending rewards.
+ *
+ * This module mirrors the on-chain `settle_delegate_rewards` math from
+ * `programs/ario-gar/src/state/mod.rs` so the SDK can return live values from
+ * its read-side methods (`getGatewayDelegates`, `getDelegations`,
+ * `getAllDelegates`) without needing an on-chain settlement call.
+ *
+ * See `INVARIANTS.md` in the contracts repo for the broader stake-pool
+ * invariant context.
+ */
+import { REWARD_PRECISION } from './constants.js';
+const U64_MAX = (1n << 64n) - 1n;
+/**
+ * Compute the live delegation balance: the last-settled principal plus any
+ * pending rewards accrued since the last settlement.
+ *
+ * Mirrors `settle_delegate_rewards` in
+ * `programs/ario-gar/src/state/mod.rs` — including the u128 overflow-safe
+ * quotient/remainder split and the saturating-to-`u64::MAX` cap at the end —
+ * so a value computed here matches what the on-chain instruction would write
+ * if it were called right now.
+ *
+ * @param delegatedStake          - `Delegation.amount` (u64 → number).
+ * @param rewardDebt              - `Delegation.reward_debt` (u128 → bigint).
+ * @param cumulativeRewardPerToken - `Gateway.cumulative_reward_per_token` (u128 → bigint).
+ * @returns The delegate's live balance in mARIO, saturating-capped at `u64::MAX`.
+ */
+export function computeLiveDelegationBalance({ delegatedStake, rewardDebt, cumulativeRewardPerToken, }) {
+    // Fast paths matching the on-chain `if` guards: zero principal or no
+    // accumulator delta means no pending rewards to settle.
+    if (delegatedStake <= 0 || cumulativeRewardPerToken <= rewardDebt) {
+        return delegatedStake;
+    }
+    const amount = BigInt(delegatedStake);
+    const delta = cumulativeRewardPerToken - rewardDebt;
+    // Quotient / remainder split mirrors the on-chain `checked_mul ... unwrap_or_else`
+    // fallback. BigInt has no native overflow, so we always take the split path
+    // for parity; the result is identical either way.
+    const quot = delta / REWARD_PRECISION;
+    const rem = delta % REWARD_PRECISION;
+    const fromQuot = amount * quot; // saturating not needed — BigInt is unbounded
+    const fromRem = (amount * rem) / REWARD_PRECISION;
+    const pending = fromQuot + fromRem;
+    // Saturating cap at u64::MAX to match the on-chain `u64::try_from(...).unwrap_or(u64::MAX)`.
+    const live = amount + pending;
+    const capped = live > U64_MAX ? U64_MAX : live;
+    return Number(capped);
+}

package/lib/esm/solana/deserialize.js

@@ -28,9 +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';
-import { getEpochDecoder } from './generated/gar/accounts/epoch.js';
 const addressDecoder = getAddressDecoder();
 const addressEncoder = getAddressEncoder();
 // =========================================
@@ -281,12 +281,18 @@ function scaleToFloat(value, scale = RATE_SCALE) {
 // Gateway deserialization
 // =========================================
 /**
- * Deserialize a Gateway account from raw bytes.
- * PDA: ["gateway", operator_pubkey] in ario-gar program.
+ * Internal variant of {@link deserializeGateway} that additionally surfaces
+ * the on-chain `cumulative_reward_per_token` u128 accumulator. Used by the
+ * live delegation balance pipeline ({@link computeLiveDelegationBalance} via
+ * `getGatewayAccumulators` in `io-readable.ts`).
+ *
+ * Not part of the public AoGateway shape — `bigint` is not JSON-serializable
+ * and would leak through `getGateway` / `getGateways`. Prefer
+ * {@link deserializeGateway} everywhere except inside live-balance plumbing.
  *
- * Returns the SDK-compatible AoGateway type.
+ * PDA: ["gateway", operator_pubkey] in ario-gar program.
  */
-export function deserializeGateway(data) {
+export function deserializeGatewayWithAccumulator(data) {
     const r = new BorshReader(data, 8); // skip 8-byte discriminator
     const operator = r.readPubkey();
     const label = r.readString();
@@ -329,8 +335,12 @@ export function deserializeGateway(data) {
     r.readU8(); // _reserved (layout-preserving placeholder for the legacy is_registered byte)
     // observer_address
     const observerAddress = r.readPubkey();
-    // cumulative_reward_per_token (u128, not exposed in SDK type)
-    r.skip(16);
+    // cumulative_reward_per_token: u128 — per-share accumulator advanced by
+    // distribute_epoch. Combined with each Delegation.reward_debt, this lets
+    // off-chain readers compute the live delegate balance without an on-chain
+    // settlement call. Not part of the public AoGateway type but surfaced as
+    // an extra field on this function's return so internal readers can use it.
+    const cumulativeRewardPerToken = r.readU128();
     // bump
     r.skip(1);
     const stats = {
@@ -378,8 +388,24 @@ export function deserializeGateway(data) {
         operatorStake,
         status: statusIdx === 0 ? 'joined' : 'leaving',
         weights,
+        cumulativeRewardPerToken,
     };
 }
+/**
+ * Deserialize a Gateway account from raw bytes.
+ *
+ * Returns the SDK-compatible AoGateway type (plus `operator: string`).
+ * The on-chain `cumulative_reward_per_token` u128 is intentionally NOT
+ * surfaced on the returned object — `bigint` is not JSON-serializable,
+ * and leaking it through `getGateway` / `getGateways` would break
+ * downstream consumers that call `JSON.stringify` on results. Use
+ * {@link deserializeGatewayWithAccumulator} from within the live-balance
+ * pipeline when the accumulator value is actually needed.
+ */
+export function deserializeGateway(data) {
+    const { cumulativeRewardPerToken: _unused, ...publicShape } = deserializeGatewayWithAccumulator(data);
+    return publicShape;
+}
 // =========================================
 // ArNS Record deserialization
 // =========================================
@@ -477,13 +503,17 @@ export function deserializeDelegation(data) {
     const delegator = r.readPubkey();
     const amount = r.readU64AsNumber();
     const startTimestamp = r.readI64AsNumber();
-    // reward_debt: u128, bump: u8 — skip
-    r.skip(16 + 1);
+    // reward_debt: u128 — snapshot of gateway.cumulative_reward_per_token at last
+    // settlement. Needed (together with the gateway's current accumulator) to
+    // compute the live delegate balance via computeLiveDelegationBalance().
+    const rewardDebt = r.readU128();
+    r.skip(1); // bump
     return {
         gateway: gateway,
         delegator: delegator,
         delegatedStake: amount,
         startTimestamp,
+        rewardDebt,
     };
 }
 // =========================================

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,24 +7,15 @@
  */
 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 { computeLiveDelegationBalance } from './delegation-math.js';
+import { deserializeAllowlist, deserializeArioConfig, deserializeArnsRecord, deserializeDelegation, deserializeDemandFactor, deserializeEpoch, deserializeEpochSettings, deserializeEpochSettingsFull, deserializeGarSettings, deserializeGarSupplyCounters, deserializeGateway, deserializeGatewayWithAccumulator, deserializeObservation, deserializePrimaryName, deserializePrimaryNameRequest, deserializeRedelegationRecord, deserializeReservedName, deserializeReturnedName, deserializeVault, deserializeWithdrawal, } from './deserialize.js';
 import { TOKEN_PROGRAM_ADDRESS } from './instruction.js';
 import { getArioConfigPDA, getArnsRecordPDA, getArnsRecordPDAFromHash, getArnsSettingsPDA, getDemandFactorPDA, getEpochPDA, getEpochSettingsPDA, getGarSettingsPDA, getGatewayPDA, getGatewayRegistryPDA, getObserverLookupPDA, getPrimaryNamePDA, getPrimaryNameRequestPDA, getReservedNamePDA, getReturnedNamePDA, getVaultPDA, } from './pda.js';
 const addressDecoder = getAddressDecoder();
@@ -189,6 +180,42 @@ export class SolanaARIOReadable {
             data: Buffer.from(entry.account.data[0], 'base64'),
         }));
     }
+    /**
+     * Batch-fetch the `cumulative_reward_per_token` accumulator for every gateway
+     * in `operatorAddresses`. Returns a Map keyed by base58 operator address.
+     * Used by the delegate readers below to compute the live delegation balance
+     * without an on-chain settlement call (see {@link computeLiveDelegationBalance}
+     * and `INVARIANTS.md` in the contracts repo). Missing gateways are silently
+     * skipped — callers fall back to the stale `Delegation.amount` for those
+     * (the accumulator delta is 0 and live == stored anyway when the gateway
+     * has no rewards to distribute).
+     */
+    async getGatewayAccumulators(operatorAddresses) {
+        const unique = Array.from(new Set(operatorAddresses));
+        if (unique.length === 0)
+            return new Map();
+        const pdas = await Promise.all(unique.map(async (op) => (await getGatewayPDA(address(op), this.garProgram))[0]));
+        const accounts = await fetchEncodedAccounts(this.rpc, pdas, {
+            commitment: this.commitment,
+        });
+        const out = new Map();
+        for (let i = 0; i < accounts.length; i++) {
+            const acct = accounts[i];
+            if (!acct.exists)
+                continue;
+            try {
+                // Internal variant: surfaces the u128 accumulator that the public
+                // `deserializeGateway` deliberately drops (BigInt is not
+                // JSON-serializable and would leak through getGateway).
+                const gw = deserializeGatewayWithAccumulator(Buffer.from(acct.data));
+                out.set(unique[i], gw.cumulativeRewardPerToken);
+            }
+            catch {
+                // Skip malformed; the caller will fall back to the raw delegation amount.
+            }
+        }
+        return out;
+    }
     /** Read the gateway registry and return addresses in registry index order */
     async getRegistryGatewayAddresses() {
         const [registryPda] = await getGatewayRegistryPDA(this.garProgram);
@@ -490,13 +517,22 @@ export class SolanaARIOReadable {
                 memcmp: { offset: 8n, bytes: gateway, encoding: 'base58' },
             },
         ]);
+        // Fetch this gateway's current reward accumulator so we can return live
+        // balances (raw `Delegation.amount` is stale between settlements — see
+        // INVARIANTS.md and `computeLiveDelegationBalance`).
+        const accumulators = await this.getGatewayAccumulators([gateway]);
+        const cumulative = accumulators.get(gateway) ?? 0n;
         const items = [];
         for (const { data } of accounts) {
             try {
                 const del = deserializeDelegation(data);
                 items.push({
                     address: del.delegator,
-                    delegatedStake: del.delegatedStake,
+                    delegatedStake: computeLiveDelegationBalance({
+                        delegatedStake: del.delegatedStake,
+                        rewardDebt: del.rewardDebt,
+                        cumulativeRewardPerToken: cumulative,
+                    }),
                     startTimestamp: secToMs(del.startTimestamp),
                 });
             }
@@ -538,22 +574,32 @@ export class SolanaARIOReadable {
                 },
             },
         ]);
-        const items = [];
+        const decoded = [];
         for (const { pubkey, data } of accounts) {
             try {
-                const del = deserializeDelegation(data);
-                items.push({
-                    type: 'stake',
-                    gatewayAddress: del.gateway,
-                    delegationId: pubkey,
-                    startTimestamp: secToMs(del.startTimestamp),
-                    balance: del.delegatedStake,
+                decoded.push({
+                    pubkey: pubkey,
+                    del: deserializeDelegation(data),
                 });
             }
             catch {
                 // Skip malformed
             }
         }
+        // Batch-fetch each referenced gateway's reward accumulator so we can
+        // return live balances. See INVARIANTS.md and `computeLiveDelegationBalance`.
+        const accumulators = await this.getGatewayAccumulators(decoded.map(({ del }) => del.gateway));
+        const items = decoded.map(({ pubkey, del }) => ({
+            type: 'stake',
+            gatewayAddress: del.gateway,
+            delegationId: pubkey,
+            startTimestamp: secToMs(del.startTimestamp),
+            balance: computeLiveDelegationBalance({
+                delegatedStake: del.delegatedStake,
+                rewardDebt: del.rewardDebt,
+                cumulativeRewardPerToken: accumulators.get(del.gateway) ?? 0n,
+            }),
+        }));
         return paginate(items, params);
     }
     async getAllowedDelegates(params) {
@@ -1300,23 +1346,33 @@ export class SolanaARIOReadable {
     // =========================================
     async getAllDelegates(params) {
         const accounts = await this.getAccountsByDiscriminator(this.garProgram, DELEGATION_DISCRIMINATOR);
-        const items = [];
+        const decoded = [];
         for (const { pubkey, data } of accounts) {
             try {
-                const del = deserializeDelegation(data);
-                items.push({
-                    address: del.delegator,
-                    gatewayAddress: del.gateway,
-                    delegatedStake: del.delegatedStake,
-                    startTimestamp: secToMs(del.startTimestamp),
-                    vaultedStake: 0,
-                    cursorId: pubkey,
+                decoded.push({
+                    pubkey: pubkey,
+                    del: deserializeDelegation(data),
                 });
             }
             catch {
                 // Skip malformed
             }
         }
+        // Batch-fetch each referenced gateway's reward accumulator so we can
+        // return live balances. See INVARIANTS.md and `computeLiveDelegationBalance`.
+        const accumulators = await this.getGatewayAccumulators(decoded.map(({ del }) => del.gateway));
+        const items = decoded.map(({ pubkey, del }) => ({
+            address: del.delegator,
+            gatewayAddress: del.gateway,
+            delegatedStake: computeLiveDelegationBalance({
+                delegatedStake: del.delegatedStake,
+                rewardDebt: del.rewardDebt,
+                cumulativeRewardPerToken: accumulators.get(del.gateway) ?? 0n,
+            }),
+            startTimestamp: secToMs(del.startTimestamp),
+            vaultedStake: 0,
+            cursorId: pubkey,
+        }));
         return paginate(items, params);
     }
     async getAllGatewayVaults(params) {

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';