@ar.io/sdk 4.0.0-solana.1 → 4.0.0-solana.10

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

@@ -23,6 +23,7 @@ import { setAntBaseNameCLICommand, setAntRecordCLICommand, setAntUndernameCLICom
 import { buyRecordCLICommand, extendLeaseCLICommand, increaseUndernameLimitCLICommand, requestPrimaryNameCLICommand, setPrimaryNameCLICommand, syncAttributesCLICommand, upgradeRecordCLICommand, } from './commands/arnsPurchaseCommands.js';
 import { escrowCancelCLICommand, escrowClaimArweaveCLICommand, escrowClaimEthereumCLICommand, escrowDepositCLICommand, escrowStatusCLICommand, escrowUpdateRecipientCLICommand, } from './commands/escrowCommands.js';
 import { cancelWithdrawal, decreaseDelegateStake, decreaseOperatorStake, delegateStake, increaseOperatorStake, instantWithdrawal, joinNetwork, leaveNetwork, redelegateStake, saveObservations, updateGatewaySettings, } from './commands/gatewayWriteCommands.js';
+import { closeDrainedWithdrawalCLICommand, closeEmptyDelegationCLICommand, closeExpiredRequestCLICommand, closeObservationCLICommand, finalizeGoneCLICommand, pruneExpiredNamesCLICommand, pruneExpiredReservationCLICommand, pruneGatewayCLICommand, pruneNameToReturnedCLICommand, pruneReturnedNamesCLICommand, releaseVaultCLICommand, } from './commands/pruneCommands.js';
 import { getAllGatewayVaults, getAllowedDelegates, getArNSRecord, getArNSReservedName, getArNSReturnedName, getCostDetails, getDelegations, getEpoch, getGateway, getGatewayDelegates, getGatewayVaults, getPrescribedNames, getPrescribedObservers, getPrimaryName, getTokenCost, getVault, listAllDelegatesCLICommand, listAntsForAddress, listArNSRecords, listArNSRecordsForAddress, listArNSReservedNames, listArNSReturnedNames, listGateways, resolveArNSName, } from './commands/readCommands.js';
 import { createVaultCLICommand, extendVaultCLICommand, increaseVaultCLICommand, revokeVaultCLICommand, transferCLICommand, vaultedTransferCLICommand, } from './commands/transfer.js';
 import { addressAndVaultIdOptions, antStateOptions, arnsPurchaseOptions, buyRecordOptions, decreaseDelegateStakeOptions, delegateStakeOptions, epochOptions, getVaultOptions, globalOptions, joinNetworkOptions, operatorStakeOptions, optionMap, paginationAddressOptions, paginationOptions, redelegateStakeOptions, setAntBaseNameOptions, setAntUndernameOptions, tokenCostOptions, transferOptions, transferRecordOwnershipOptions, updateGatewaySettingsOptions, upgradeAntOptions, vaultedTransferOptions, writeActionOptions, } from './options.js';
@@ -456,6 +457,77 @@ makeCommand({
     options: arnsPurchaseOptions,
     action: setPrimaryNameCLICommand,
 });
+// # Prune / cleanup (Solana-only — permissionless crank surface)
+makeCommand({
+    name: 'prune-expired-names',
+    description: 'Batch-prune expired ArnsRecord PDAs (Solana-only). Discovers eligible records ' +
+        'via getExpiredArnsRecords if --arns-records is omitted.',
+    options: [...writeActionOptions, optionMap.max, optionMap.arnsRecords],
+    action: pruneExpiredNamesCLICommand,
+});
+makeCommand({
+    name: 'prune-name-to-returned',
+    description: 'Convert a single expired-but-not-yet-returned lease into a ReturnedName ' +
+        '(starts the Dutch auction). Solana-only.',
+    options: [...writeActionOptions, optionMap.name],
+    action: pruneNameToReturnedCLICommand,
+});
+makeCommand({
+    name: 'prune-returned-names',
+    description: 'Batch-prune expired ReturnedName PDAs (Solana-only). Discovers via ' +
+        'getExpiredReturnedNames if --returned-names is omitted.',
+    options: [...writeActionOptions, optionMap.max, optionMap.returnedNames],
+    action: pruneReturnedNamesCLICommand,
+});
+makeCommand({
+    name: 'prune-expired-reservation',
+    description: 'Close an expired ReservedName PDA (Solana-only).',
+    options: [...writeActionOptions, optionMap.name],
+    action: pruneExpiredReservationCLICommand,
+});
+makeCommand({
+    name: 'prune-gateway',
+    description: 'Slash + remove a deficient gateway (≥30 consecutive failures). Solana-only.',
+    options: [...writeActionOptions, optionMap.gateway],
+    action: pruneGatewayCLICommand,
+});
+makeCommand({
+    name: 'finalize-gone',
+    description: 'GC a Leaving/Gone gateway whose leave window has fully elapsed. Solana-only.',
+    options: [...writeActionOptions, optionMap.gateway],
+    action: finalizeGoneCLICommand,
+});
+makeCommand({
+    name: 'close-observation',
+    description: 'Reclaim rent from an Observation PDA whose epoch has been distributed. Solana-only.',
+    options: [...writeActionOptions, optionMap.epochIndex, optionMap.observer],
+    action: closeObservationCLICommand,
+});
+makeCommand({
+    name: 'close-empty-delegation',
+    description: 'Close an empty Delegation PDA (amount == 0). Rent refunds to the original delegator. Solana-only.',
+    options: [...writeActionOptions, optionMap.gateway, optionMap.delegator],
+    action: closeEmptyDelegationCLICommand,
+});
+makeCommand({
+    name: 'close-drained-withdrawal',
+    description: 'Close a drained Withdrawal PDA (amount == 0). Rent refunds to the original owner. Solana-only.',
+    options: [...writeActionOptions, optionMap.owner, optionMap.withdrawalId],
+    action: closeDrainedWithdrawalCLICommand,
+});
+makeCommand({
+    name: 'release-vault',
+    description: 'Release tokens from an expired vault back to the owner (Solana-only). ' +
+        'NOT permissionless — must be called from the vault owner wallet.',
+    options: [...writeActionOptions, optionMap.vaultId, optionMap.owner],
+    action: releaseVaultCLICommand,
+});
+makeCommand({
+    name: 'close-expired-request',
+    description: 'Close an expired PrimaryNameRequest PDA. Solana-only.',
+    options: [...writeActionOptions, optionMap.initiator],
+    action: closeExpiredRequestCLICommand,
+});
 // # ANT Registry
 makeCommand({
     name: 'get-ants-for-address',

package/lib/esm/cli/commands/pruneCommands.js

@@ -0,0 +1,166 @@
+import { assertConfirmationPrompt, requiredStringFromOptions, writeARIOFromOptions, } from '../utils.js';
+function rejectAoBackend(o, command) {
+    if (o.ao) {
+        throw new Error(`${command} is Solana-only — Lua's tick() handles the equivalent on AO. Drop --ao.`);
+    }
+}
+async function getSolanaWriter(o) {
+    const { ario } = await writeARIOFromOptions(o);
+    return ario;
+}
+function parseMaxNames(o) {
+    const raw = o.max;
+    if (raw === undefined) {
+        throw new Error('--max <count> is required (u8 batch size, 1-255)');
+    }
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1 || n > 255) {
+        throw new Error(`--max must be an integer 1-255 (got ${raw})`);
+    }
+    return n;
+}
+// =========================================
+// ArNS prune
+// =========================================
+export async function pruneExpiredNamesCLICommand(o) {
+    rejectAoBackend(o, 'prune-expired-names');
+    const max = parseMaxNames(o);
+    const ario = await getSolanaWriter(o);
+    // If `--arns-records` wasn't provided, discover them via the readable's
+    // helper. Cap at `max` so we never overshoot the ix's u8 batch parameter.
+    let records = o.arnsRecords ?? [];
+    if (records.length === 0) {
+        const now = Math.floor(Date.now() / 1000);
+        const expired = await ario.getExpiredArnsRecords(now);
+        records = expired.slice(0, max).map((r) => r.pubkey);
+        if (records.length === 0) {
+            return { message: 'No expired ArnsRecords to prune' };
+        }
+    }
+    else {
+        records = records.slice(0, max);
+    }
+    await assertConfirmationPrompt(`Prune ${records.length} expired ArnsRecord(s)?`, o);
+    return ario.pruneExpiredNames({ maxNames: max, arnsRecords: records });
+}
+export async function pruneNameToReturnedCLICommand(o) {
+    rejectAoBackend(o, 'prune-name-to-returned');
+    const name = requiredStringFromOptions(o, 'name');
+    const ario = await getSolanaWriter(o);
+    await assertConfirmationPrompt(`Convert expired lease for "${name}" to a ReturnedName (Dutch auction)?`, o);
+    return ario.pruneNameToReturned({ name });
+}
+export async function pruneReturnedNamesCLICommand(o) {
+    rejectAoBackend(o, 'prune-returned-names');
+    const max = parseMaxNames(o);
+    const ario = await getSolanaWriter(o);
+    let returned = o.returnedNames ?? [];
+    if (returned.length === 0) {
+        const now = Math.floor(Date.now() / 1000);
+        const expired = await ario.getExpiredReturnedNames(now);
+        returned = expired.slice(0, max).map((r) => r.pubkey);
+        if (returned.length === 0) {
+            return { message: 'No expired ReturnedNames to prune' };
+        }
+    }
+    else {
+        returned = returned.slice(0, max);
+    }
+    await assertConfirmationPrompt(`Prune ${returned.length} expired ReturnedName(s)?`, o);
+    return ario.pruneReturnedNames({
+        maxNames: max,
+        returnedNames: returned,
+    });
+}
+export async function pruneExpiredReservationCLICommand(o) {
+    rejectAoBackend(o, 'prune-expired-reservation');
+    const name = requiredStringFromOptions(o, 'name');
+    const ario = await getSolanaWriter(o);
+    await assertConfirmationPrompt(`Close expired reservation for "${name}"?`, o);
+    return ario.pruneExpiredReservation({ name });
+}
+// =========================================
+// Gateway prune
+// =========================================
+export async function pruneGatewayCLICommand(o) {
+    rejectAoBackend(o, 'prune-gateway');
+    const gateway = requiredStringFromOptions(o, 'gateway');
+    const ario = await getSolanaWriter(o);
+    await assertConfirmationPrompt(`Slash + remove deficient gateway ${gateway}?`, o);
+    return ario.pruneGateway({ gateway });
+}
+export async function finalizeGoneCLICommand(o) {
+    rejectAoBackend(o, 'finalize-gone');
+    const gateway = requiredStringFromOptions(o, 'gateway');
+    const ario = await getSolanaWriter(o);
+    await assertConfirmationPrompt(`Finalize-GC departed gateway ${gateway} (reclaim PDA rent)?`, o);
+    return ario.finalizeGone({ gateway });
+}
+// =========================================
+// Rent reclaim
+// =========================================
+export async function closeObservationCLICommand(o) {
+    rejectAoBackend(o, 'close-observation');
+    const epochIndexStr = requiredStringFromOptions(o, 'epochIndex');
+    const observer = requiredStringFromOptions(o, 'observer');
+    const epochIndex = Number(epochIndexStr);
+    if (!Number.isInteger(epochIndex) || epochIndex < 0) {
+        throw new Error(`--epoch-index must be a non-negative integer (got ${epochIndexStr})`);
+    }
+    const ario = await getSolanaWriter(o);
+    await assertConfirmationPrompt(`Close Observation PDA (epoch ${epochIndex}, observer ${observer})?`, o);
+    return ario.closeObservation({ epochIndex, observer });
+}
+export async function closeEmptyDelegationCLICommand(o) {
+    rejectAoBackend(o, 'close-empty-delegation');
+    const gateway = requiredStringFromOptions(o, 'gateway');
+    const delegator = requiredStringFromOptions(o, 'delegator');
+    const ario = await getSolanaWriter(o);
+    await assertConfirmationPrompt(`Close empty Delegation PDA (gateway=${gateway}, delegator=${delegator})?`, o);
+    return ario.closeEmptyDelegation({ gateway, delegator });
+}
+export async function closeDrainedWithdrawalCLICommand(o) {
+    rejectAoBackend(o, 'close-drained-withdrawal');
+    const owner = requiredStringFromOptions(o, 'owner');
+    const withdrawalIdStr = requiredStringFromOptions(o, 'withdrawalId');
+    // Validate before BigInt() — `BigInt('0xff')` and `BigInt('  1  ')` succeed
+    // and `BigInt('abc')` throws an opaque SyntaxError. Restrict to the u64
+    // decimal form the on-chain seed encoder expects so the CLI fails with a
+    // clear message instead of a downstream parser error.
+    if (!/^\d+$/.test(withdrawalIdStr)) {
+        throw new Error(`--withdrawal-id must be a non-negative decimal integer (got "${withdrawalIdStr}")`);
+    }
+    const withdrawalId = BigInt(withdrawalIdStr);
+    const ario = await getSolanaWriter(o);
+    await assertConfirmationPrompt(`Close drained Withdrawal PDA (owner=${owner}, id=${withdrawalIdStr})?`, o);
+    return ario.closeDrainedWithdrawal({ owner, withdrawalId });
+}
+// =========================================
+// Vault + primary-name request
+// =========================================
+export async function releaseVaultCLICommand(o) {
+    rejectAoBackend(o, 'release-vault');
+    // The on-chain handler requires `owner: Signer` — the SDK uses the
+    // configured signer as the owner. The `--owner` flag is accepted as
+    // documentation but ignored unless it matches the signer; fail loud if
+    // it doesn't, so users don't think they can release someone else's vault.
+    const ario = await getSolanaWriter(o);
+    if (o.owner) {
+        const signerAddr = (await writeARIOFromOptions(o)).signerAddress;
+        if (o.owner !== signerAddr) {
+            throw new Error(`release-vault: --owner ${o.owner} does not match signer ${signerAddr}. ` +
+                `release_vault is owner-signed; use the owner's wallet to call it.`);
+        }
+    }
+    const vaultIdStr = requiredStringFromOptions(o, 'vaultId');
+    const vaultId = vaultIdStr;
+    await assertConfirmationPrompt(`Release expired vault id=${vaultIdStr} (transfer tokens back to owner)?`, o);
+    return ario.releaseVault({ vaultId });
+}
+export async function closeExpiredRequestCLICommand(o) {
+    rejectAoBackend(o, 'close-expired-request');
+    const initiator = requiredStringFromOptions(o, 'initiator');
+    const ario = await getSolanaWriter(o);
+    await assertConfirmationPrompt(`Close expired primary-name request from ${initiator}?`, o);
+    return ario.closeExpiredRequest({ initiator });
+}

package/lib/esm/cli/options.js

@@ -421,6 +421,35 @@ export const optionMap = {
         description: 'Reassign all affiliated names to the new process',
         type: 'boolean',
     },
+    // -----------------------------------------------------------------
+    // Prune / cleanup flags (Solana-only — see pruneCommands.ts)
+    // -----------------------------------------------------------------
+    gateway: {
+        alias: '--gateway <gateway>',
+        description: 'The gateway operator address (prune / finalize commands)',
+    },
+    delegator: {
+        alias: '--delegator <delegator>',
+        description: 'The delegator address (close-empty-delegation)',
+    },
+    observer: {
+        alias: '--observer <observer>',
+        description: 'The observer address (close-observation)',
+    },
+    max: {
+        alias: '--max <max>',
+        description: 'Per-tx batch size (1-255, u8) for prune-expired-names / prune-returned-names',
+    },
+    arnsRecords: {
+        alias: '--arns-records <arnsRecords...>',
+        description: 'Explicit ArnsRecord PDAs to prune. Default: discover via getExpiredArnsRecords.',
+        type: 'array',
+    },
+    returnedNames: {
+        alias: '--returned-names <returnedNames...>',
+        description: 'Explicit ReturnedName PDAs to prune. Default: discover via getExpiredReturnedNames.',
+        type: 'array',
+    },
 };
 export const walletOptions = [
     optionMap.walletFile,

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()
@@ -238,9 +238,7 @@ export class SolanaANTReadable {
             try {
                 const buf = Buffer.from(account.data[0], 'base64');
                 const record = deserializeAntRecord(buf);
-                // Look up metadata by computing the undername hash
-                const { createHash } = await import('crypto');
-                const hash = createHash('sha256')
+                const hash = __createHash('sha256')
                     .update(record.undername.toLowerCase())
                     .digest('hex');
                 const meta = metaByHash.get(hash) ?? {};

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);
+}