@ar.io/sdk 4.0.0-solana.26 → 4.0.0-solana.28

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

@@ -290,9 +290,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;
@@ -300,6 +314,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,
@@ -308,9 +338,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
     // =========================================
@@ -1723,8 +1775,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);
@@ -1733,7 +1798,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 });
                 }
             }
@@ -1743,6 +1808,14 @@ 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

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

@@ -69,6 +69,36 @@ function withRemainingAccounts(ix, remaining) {
     ];
     return { ...ix, accounts };
 }
+/**
+ * Pick the swapped-gateway operator that `finalize_gone` needs as a writable
+ * `remaining_accounts[0]`.
+ *
+ * `finalize_gone` reclaims a gateway's slot from the compact GatewayRegistry by
+ * moving the LAST active slot into it and rewriting that swapped gateway's
+ * stored `registry_index`. When the finalized gateway is NOT already the last
+ * slot, the on-chain handler requires the swapped Gateway PDA (writable) at
+ * `remaining_accounts[0]`; when it IS the last slot, no swap occurs and no
+ * extra account is needed. See
+ * `programs/ario-gar/src/instructions/gateway.rs::finalize_gone`.
+ *
+ * `registryAddresses` MUST be the active registry operator addresses in slot
+ * order (`getRegistryGatewayAddresses()` — length === on-chain
+ * `registry.count`), so `registryAddresses[length - 1]` is exactly the
+ * `registry.gateways[count - 1].address` the on-chain swap reads.
+ *
+ * @returns the swapped gateway's operator address, or `null` when the finalized
+ *   gateway already occupies the last slot.
+ * @throws if `registryIndex` is outside the active registry count (mirrors the
+ *   on-chain `index < registry.count` guard, surfacing a stale index early).
+ */
+export function selectFinalizeGoneSwapOperator(registryIndex, registryAddresses) {
+    if (registryIndex < 0 || registryIndex >= registryAddresses.length) {
+        throw new Error(`finalizeGone: registry index ${registryIndex} is outside the active ` +
+            `registry count ${registryAddresses.length}`);
+    }
+    const lastIndex = registryAddresses.length - 1;
+    return registryIndex === lastIndex ? null : registryAddresses[lastIndex];
+}
 /**
  * Split a primary name into its undername + base parts using the same rule
  * as the on-chain `splitn(2, '_')` in `programs/ario-core/src/instructions/primary_name.rs`:
@@ -2627,11 +2657,34 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
     async finalizeGone(params, _options) {
         const gatewayAddr = address(params.gateway);
         const [gatewayPda] = await getGatewayPDA(gatewayAddr, this.garProgram);
+        // `finalize_gone` reclaims this gateway's compact-registry slot by
+        // swap-removing the LAST active slot into it. When this gateway is not the
+        // last slot, the on-chain handler rewrites the swapped gateway's stored
+        // registry_index and therefore requires that swapped Gateway PDA as
+        // writable remaining_accounts[0]
+        // (programs/ario-gar/src/instructions/gateway.rs::finalize_gone). Read the
+        // gateway's slot index + the active registry to decide.
+        const gatewayAccount = await fetchEncodedAccount(this.rpc, gatewayPda, {
+            commitment: this.commitment,
+        });
+        if (!gatewayAccount.exists) {
+            throw new Error(`Gateway not found for operator ${params.gateway}`);
+        }
+        const gateway = getGatewayDecoder().decode(gatewayAccount.data);
+        const registryAddresses = await this.getRegistryGatewayAddresses();
+        const swappedOperator = selectFinalizeGoneSwapOperator(gateway.registryIndex.index, registryAddresses);
         const ix = await getFinalizeGoneInstructionAsync(await this.withGarDefaults({
             gateway: gatewayPda,
             caller: this.signer,
         }), { programAddress: this.garProgram });
-        const sig = await this.sendTransaction([ix]);
+        let finalIx = ix;
+        if (swappedOperator !== null) {
+            const [swappedGatewayPda] = await getGatewayPDA(address(swappedOperator), this.garProgram);
+            finalIx = withRemainingAccounts(ix, [
+                { address: swappedGatewayPda, role: AccountRole.WRITABLE },
+            ]);
+        }
+        const sig = await this.sendTransaction([finalIx]);
         return { id: sig };
     }
     /**

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

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

@@ -83,6 +83,15 @@ export declare class SolanaARIOReadable {
         LastDistributedEpochIndex: number;
     }>;
     getTokenSupply(): Promise<TokenSupplyData>;
+    /**
+     * 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`).
+     */
+    private getTokenAccountAmount;
     /**
      * Resolve the ARIO SPL mint address from the on-chain `ArioConfig`.
      *
@@ -302,13 +311,35 @@ export declare class SolanaARIOReadable {
         failedConsecutive: number;
     }>>;
     /**
-     * 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.
      */
     getGoneGateways(): Promise<Array<{
         pubkey: Address;
         operator: Address;
     }>>;
+    /**
+     * 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.
+     */
+    getLeavingGateways(): Promise<Array<{
+        pubkey: Address;
+        operator: Address;
+    }>>;
     /**
      * Enumerate Joined Gateway PDAs whose delegation has been DISABLED
      * (`allow_delegated_staking == false`) yet still hold delegated stake

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

@@ -26,6 +26,29 @@ import type { mARIOToken } from '../types/token.js';
 import { deserializeEpochSettingsFull } from './deserialize.js';
 import { SolanaARIOReadable } from './io-readable.js';
 import type { SolanaRpcSubscriptions, SolanaSigner, SolanaWriteConfig } from './types.js';
+/**
+ * Pick the swapped-gateway operator that `finalize_gone` needs as a writable
+ * `remaining_accounts[0]`.
+ *
+ * `finalize_gone` reclaims a gateway's slot from the compact GatewayRegistry by
+ * moving the LAST active slot into it and rewriting that swapped gateway's
+ * stored `registry_index`. When the finalized gateway is NOT already the last
+ * slot, the on-chain handler requires the swapped Gateway PDA (writable) at
+ * `remaining_accounts[0]`; when it IS the last slot, no swap occurs and no
+ * extra account is needed. See
+ * `programs/ario-gar/src/instructions/gateway.rs::finalize_gone`.
+ *
+ * `registryAddresses` MUST be the active registry operator addresses in slot
+ * order (`getRegistryGatewayAddresses()` — length === on-chain
+ * `registry.count`), so `registryAddresses[length - 1]` is exactly the
+ * `registry.gateways[count - 1].address` the on-chain swap reads.
+ *
+ * @returns the swapped gateway's operator address, or `null` when the finalized
+ *   gateway already occupies the last slot.
+ * @throws if `registryIndex` is outside the active registry count (mirrors the
+ *   on-chain `index < registry.count` guard, surfacing a stale index early).
+ */
+export declare function selectFinalizeGoneSwapOperator(registryIndex: number, registryAddresses: string[]): string | null;
 /**
  * Split a primary name into its undername + base parts using the same rule
  * as the on-chain `splitn(2, '_')` in `programs/ario-core/src/instructions/primary_name.rs`:

package/lib/types/types/io.d.ts

@@ -144,6 +144,16 @@ export type EligibleDistribution = {
     gatewayAddress: WalletAddress;
     cursorId: string;
 };
+/**
+ * The six ARIO supply buckets. They are mutually exclusive and sum to `total`:
+ *   circulating + locked + staked + delegated + withdrawn + protocolBalance === total
+ *
+ * `protocolBalance` is the protocol **reward reserve** (the pool epoch rewards
+ * are paid from) — on Solana this is the live balance of the protocol token
+ * account, matching AO's `protocolBalance` (the qNvAoz0 reserve). It is NOT the
+ * on-chain `ArioConfig.protocol_balance` accounting field, which folds the
+ * staking buckets in and would double-count.
+ */
 export type TokenSupplyData = {
     total: number;
     circulating: number;

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

package/package.json

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