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

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

@@ -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/io-readable.js

@@ -14,7 +14,8 @@ 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 { 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();
@@ -179,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);
@@ -480,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),
                 });
             }
@@ -528,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) {
@@ -1290,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/version.js

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

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

@@ -14,6 +14,12 @@ export declare const MPL_CORE_PROGRAM_ID: Address;
 export declare const TOKEN_DECIMALS = 6;
 export declare const ONE_TOKEN = 1000000;
 export declare const RATE_SCALE = 1000000;
+/**
+ * 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 declare const REWARD_PRECISION = 1000000000000000000n;
 export declare const ARIO_CONFIG_SEED: Buffer<ArrayBuffer>;
 export declare const VAULT_SEED: Buffer<ArrayBuffer>;
 export declare const VAULT_COUNTER_SEED: Buffer<ArrayBuffer>;

package/lib/types/solana/delegation-math.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 declare function computeLiveDelegationBalance({ delegatedStake, rewardDebt, cumulativeRewardPerToken, }: {
+    delegatedStake: number;
+    rewardDebt: bigint;
+    cumulativeRewardPerToken: bigint;
+}): number;

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

@@ -81,10 +81,31 @@ declare class BorshWriter {
     getOffset(): number;
 }
 /**
- * Deserialize a Gateway account from raw bytes.
+ * 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.
+ *
  * PDA: ["gateway", operator_pubkey] in ario-gar program.
+ */
+export declare function deserializeGatewayWithAccumulator(data: Buffer): AoGateway & {
+    operator: string;
+    cumulativeRewardPerToken: bigint;
+};
+/**
+ * Deserialize a Gateway account from raw bytes.
  *
- * Returns the SDK-compatible AoGateway type.
+ * 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 declare function deserializeGateway(data: Buffer): AoGateway & {
     operator: string;
@@ -119,8 +140,19 @@ export declare function deserializeVault(data: Buffer): AoVaultData & {
 export type DeserializedDelegation = {
     gateway: string;
     delegator: string;
+    /**
+     * Last-settled principal (raw `Delegation.amount` from on-chain state).
+     * This value is stale between epochs — see `INVARIANTS.md` in the contracts
+     * repo. Use `computeLiveDelegationBalance` (with the gateway's current
+     * `cumulativeRewardPerToken`) to get the actual current balance.
+     */
     delegatedStake: number;
     startTimestamp: number;
+    /**
+     * Snapshot of `gateway.cumulative_reward_per_token` at the last settlement.
+     * Required input to `computeLiveDelegationBalance`.
+     */
+    rewardDebt: bigint;
 };
 /**
  * Deserialize a Delegation account from raw bytes.

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

@@ -52,6 +52,17 @@ export declare class SolanaARIOReadable {
      * keep the IDL-derived bytes as the single source of truth).
      */
     private getAccountsByDiscriminator;
+    /**
+     * 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).
+     */
+    protected getGatewayAccumulators(operatorAddresses: string[]): Promise<Map<string, bigint>>;
     /** Read the gateway registry and return addresses in registry index order */
     protected getRegistryGatewayAddresses(): Promise<string[]>;
     getInfo(): Promise<{

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

package/package.json

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