@ar.io/sdk 4.0.0-solana.27 → 4.0.0-solana.29

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
     // =========================================

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

@@ -2420,16 +2420,26 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         // currentIndex is the NEXT epoch to create; the live one is currentIndex-1.
         const targetEpochIndex = currentIndex > 0 ? currentIndex - 1 : 0;
         const nextEpochStart = settings.genesisTimestamp + currentIndex * settings.epochDuration;
-        // Bootstrap: no epochs yet.
-        if (currentIndex === 0) {
+        const epoch = await this.getEpochRaw(targetEpochIndex);
+        // Cold start: the live epoch (targetEpochIndex) doesn't exist yet. Two cases,
+        // handled identically — `create_epoch` always creates epoch[currentIndex] and
+        // then increments the counter, so the NEXT crank finds it live at currentIndex-1:
+        //   1. Genesis: currentIndex === 0 → create epoch 0.
+        //   2. AO→Solana continuity cold start: `admin_set_current_epoch_index` jumped
+        //      currentIndex to e.g. 454 with NO prior epochs on-chain (the AO-side
+        //      epochs were never created on Solana). targetEpochIndex (453) points at
+        //      an epoch that will never exist, so the old `currentIndex === 0`-only
+        //      bootstrap deadlocked here ('waiting_for_epoch' forever). Create
+        //      epoch[currentIndex] (454) directly — its start was re-anchored to ≈now.
+        if (!epoch) {
             if (now < nextEpochStart)
-                return { action: 'idle', reason: 'waiting_for_genesis' };
+                return {
+                    action: 'idle',
+                    reason: currentIndex === 0 ? 'waiting_for_genesis' : 'waiting_for_epoch',
+                };
             const { id } = await this.createEpoch();
-            return { action: 'create', epochIndex: 0, txId: id };
+            return { action: 'create', epochIndex: currentIndex, txId: id };
         }
-        const epoch = await this.getEpochRaw(targetEpochIndex);
-        if (!epoch)
-            return { action: 'idle', reason: 'waiting_for_epoch' };
         // Tally (batched). activeGatewayCount===0 still needs one tx to flip the flag.
         if (epoch.weightsTallied === 0) {
             const gatewayAccounts = epoch.activeGatewayCount > 0

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

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`.
      *

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

package/package.json

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