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

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

@@ -1,5 +1,20 @@
 /**
- * Solana implementation of the AoARIORead interface.
+ * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Solana implementation of the ARIORead interface.
  *
  * Reads AR.IO protocol state directly from Solana PDAs using RPC,
  * returning the same types that the AO implementation returns.
@@ -14,10 +29,11 @@ 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 { computeLiveDelegationBalance } from './delegation-math.js';
+import { computeLiveDelegationBalance, selectCompoundableDelegations, } 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';
+import { withRetry } from './retry.js';
 const addressDecoder = getAddressDecoder();
 /** All-zero address — equivalent of web3.js `PublicKey.default`. */
 const DEFAULT_ADDRESS = address('11111111111111111111111111111111');
@@ -71,7 +87,7 @@ function toMsTimestamps(obj) {
 /**
  * Drop the SDK-internal extras (`name`, `owner`) and the `processId` re-key
  * that `deserializeArnsRecord` adds, projecting back to the cross-backend
- * `AoArNSNameDataWithName` shape consumers expect.
+ * `ArNSNameDataWithName` shape consumers expect.
  *
  * Timestamps are converted from on-chain seconds to JS milliseconds here
  * (see `toMsTimestamps` above for rationale).
@@ -89,6 +105,12 @@ function arnsRecordToWithName(record) {
             : {}),
     };
 }
+/**
+ * TTL for {@link SolanaARIOReadable.getCachedAccount}. DemandFactor / config
+ * accounts change on the order of epochs, so a few seconds of staleness is a
+ * safe trade for collapsing burst reads (e.g. per-row cost lookups).
+ */
+const CONFIG_CACHE_TTL_MS = 30_000;
 function paginate(items, params) {
     const limit = params?.limit ?? 100;
     const startIdx = params?.cursor ? parseInt(params.cursor, 10) : 0;
@@ -130,6 +152,11 @@ export class SolanaARIOReadable {
     // Memoized ARIO mint address (read once from ArioConfig.mint and reused
     // for every SPL-ATA derivation in getBalance/getBalances).
     _arioMint;
+    // Short-TTL cache for slow-changing config-ish accounts (DemandFactor,
+    // ArnsConfig, etc.). Collapses the many identical reads a UI fires in a
+    // burst — e.g. the returned-names page running `getCostDetails` per row,
+    // each re-reading the same DemandFactor PDA — into a single network call.
+    _accountCache = new Map();
     constructor(config) {
         this.rpc = config.rpc;
         this.commitment = config.commitment ?? 'confirmed';
@@ -141,9 +168,27 @@ export class SolanaARIOReadable {
     }
     /** Helper to fetch an encoded account (kit's replacement for Connection.getAccountInfo). */
     async getAccount(pda) {
-        return fetchEncodedAccount(this.rpc, pda, {
+        return withRetry(() => fetchEncodedAccount(this.rpc, pda, {
             commitment: this.commitment,
-        });
+        }));
+    }
+    /**
+     * Like {@link getAccount} but caches the result per-PDA for `ttlMs`. Use only
+     * for accounts that change slowly (DemandFactor, ArnsConfig) where a few
+     * seconds of staleness is acceptable in exchange for collapsing repeated
+     * reads. A successful fetch is cached; misses (`exists: false`) are not.
+     */
+    async getCachedAccount(pda, ttlMs = CONFIG_CACHE_TTL_MS) {
+        const key = String(pda);
+        const now = Date.now();
+        const hit = this._accountCache.get(key);
+        if (hit && hit.expiresAt > now)
+            return hit.account;
+        const account = await this.getAccount(pda);
+        if (account.exists) {
+            this._accountCache.set(key, { account, expiresAt: now + ttlMs });
+        }
+        return account;
     }
     /**
      * Helper for `getProgramAccounts` with a discriminator memcmp filter.
@@ -168,7 +213,7 @@ export class SolanaARIOReadable {
         // when called without `withContext: true`. With `encoding: 'base64'`, each
         // account's `data` is a `[base64, 'base64']` tuple. We bypass kit's strict
         // generic overload typing here with a cast — the runtime shape is stable.
-        const result = (await this.rpc
+        const result = await withRetry(() => this.rpc
             .getProgramAccounts(programId, {
             commitment: this.commitment,
             encoding: 'base64',
@@ -195,9 +240,9 @@ export class SolanaARIOReadable {
         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, {
+        const accounts = await withRetry(() => fetchEncodedAccounts(this.rpc, pdas, {
             commitment: this.commitment,
-        });
+        }));
         const out = new Map();
         for (let i = 0; i < accounts.length; i++) {
             const acct = accounts[i];
@@ -289,9 +334,23 @@ export class SolanaARIOReadable {
         let staked = 0;
         let delegated = 0;
         let withdrawn = 0;
+        // `protocolBalance` is the REWARD RESERVE: the live balance of the protocol
+        // token account the epoch cranker emits from (ario-gar `distribute_epoch`
+        // reads `protocol_token_account.amount`). This matches AO's `protocolBalance`
+        // semantics (the qNvAoz0 reserve) and makes the six buckets sum to `total`:
+        //   circulating + locked + staked + delegated + withdrawn + protocolBalance == total
+        //
+        // It is deliberately NOT `ArioConfig.protocol_balance`, which is a *folded*
+        // accounting field (= reserve + staked + delegated + withdrawn) and so
+        // double-counts the staking buckets — surfacing it as "protocol balance"
+        // over-reports the reward reserve by tens of millions of ARIO. We fall back
+        // to the folded value only when GatewaySettings or the token account can't
+        // be read (e.g. pre-init).
+        let protocolBalance = config.protocolBalance;
         if (garSettingsAccount.exists) {
+            const garData = Buffer.from(garSettingsAccount.data);
             try {
-                const counters = deserializeGarSupplyCounters(Buffer.from(garSettingsAccount.data));
+                const counters = deserializeGarSupplyCounters(garData);
                 staked = counters.totalStaked;
                 delegated = counters.totalDelegated;
                 withdrawn = counters.totalWithdrawn;
@@ -299,6 +358,22 @@ export class SolanaARIOReadable {
             catch {
                 // Old-layout account without supply counters — fall back to 0
             }
+            // The protocol token account is pinned in GatewaySettings at offset 189
+            // (see ario-gar state/mod.rs::GatewaySettings: 8 disc + 32 authority +
+            // 32 mint + 6×8 economic params + 4 max_delegates + 1 migration_active +
+            // 32 migration_authority + 32 stake_token_account = 189; the pubkey runs
+            // [189, 221)). Read its live SPL balance as the reward reserve.
+            if (garData.length >= 221) {
+                try {
+                    const protocolTokenAccount = addressDecoder.decode(garData.subarray(189, 221));
+                    const reserve = await this.getTokenAccountAmount(protocolTokenAccount);
+                    if (reserve !== null)
+                        protocolBalance = reserve;
+                }
+                catch {
+                    // Couldn't read the reserve — keep the folded fallback.
+                }
+            }
         }
         return {
             total: config.totalSupply,
@@ -307,9 +382,31 @@ export class SolanaARIOReadable {
             staked,
             delegated,
             withdrawn,
-            protocolBalance: config.protocolBalance,
+            protocolBalance,
         };
     }
+    /**
+     * Read the `amount` (in mARIO) of an SPL token account directly by address.
+     * Returns `null` if the account doesn't exist or is too small to be a token
+     * account, so callers can distinguish "absent" from a real zero balance.
+     *
+     * Uses a portable little-endian u64 decode — some browser bundlers strip the
+     * BigInt readers from the `buffer` shim's prototype (see `getBalance`).
+     */
+    async getTokenAccountAmount(tokenAccount) {
+        const account = await this.getAccount(tokenAccount);
+        if (!account.exists)
+            return null;
+        const data = account.data;
+        if (data.length < 72)
+            return null;
+        let amount = 0n;
+        for (let i = 7; i >= 0; i--) {
+            amount = (amount << 8n) | BigInt(data[64 + i]);
+        }
+        // ARIO supply caps at 1B * 1e6 mARIO ≈ 2^50, well under MAX_SAFE_INTEGER.
+        return Number(amount);
+    }
     // =========================================
     // Balance read methods
     // =========================================
@@ -387,7 +484,7 @@ export class SolanaARIOReadable {
                 },
             },
         ];
-        const result = (await this.rpc
+        const result = await withRetry(() => this.rpc
             .getProgramAccounts(TOKEN_PROGRAM_ADDRESS, {
             commitment: this.commitment,
             encoding: 'base64',
@@ -562,22 +659,43 @@ export class SolanaARIOReadable {
         }
         return paginate(items, params);
     }
+    /**
+     * Returns every delegation a wallet currently has, covering both halves
+     * of the `Delegation` union:
+     *
+     * - `type: 'stake'` — active `Delegation` PDAs (filtered by delegator at
+     *   memcmp offset 40 = 8 disc + 32 gateway).
+     * - `type: 'vault'` — pending delegate-stake withdrawals: `Withdrawal`
+     *   PDAs filtered by owner at memcmp offset 8 (= 8 disc), then narrowed
+     *   client-side to `isDelegate: true`. Operator-stake withdrawals are
+     *   excluded — those are surfaced via `getWithdrawals` /
+     *   `getGatewayVaults`.
+     *
+     * Both queries run in parallel; consumers see a single merged result
+     * matching the cross-backend interface contract.
+     */
     async getDelegations(params) {
-        const delegator = address(params.address);
-        // Filter delegations by delegator pubkey at offset 40 (8 disc + 32 gateway)
-        const accounts = await this.getAccountsByDiscriminator(this.garProgram, DELEGATION_DISCRIMINATOR, [
-            {
-                memcmp: {
-                    offset: 40n,
-                    bytes: delegator,
-                    encoding: 'base58',
+        const owner = address(params.address);
+        const [delegationAccounts, withdrawalAccounts] = await Promise.all([
+            // Active delegations — `Delegation` PDA layout:
+            // disc(8) + gateway(32) + delegator(32) + ... — delegator at offset 40.
+            this.getAccountsByDiscriminator(this.garProgram, DELEGATION_DISCRIMINATOR, [
+                {
+                    memcmp: { offset: 40n, bytes: owner, encoding: 'base58' },
                 },
-            },
+            ]),
+            // Pending vault delegations — `Withdrawal` PDA layout:
+            // disc(8) + owner(32) + withdrawal_id(8) + gateway(32) + ... — owner at offset 8.
+            this.getAccountsByDiscriminator(this.garProgram, WITHDRAWAL_DISCRIMINATOR, [
+                {
+                    memcmp: { offset: 8n, bytes: owner, encoding: 'base58' },
+                },
+            ]),
         ]);
-        const decoded = [];
-        for (const { pubkey, data } of accounts) {
+        const decodedDelegations = [];
+        for (const { pubkey, data } of delegationAccounts) {
             try {
-                decoded.push({
+                decodedDelegations.push({
                     pubkey: pubkey,
                     del: deserializeDelegation(data),
                 });
@@ -588,8 +706,8 @@ export class SolanaARIOReadable {
         }
         // 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 }) => ({
+        const accumulators = await this.getGatewayAccumulators(decodedDelegations.map(({ del }) => del.gateway));
+        const stakeItems = decodedDelegations.map(({ pubkey, del }) => ({
             type: 'stake',
             gatewayAddress: del.gateway,
             delegationId: pubkey,
@@ -600,7 +718,30 @@ export class SolanaARIOReadable {
                 cumulativeRewardPerToken: accumulators.get(del.gateway) ?? 0n,
             }),
         }));
-        return paginate(items, params);
+        const vaultItems = [];
+        for (const { pubkey, data } of withdrawalAccounts) {
+            try {
+                const w = deserializeWithdrawal(data);
+                // Delegate-stake decreases only. Operator-stake withdrawals (the
+                // operator's own decreaseOperatorStake calls) belong on
+                // `getWithdrawals` / `getGatewayVaults`, not `getDelegations`.
+                if (!w.isDelegate)
+                    continue;
+                vaultItems.push({
+                    type: 'vault',
+                    gatewayAddress: w.gateway,
+                    delegationId: pubkey,
+                    vaultId: w.vaultId,
+                    balance: w.balance,
+                    startTimestamp: secToMs(w.startTimestamp),
+                    endTimestamp: secToMs(w.endTimestamp),
+                });
+            }
+            catch {
+                // Skip malformed
+            }
+        }
+        return paginate([...stakeItems, ...vaultItems], params);
     }
     async getAllowedDelegates(params) {
         return this.getGatewayDelegateAllowList(params);
@@ -633,6 +774,46 @@ export class SolanaARIOReadable {
         }
         return paginate(items, params);
     }
+    /**
+     * Return every pending stake withdrawal owned by `address` — operator-stake
+     * decreases (`isDelegate: false`) and delegate-stake decreases
+     * (`isDelegate: true`) in one paginated result. A withdrawal is claimable
+     * when `Date.now() >= endTimestamp`; release the funds via
+     * `claimWithdrawal({ withdrawalId: item.vaultId })`.
+     *
+     * Solana-only: AO releases withdrawals automatically at maturity and has no
+     * equivalent per-owner read; the AO backend throws.
+     */
+    async getWithdrawals(params) {
+        const owner = address(params.address);
+        // Withdrawal layout: disc(8) + owner(32) + withdrawal_id(8) + gateway(32).
+        // Filter by owner at offset 8 — returns both operator-stake (isDelegate=false)
+        // and delegate-stake (isDelegate=true) withdrawals for this wallet.
+        const accounts = await this.getAccountsByDiscriminator(this.garProgram, WITHDRAWAL_DISCRIMINATOR, [
+            {
+                memcmp: { offset: 8n, bytes: owner, encoding: 'base58' },
+            },
+        ]);
+        const items = [];
+        for (const { pubkey, data } of accounts) {
+            try {
+                const w = deserializeWithdrawal(data);
+                items.push({
+                    cursorId: pubkey,
+                    vaultId: w.vaultId,
+                    balance: w.balance,
+                    startTimestamp: secToMs(w.startTimestamp),
+                    endTimestamp: secToMs(w.endTimestamp),
+                    gatewayAddress: w.gateway,
+                    isDelegate: w.isDelegate,
+                });
+            }
+            catch {
+                // Skip malformed
+            }
+        }
+        return paginate(items, params);
+    }
     // =========================================
     // ArNS read methods
     // =========================================
@@ -679,7 +860,7 @@ export class SolanaARIOReadable {
      * mints against ≈ 4k records, and rises as the registry grows).
      *
      * The shape mirrors `getArNSRecord` / `getArNSRecords` — same
-     * `AoArNSNameDataWithName` items, no pagination wrapper. Callers
+     * `ArNSNameDataWithName` items, no pagination wrapper. Callers
      * that want pagination should drive it via `getArNSRecords({
      * filters: { processId: mints } })` instead.
      */
@@ -807,7 +988,11 @@ export class SolanaARIOReadable {
     }
     async getArNSReturnedName({ name, }) {
         const [pda] = await getReturnedNamePDA(name, this.arnsProgram);
-        const account = await this.getAccount(pda);
+        // A ReturnedName account is immutable once created (its premium is derived
+        // client-side from the static start/end timestamps), so cache the read.
+        // The returned-names price table reads each name's PDA twice (lease +
+        // permabuy) and `getTokenCost` reads it again — all share one fetch.
+        const account = await this.getCachedAccount(pda);
         if (!account.exists) {
             throw new Error(`Returned name not found: ${name}`);
         }
@@ -1027,6 +1212,36 @@ export class SolanaARIOReadable {
         }
         return { failureSummaries, reports };
     }
+    /**
+     * Observer pubkeys that have an OPEN Observation PDA for `epochIndex`. Lean —
+     * reads only the Observation accounts (no gateway-registry decode like
+     * {@link getObservations}). Used by the crank to close observations before
+     * `close_epoch`, whose `observations_closed == observations_submitted`
+     * precondition would otherwise wedge epoch progression.
+     */
+    async getEpochObservers(epochIndex) {
+        const epochIndexBuf = Buffer.alloc(8);
+        epochIndexBuf.writeBigUInt64LE(BigInt(epochIndex));
+        const accounts = await this.getAccountsByDiscriminator(this.garProgram, OBSERVATION_DISCRIMINATOR, [
+            {
+                memcmp: {
+                    offset: 8n,
+                    bytes: bs58.encode(epochIndexBuf),
+                    encoding: 'base58',
+                },
+            },
+        ]);
+        const observers = [];
+        for (const { data } of accounts) {
+            try {
+                observers.push(address(deserializeObservation(data).observer));
+            }
+            catch {
+                // skip malformed
+            }
+        }
+        return observers;
+    }
     async getDistributions(epoch) {
         const epochIndex = await this.resolveEpochIndex(epoch);
         const epochData = await this.fetchEpoch(epochIndex);
@@ -1087,7 +1302,7 @@ export class SolanaARIOReadable {
      */
     async getTokenCost(params) {
         const [dfPda] = await getDemandFactorPDA(this.arnsProgram);
-        const dfAccount = await this.getAccount(dfPda);
+        const dfAccount = await this.getCachedAccount(dfPda);
         if (!dfAccount.exists)
             throw new Error('DemandFactor account not found');
         const df = deserializeDemandFactor(Buffer.from(dfAccount.data));
@@ -1141,6 +1356,11 @@ export class SolanaARIOReadable {
                 cost = (bf * demandFactorRaw * annualPct * years) / scale / scale;
                 break;
             }
+            // A Primary-Name-Request is priced identically to a single
+            // Increase-Undername-Limit operation against the same name: it uses the
+            // name-length-indexed base fee (`bf`) and a quantity of 1. Fall through
+            // to share that logic rather than duplicating it.
+            case 'Primary-Name-Request':
             case 'Increase-Undername-Limit': {
                 const qty = BigInt(params.quantity ?? 1);
                 let isPermabuy = false;
@@ -1160,13 +1380,6 @@ export class SolanaARIOReadable {
                 cost = permabuyCost;
                 break;
             }
-            case 'Primary-Name-Request': {
-                const primaryBaseFee = BigInt(df.fees[50]);
-                const annualPct = 200000n;
-                const yearFactor = scale + annualPct;
-                cost = (primaryBaseFee * demandFactorRaw * yearFactor) / scale / scale;
-                break;
-            }
             default:
                 throw new Error(`Unknown intent: ${params.intent}`);
         }
@@ -1177,14 +1390,35 @@ export class SolanaARIOReadable {
         const discounts = [];
         if (params.fromAddress) {
             try {
-                const gw = await this.getGateway({ address: params.fromAddress });
-                if (gw.status === 'joined') {
-                    const discountAmount = Math.floor((tokenCost * 200_000) / RATE_SCALE);
-                    discounts.push({
-                        name: 'Gateway Operator',
-                        discountTotal: discountAmount,
-                        multiplier: 0.8,
-                    });
+                // Operator-discount check. Read the gateway PDA through the short-TTL
+                // cache (NOT public `getGateway`, which stays fresh for gateway pages):
+                // a price table calls `getCostDetails` many times for the SAME
+                // `fromAddress`, so this collapses N redundant gateway reads to one.
+                const [gwPda] = await getGatewayPDA(address(params.fromAddress), this.garProgram);
+                const gwAccount = await this.getCachedAccount(gwPda);
+                if (gwAccount.exists) {
+                    const gw = deserializeGateway(Buffer.from(gwAccount.data));
+                    if (gw.status === 'joined') {
+                        // Match on-chain eligibility from ario-arns pricing.rs
+                        // `try_apply_gateway_discount`:
+                        // 1. Tenure: gateway running >= 180 days (15_552_000 seconds)
+                        const GATEWAY_DISCOUNT_MIN_TENURE_S = 15_552_000;
+                        const nowSeconds = Math.floor(Date.now() / 1000);
+                        const timeRunning = nowSeconds - gw.startTimestamp;
+                        // 2. Performance: >= 90% epoch pass rate
+                        const passRate = ((1 + gw.stats.passedEpochCount) /
+                            (1 + gw.stats.totalEpochCount)) *
+                            1_000_000;
+                        if (timeRunning >= GATEWAY_DISCOUNT_MIN_TENURE_S &&
+                            passRate >= 900_000) {
+                            const discountAmount = Math.floor((tokenCost * 200_000) / RATE_SCALE);
+                            discounts.push({
+                                name: 'Gateway Operator',
+                                discountTotal: discountAmount,
+                                multiplier: 0.8,
+                            });
+                        }
+                    }
                 }
             }
             catch {
@@ -1192,14 +1426,106 @@ export class SolanaARIOReadable {
             }
         }
         const totalDiscount = discounts.reduce((sum, d) => sum + d.discountTotal, 0);
+        const finalCost = tokenCost - totalDiscount;
+        // Project Solana state into the public-facing `FundingPlan` shape when
+        // the caller asks about a specific funding source for a specific wallet.
+        // (`fromAddress` is required — we can't enumerate funding sources for
+        // an unknown wallet; without `fundFrom` we don't know what to budget
+        // against.) The internal `funding-plan.ts` `FundingPlan` is a
+        // separate, instruction-building plan — keep them distinct.
+        let fundingPlan;
+        if (params.fromAddress && params.fundFrom !== undefined) {
+            fundingPlan = await this.buildPublicFundingPlan({
+                fromAddress: params.fromAddress,
+                fundFrom: params.fundFrom,
+                cost: finalCost,
+            });
+        }
         return {
-            tokenCost: tokenCost - totalDiscount,
+            tokenCost: finalCost,
             discounts,
+            ...(fundingPlan ? { fundingPlan } : {}),
+        };
+    }
+    /**
+     * Project Solana on-chain state into the cross-backend `FundingPlan`
+     * shape consumed by UI flows like "how short are you on this purchase,
+     * and from which sources?". Always returns the wallet's `balance` and
+     * full per-gateway `stakes` breakdown (active delegations + pending
+     * delegate-stake withdrawals); `shortfall` is computed against the
+     * specific `fundFrom` semantics.
+     *
+     * Note: the internal `src/solana/funding-plan.ts` `FundingPlan` is a
+     * different type — that's the multi-source instruction-building plan
+     * used by `buyRecord({ fundFrom: 'any' })`. The two share a concept but
+     * not a shape; the public type here is what consumer UIs see.
+     */
+    async buildPublicFundingPlan({ fromAddress, fundFrom, cost, }) {
+        // Pull balance + full delegation list (stake + vault) in parallel.
+        // Limit is intentionally large — the public FundingPlan reports the
+        // *entire* per-gateway breakdown, not a pagination window.
+        const [balance, delegations] = await Promise.all([
+            this.getBalance({ address: fromAddress }),
+            this.getDelegations({ address: fromAddress, limit: 10_000 }),
+        ]);
+        const stakes = {};
+        for (const d of delegations.items) {
+            const gateway = d.gatewayAddress;
+            if (!stakes[gateway]) {
+                stakes[gateway] = { vaults: [], delegatedStake: 0 };
+            }
+            if (d.type === 'stake') {
+                stakes[gateway].delegatedStake = d.balance;
+            }
+            else {
+                // `Record<string, number>[]` per-vault entries — AO-era shape we
+                // keep for cross-backend compatibility.
+                stakes[gateway].vaults.push({ [d.vaultId]: d.balance });
+            }
+        }
+        const sumDelegated = Object.values(stakes).reduce((sum, g) => sum + g.delegatedStake, 0);
+        const sumVaulted = Object.values(stakes).reduce((sum, g) => sum +
+            g.vaults.reduce((vsum, v) => vsum + Object.values(v).reduce((a, b) => a + b, 0), 0), 0);
+        // Compute shortfall against the *eligible* pool for the chosen
+        // `fundFrom`. `turbo` and `plan` are special: turbo is paid in
+        // off-chain credits (no mARIO shortfall meaningful here), and plan
+        // is caller-supplied (caller did their own arithmetic).
+        let eligible;
+        switch (fundFrom) {
+            case 'balance':
+                eligible = balance;
+                break;
+            case 'stakes':
+                eligible = sumDelegated;
+                break;
+            case 'withdrawal':
+                eligible = sumVaulted;
+                break;
+            case 'any':
+                eligible = balance + sumDelegated + sumVaulted;
+                break;
+            case 'turbo':
+            case 'plan':
+                eligible = Number.MAX_SAFE_INTEGER;
+                break;
+            default: {
+                // Exhaustiveness check — surface a missed FundFrom variant at
+                // type-check time, not at runtime.
+                const _exhaustive = fundFrom;
+                eligible = 0;
+                void _exhaustive;
+            }
+        }
+        return {
+            address: fromAddress,
+            balance,
+            stakes,
+            shortfall: Math.max(0, cost - eligible),
         };
     }
     async getRegistrationFees() {
         const [dfPda] = await getDemandFactorPDA(this.arnsProgram);
-        const account = await this.getAccount(dfPda);
+        const account = await this.getCachedAccount(dfPda);
         if (!account.exists) {
             throw new Error('DemandFactor account not found');
         }
@@ -1222,7 +1548,7 @@ export class SolanaARIOReadable {
     }
     async getDemandFactor() {
         const [pda] = await getDemandFactorPDA(this.arnsProgram);
-        const account = await this.getAccount(pda);
+        const account = await this.getCachedAccount(pda);
         if (!account.exists) {
             throw new Error('DemandFactor account not found');
         }
@@ -1231,7 +1557,7 @@ export class SolanaARIOReadable {
     }
     async getDemandFactorSettings() {
         const [pda] = await getDemandFactorPDA(this.arnsProgram);
-        const account = await this.getAccount(pda);
+        const account = await this.getCachedAccount(pda);
         if (!account.exists) {
             throw new Error('DemandFactor account not found');
         }
@@ -1252,13 +1578,25 @@ export class SolanaARIOReadable {
     // Primary name read methods
     // =========================================
     async getPrimaryName(params) {
+        // On-chain `PrimaryName` stores only {owner, name, set_at}. The ANT mint
+        // that PrimaryName.processId expects lives on the matching ArnsRecord
+        // (looked up by the base name). Both lookup paths below deserialize the
+        // on-chain account and then enrich with the ArnsRecord lookup.
+        const baseNameOf = (n) => {
+            const parts = n.toLowerCase().split('_');
+            return parts.length === 2 ? parts[1] : parts[0];
+        };
+        const enrich = async (pn) => {
+            const rec = await this.getArNSRecord({ name: baseNameOf(pn.name) });
+            return { ...pn, processId: rec.processId };
+        };
         if ('address' in params) {
             const [pda] = await getPrimaryNamePDA(address(params.address), this.coreProgram);
             const account = await this.getAccount(pda);
             if (!account.exists) {
                 throw new Error(`Primary name not found for address ${params.address}`);
             }
-            return deserializePrimaryName(Buffer.from(account.data));
+            return enrich(deserializePrimaryName(Buffer.from(account.data)));
         }
         // Lookup by name — scan all primary name accounts
         const accounts = await this.getAccountsByDiscriminator(this.coreProgram, PRIMARY_NAME_DISCRIMINATOR);
@@ -1266,7 +1604,7 @@ export class SolanaARIOReadable {
             try {
                 const pn = deserializePrimaryName(data);
                 if (pn.name === params.name) {
-                    return pn;
+                    return enrich(pn);
                 }
             }
             catch {
@@ -1298,13 +1636,23 @@ export class SolanaARIOReadable {
     }
     async getPrimaryNames(params) {
         const accounts = await this.getAccountsByDiscriminator(this.coreProgram, PRIMARY_NAME_DISCRIMINATOR);
+        // Enrich each on-chain PrimaryName with its ArnsRecord.processId (the
+        // on-chain account doesn't store it; see deserializePrimaryName).
+        // Records that no longer have a matching ArnsRecord are silently
+        // skipped — same forgiveness the per-name lookup already applies.
+        const baseNameOf = (n) => {
+            const parts = n.toLowerCase().split('_');
+            return parts.length === 2 ? parts[1] : parts[0];
+        };
         const items = [];
         for (const { data } of accounts) {
             try {
-                items.push(deserializePrimaryName(data));
+                const pn = deserializePrimaryName(data);
+                const rec = await this.getArNSRecord({ name: baseNameOf(pn.name) });
+                items.push({ ...pn, processId: rec.processId });
             }
             catch {
-                // Skip malformed
+                // Skip malformed or orphaned (ArnsRecord missing).
             }
         }
         return paginate(items, params);
@@ -1375,6 +1723,56 @@ export class SolanaARIOReadable {
         }));
         return paginate(items, params);
     }
+    /**
+     * Enumerate every delegation that has pending (unsettled) rewards — the work
+     * list for the permissionless `compound_delegation_rewards` crank. Pending is
+     * computed from the gateway's reward-per-share accumulator (mirrors
+     * {@link computeLiveDelegationBalance}); the crank only changes balances, so
+     * rewards already accrue correctly without it.
+     *
+     * Skips delegations whose gateway is `Leaving` (those settle through
+     * `claim_delegate_from_leaving_gateway`, not compounding) and any below
+     * `minPendingRewards` — compounding sub-threshold dust just advances
+     * `reward_debt` for no balance gain. Feed the result, chunked, to
+     * `SolanaARIOWriteable.compoundDelegationRewardsBatch`.
+     */
+    async getDelegationsToCompound(params) {
+        const minPending = params?.minPendingRewards ?? 0;
+        // One scan for gateways → accumulator + status.
+        const gatewayAccounts = await this.getAccountsByDiscriminator(this.garProgram, GATEWAY_DISCRIMINATOR);
+        const gateways = new Map();
+        for (const { data } of gatewayAccounts) {
+            try {
+                const gw = deserializeGatewayWithAccumulator(data);
+                gateways.set(gw.operator, {
+                    cumulativeRewardPerToken: gw.cumulativeRewardPerToken,
+                    status: gw.status,
+                });
+            }
+            catch {
+                // Skip malformed.
+            }
+        }
+        // One scan for delegations; decode then delegate the selection logic to the
+        // pure `selectCompoundableDelegations` (unit-tested in delegation-math).
+        const delegationAccounts = await this.getAccountsByDiscriminator(this.garProgram, DELEGATION_DISCRIMINATOR);
+        const delegations = [];
+        for (const { data } of delegationAccounts) {
+            try {
+                const del = deserializeDelegation(data);
+                delegations.push({
+                    gateway: del.gateway,
+                    delegator: del.delegator,
+                    delegatedStake: del.delegatedStake,
+                    rewardDebt: del.rewardDebt,
+                });
+            }
+            catch {
+                // Skip malformed.
+            }
+        }
+        return selectCompoundableDelegations(delegations, gateways, minPending);
+    }
     async getAllGatewayVaults(params) {
         const accounts = await this.getAccountsByDiscriminator(this.garProgram, WITHDRAWAL_DISCRIMINATOR);
         const items = [];
@@ -1416,7 +1814,7 @@ export class SolanaARIOReadable {
      */
     async getExpiredArnsRecords(now) {
         const [arnsConfigPda] = await getArnsSettingsPDA(this.arnsProgram);
-        const cfgAccount = await this.getAccount(arnsConfigPda);
+        const cfgAccount = await this.getCachedAccount(arnsConfigPda);
         if (!cfgAccount.exists)
             return [];
         const cfg = getArnsConfigDecoder().decode(cfgAccount.data);
@@ -1451,7 +1849,7 @@ export class SolanaARIOReadable {
      */
     async getExpiredReturnedNames(now) {
         const [arnsConfigPda] = await getArnsSettingsPDA(this.arnsProgram);
-        const cfgAccount = await this.getAccount(arnsConfigPda);
+        const cfgAccount = await this.getCachedAccount(arnsConfigPda);
         if (!cfgAccount.exists)
             return [];
         const cfg = getArnsConfigDecoder().decode(cfgAccount.data);
@@ -1524,8 +1922,21 @@ export class SolanaARIOReadable {
         return out;
     }
     /**
-     * Enumerate Gateway PDAs whose `status == Gone` (already left the
-     * network but PDA not yet GC'd). Eligible for `finalizeGone`.
+     * Enumerate Gateway PDAs that are candidates for `finalizeGone` GC — i.e.
+     * those whose `status == Leaving`.
+     *
+     * NOTE: despite the historical name, this returns `Leaving` (not `Gone`)
+     * gateways. `Gone` is NOT a persistent discovery state: the on-chain
+     * `finalize_gone` instruction accepts a `Leaving` gateway, flips it to
+     * `Gone`, and closes the Gateway PDA in the *same* instruction
+     * (programs/ario-gar/src/instructions/gateway.rs::finalize_gone), so a
+     * gateway is never observably parked at `Gone`. Filtering on `Gone` matched
+     * nothing and left Leaving gateways un-GC'd. Time/delegation eligibility is
+     * still enforced on-chain (`finalize_gone` reverts early if the leave window
+     * hasn't elapsed or delegations remain), so over-returning not-yet-eligible
+     * Leaving gateways is safe — the tx just no-ops/reverts.
+     *
+     * @deprecated Prefer {@link getLeavingGateways} — same result, accurate name.
      */
     async getGoneGateways() {
         const accounts = await this.getAccountsByDiscriminator(this.garProgram, GATEWAY_DISCRIMINATOR);
@@ -1534,7 +1945,7 @@ export class SolanaARIOReadable {
         for (const { pubkey, data } of accounts) {
             try {
                 const g = decoder.decode(data);
-                if (g.status === GatewayStatus.Gone) {
+                if (g.status === GatewayStatus.Leaving) {
                     out.push({ pubkey, operator: g.operator });
                 }
             }
@@ -1544,6 +1955,47 @@ export class SolanaARIOReadable {
         }
         return out;
     }
+    /**
+     * Enumerate Gateway PDAs whose `status == Leaving` — the persistent
+     * pre-finalization state that `finalizeGone` GC's. Alias for
+     * {@link getGoneGateways} with a name that matches the on-chain state.
+     */
+    async getLeavingGateways() {
+        return this.getGoneGateways();
+    }
+    /**
+     * Enumerate Joined Gateway PDAs whose delegation has been DISABLED
+     * (`allow_delegated_staking == false`) yet still hold delegated stake
+     * (`total_delegated_stake > 0`) — i.e. delegates that an operator's disable
+     * left stranded (WP §6.3 / Fix #6). Each such gateway's delegates must be
+     * cranked out via
+     * {@link SolanaARIOWriteable.claimDelegateFromDisabledGateway} (enumerate
+     * them with {@link getGatewayDelegates}) before the operator can re-enable
+     * delegation. This is the discovery primitive a cranker uses to sweep them.
+     */
+    async getDisabledGatewaysWithDelegatedStake() {
+        const accounts = await this.getAccountsByDiscriminator(this.garProgram, GATEWAY_DISCRIMINATOR);
+        const decoder = getGatewayDecoder();
+        const out = [];
+        for (const { pubkey, data } of accounts) {
+            try {
+                const g = decoder.decode(data);
+                if (g.status !== GatewayStatus.Joined)
+                    continue;
+                if (!g.settings.allowDelegatedStaking && g.totalDelegatedStake > 0n) {
+                    out.push({
+                        pubkey,
+                        operator: g.operator,
+                        totalDelegatedStake: g.totalDelegatedStake,
+                    });
+                }
+            }
+            catch {
+                // skip malformed
+            }
+        }
+        return out;
+    }
     /**
      * Enumerate Delegation PDAs with `amount == 0`. Eligible for
      * `closeEmptyDelegation` (rent refund to the original delegator).
@@ -1643,7 +2095,7 @@ export class SolanaARIOReadable {
      */
     async getArnsConfigRaw() {
         const [pda] = await getArnsSettingsPDA(this.arnsProgram);
-        const account = await this.getAccount(pda);
+        const account = await this.getCachedAccount(pda);
         if (!account.exists)
             return null;
         const cfg = getArnsConfigDecoder().decode(account.data);