@ar.io/sdk 4.0.0-solana.11 → 4.0.0-solana.12

package/README.md

@@ -1043,6 +1043,57 @@ const vaults = await ario.getAllGatewayVaults({
 
 </details>
 
+#### `getWithdrawals({ address, cursor, limit, sortBy, sortOrder })`
+
+**Solana-only.** Returns every pending stake withdrawal owned by `address` — covering both operator-stake decreases (`isDelegate: false`) and delegate-stake decreases (`isDelegate: true`). A withdrawal is claimable when `Date.now() >= endTimestamp`; call `claimWithdrawal({ withdrawalId: item.vaultId })` to release the tokens.
+
+This is the per-owner read needed to drive "you have X claimable withdrawals" UIs without fanning out across every gateway the wallet has interacted with. Throws on the AO backend.
+
+```typescript
+const ario = ARIO.init({ backend: "solana", rpc, rpcSubscriptions, signer });
+
+const withdrawals = await ario.getWithdrawals({
+  address: "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
+});
+
+const claimable = withdrawals.items.filter(
+  (w) => Date.now() >= w.endTimestamp,
+);
+```
+
+<details>
+  <summary>Output</summary>
+
+```json
+{
+  "hasMore": false,
+  "totalItems": 2,
+  "limit": 100,
+  "items": [
+    {
+      "cursorId": "8CSdSjf7gXqQ5p1U2qfdwHzVw9sZRYHJpDpV87dnvb4d",
+      "vaultId": "0",
+      "gatewayAddress": "Bxz7Q2tWfqr9Q5T6cZjUnVxRk9CnHwShfgUaW5fY1Mvr",
+      "balance": 50000000000,
+      "startTimestamp": 1735843635857,
+      "endTimestamp": 1738435635857,
+      "isDelegate": true
+    },
+    {
+      "cursorId": "FmWUz4w7vSdLcz1nN8H1n2KkjJgrQQXR1n4kV3WqJ7Hf",
+      "vaultId": "1",
+      "gatewayAddress": "9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin",
+      "balance": 10000000000,
+      "startTimestamp": 1735843835857,
+      "endTimestamp": 1738435835857,
+      "isDelegate": false
+    }
+  ]
+}
+```
+
+</details>
+
 #### `increaseOperatorStake({ qty })`
 
 Increases the callers operator stake. Must be executed with a wallet registered as a gateway operator.

package/lib/esm/cli/cli.js

@@ -24,7 +24,7 @@ import { buyRecordCLICommand, extendLeaseCLICommand, increaseUndernameLimitCLICo
 import { escrowCancelCLICommand, escrowClaimArweaveCLICommand, escrowClaimEthereumCLICommand, escrowDepositCLICommand, escrowStatusCLICommand, escrowUpdateRecipientCLICommand, } from './commands/escrowCommands.js';
 import { cancelWithdrawal, claimWithdrawal, 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 { getAllGatewayVaults, getAllowedDelegates, getArNSRecord, getArNSReservedName, getArNSReturnedName, getCostDetails, getDelegations, getEpoch, getGateway, getGatewayDelegates, getGatewayVaults, getPrescribedNames, getPrescribedObservers, getPrimaryName, getTokenCost, getVault, getWithdrawals, 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';
 import { applyOptions, arioProcessIdFromOptions, assertConfirmationPrompt, customTagsFromOptions, epochInputFromOptions, formatARIOWithCommas, getANTStateFromOptions, getLoggerFromOptions, makeCommand, paginationParamsFromOptions, readANTFromOptions, readARIOFromOptions, requiredAddressFromOptions, requiredAoSignerFromOptions, requiredProcessIdFromOptions, requiredStringArrayFromOptions, requiredStringFromOptions, writeANTFromOptions, } from './utils.js';
@@ -301,6 +301,12 @@ makeCommand({
     options: paginationAddressOptions,
     action: getAllGatewayVaults,
 });
+makeCommand({
+    name: 'get-withdrawals',
+    description: 'Get all pending stake withdrawals (operator + delegate) owned by an address (Solana-only)',
+    options: paginationAddressOptions,
+    action: getWithdrawals,
+});
 // # Actions
 makeCommand({
     name: 'transfer',

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

@@ -165,6 +165,18 @@ export async function getAllGatewayVaults(o) {
             message: `No vaults found`,
         };
 }
+export async function getWithdrawals(o) {
+    const address = requiredAddressFromOptions(o);
+    const result = await readARIOFromOptions(o).getWithdrawals({
+        address,
+        ...paginationParamsFromOptions(o),
+    });
+    return result.items?.length
+        ? result
+        : {
+            message: `No pending withdrawals found for address ${address}`,
+        };
+}
 export async function getVault(o) {
     return readARIOFromOptions(o)
         .getVault({

package/lib/esm/common/io.js

@@ -758,6 +758,16 @@ export class ARIOReadable {
             ],
         });
     }
+    /**
+     * AO backend stub — `getWithdrawals` is a Solana-only per-owner read that
+     * aggregates operator-stake and delegate-stake withdrawals for a wallet.
+     * On AO, withdrawals auto-distribute at maturity; use `getDelegations`
+     * (vault-typed entries) and `getGatewayVaults` instead.
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    async getWithdrawals(_params) {
+        throw new Error('getWithdrawals is only supported on the Solana backend (use ARIO.init({ backend: "solana", ... })).');
+    }
     async resolveArNSName({ name, }) {
         // derive baseName & undername using last underscore
         const lastUnderscore = name.lastIndexOf('_');

package/lib/esm/solana/deserialize.js

@@ -327,7 +327,7 @@ export function deserializeGatewayWithAccumulator(data) {
     r.skip(8); // weights_epoch — not surfaced on AoGatewayWeights
     // GatewaySettings2 (auto_stake removed in cfc7a8b2 — never existed on Solana)
     const allowDelegatedStaking = r.readBool();
-    const delegateRewardShareRatio = r.readU16();
+    const delegateRewardShareRatio = r.readU16() / 100;
     const minDelegatedStake = r.readU64AsNumber();
     const allowlistEnabled = r.readBool();
     // RegistryIndex (index: u32, _reserved: u8 — was is_registered:bool)

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

@@ -633,6 +633,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
     // =========================================

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

package/lib/types/cli/commands/readCommands.d.ts

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { AoArNSNameDataWithName, AoDelegation, AoGatewayDelegateWithAddress, AoGatewayVault, AoGetCostDetailsParams } from '../../types/io.js';
+import { AoArNSNameDataWithName, AoDelegation, AoGatewayDelegateWithAddress, AoGatewayVault, AoGetCostDetailsParams, AoUserWithdrawal } from '../../types/io.js';
 import { AddressAndNameCLIOptions, AddressAndVaultIdCLIOptions, AddressCLIOptions, CLIOptionsFromAoParams, EpochCLIOptions, GetTokenCostCLIOptions, GlobalCLIOptions, NameCLIOptions, PaginationAddressCLIOptions, PaginationCLIOptions } from '../types.js';
 export declare function getGateway(o: AddressCLIOptions): Promise<import("../../types/io.js").AoGateway>;
 export declare function listGateways(o: PaginationCLIOptions): Promise<import("../../types/io.js").PaginationResult<import("../../types/io.js").AoGatewayWithAddress> | {
@@ -70,6 +70,9 @@ export declare function getGatewayVaults(o: PaginationAddressCLIOptions): Promis
 export declare function getAllGatewayVaults(o: PaginationCLIOptions): Promise<import("../../types/io.js").PaginationResult<import("../../types/io.js").AoAllGatewayVaults> | {
     message: string;
 }>;
+export declare function getWithdrawals(o: PaginationAddressCLIOptions): Promise<import("../../types/io.js").PaginationResult<AoUserWithdrawal> | {
+    message: string;
+}>;
 export declare function getVault(o: AddressAndVaultIdCLIOptions): Promise<import("../../types/io.js").AoVaultData>;
 export declare function resolveArNSName(o: NameCLIOptions): Promise<import("../../types/io.js").ArNSNameResolutionData>;
 export declare function listAntsForAddress(o: AddressCLIOptions): Promise<{

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

@@ -1,5 +1,5 @@
 import Arweave from 'arweave';
-import { ARIOWithFaucet, AoARIORead, AoARIOWrite, AoAllDelegates, AoAllGatewayVaults, AoArNSNameData, AoArNSNameDataWithName, AoArNSPurchaseParams, AoArNSReservedNameData, AoArNSReservedNameDataWithName, AoBalanceWithAddress, AoBuyRecordParams, AoCreatePrimaryNameRequest, AoCreateVaultParams, AoDelegation, AoEligibleDistribution, AoEpochData, AoEpochDistributed, AoEpochDistributionData, AoEpochDistributionTotalsData, AoEpochObservationData, AoEpochSettings, AoExtendLeaseParams, AoExtendVaultParams, AoGateway, AoGatewayDelegateWithAddress, AoGatewayRegistrySettings, AoGatewayVault, AoGatewayWithAddress, AoGetCostDetailsParams, AoIncreaseUndernameLimitParams, AoIncreaseVaultParams, AoJoinNetworkParams, AoMessageResult, AoPaginatedAddressParams, AoPrimaryName, AoPrimaryNameRequest, AoRedelegationFeeInfo, AoRegistrationFees, AoReturnedName, AoRevokeVaultParams, AoTokenSupplyData, AoUpdateGatewaySettingsParams, AoVaultData, AoVaultedTransferParams, AoWalletVault, AoWeightedObserver, ArNSNameResolutionData, ArNSNameResolver, BuyArNSNameProgressEvents, CostDetailsResult, DemandFactorSettings, EpochInput, OptionalArweave, OptionalPaymentUrl, PaginationParams, PaginationResult, ProcessConfiguration, SetPrimaryNameProgressEvents, TransactionId, WalletAddress, WithSigner, WriteOptions, mARIOToken } from '../types/index.js';
+import { ARIOWithFaucet, AoARIORead, AoARIOWrite, AoAllDelegates, AoAllGatewayVaults, AoArNSNameData, AoArNSNameDataWithName, AoArNSPurchaseParams, AoArNSReservedNameData, AoArNSReservedNameDataWithName, AoBalanceWithAddress, AoBuyRecordParams, AoCreatePrimaryNameRequest, AoCreateVaultParams, AoDelegation, AoEligibleDistribution, AoEpochData, AoEpochDistributed, AoEpochDistributionData, AoEpochDistributionTotalsData, AoEpochObservationData, AoEpochSettings, AoExtendLeaseParams, AoExtendVaultParams, AoGateway, AoGatewayDelegateWithAddress, AoGatewayRegistrySettings, AoGatewayVault, AoGatewayWithAddress, AoGetCostDetailsParams, AoIncreaseUndernameLimitParams, AoIncreaseVaultParams, AoJoinNetworkParams, AoMessageResult, AoPaginatedAddressParams, AoPrimaryName, AoPrimaryNameRequest, AoRedelegationFeeInfo, AoRegistrationFees, AoReturnedName, AoRevokeVaultParams, AoTokenSupplyData, AoUpdateGatewaySettingsParams, AoUserWithdrawal, AoVaultData, AoVaultedTransferParams, AoWalletVault, AoWeightedObserver, ArNSNameResolutionData, ArNSNameResolver, BuyArNSNameProgressEvents, CostDetailsResult, DemandFactorSettings, EpochInput, OptionalArweave, OptionalPaymentUrl, PaginationParams, PaginationResult, ProcessConfiguration, SetPrimaryNameProgressEvents, TransactionId, WalletAddress, WithSigner, WriteOptions, mARIOToken } from '../types/index.js';
 import { AOProcess } from './contracts/ao-process.js';
 import { HB } from './hyperbeam/hb.js';
 import { Logger } from './logger.js';
@@ -176,6 +176,15 @@ export declare class ARIOReadable implements AoARIORead, ArNSNameResolver {
     getGatewayRegistrySettings(): Promise<AoGatewayRegistrySettings>;
     getAllDelegates(params?: PaginationParams<AoAllDelegates>): Promise<PaginationResult<AoAllDelegates>>;
     getAllGatewayVaults(params?: PaginationParams<AoAllGatewayVaults>): Promise<PaginationResult<AoAllGatewayVaults>>;
+    /**
+     * AO backend stub — `getWithdrawals` is a Solana-only per-owner read that
+     * aggregates operator-stake and delegate-stake withdrawals for a wallet.
+     * On AO, withdrawals auto-distribute at maturity; use `getDelegations`
+     * (vault-typed entries) and `getGatewayVaults` instead.
+     */
+    getWithdrawals(_params: PaginationParams<AoUserWithdrawal> & {
+        address: WalletAddress;
+    }): Promise<PaginationResult<AoUserWithdrawal>>;
     resolveArNSName({ name, }: {
         name: string;
     }): Promise<ArNSNameResolutionData>;

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

@@ -8,7 +8,7 @@
 import { type Address, type Commitment } from '@solana/kit';
 import { type ILogger } from '../common/logger.js';
 import type { AoPrimaryName, AoPrimaryNameRequest, AoRedelegationFeeInfo, WalletAddress } from '../types/common.js';
-import type { AoAddressParams, AoAllDelegates, AoAllGatewayVaults, AoArNSNameData, AoArNSNameDataWithName, AoArNSReservedNameData, AoArNSReservedNameDataWithName, AoBalanceWithAddress, AoDelegation, AoEligibleDistribution, AoEpochData, AoEpochDistributionData, AoEpochObservationData, AoEpochSettings, AoGateway, AoGatewayDelegateWithAddress, AoGatewayRegistrySettings, AoGatewayVault, AoGatewayWithAddress, AoGetArNSRecordsParams, AoGetCostDetailsParams, AoPaginatedAddressParams, AoRegistrationFees, AoReturnedName, AoTokenCostParams, AoTokenSupplyData, AoVaultData, AoWalletVault, AoWeightedObserver, CostDetailsResult, DemandFactorSettings, EpochInput, PaginationParams, PaginationResult } from '../types/io.js';
+import type { AoAddressParams, AoAllDelegates, AoAllGatewayVaults, AoArNSNameData, AoArNSNameDataWithName, AoArNSReservedNameData, AoArNSReservedNameDataWithName, AoBalanceWithAddress, AoDelegation, AoEligibleDistribution, AoEpochData, AoEpochDistributionData, AoEpochObservationData, AoEpochSettings, AoGateway, AoGatewayDelegateWithAddress, AoGatewayRegistrySettings, AoGatewayVault, AoGatewayWithAddress, AoGetArNSRecordsParams, AoGetCostDetailsParams, AoPaginatedAddressParams, AoRegistrationFees, AoReturnedName, AoTokenCostParams, AoTokenSupplyData, AoUserWithdrawal, AoVaultData, AoWalletVault, AoWeightedObserver, CostDetailsResult, DemandFactorSettings, EpochInput, PaginationParams, PaginationResult } from '../types/io.js';
 import type { SolanaReadConfig, SolanaRpc } from './types.js';
 /**
  * Solana-backed read-only client for the AR.IO protocol.
@@ -132,6 +132,19 @@ export declare class SolanaARIOReadable {
     getGatewayVaults(params: PaginationParams<AoGatewayVault> & {
         address: WalletAddress;
     }): Promise<PaginationResult<AoGatewayVault>>;
+    /**
+     * 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.
+     */
+    getWithdrawals(params: PaginationParams<AoUserWithdrawal> & {
+        address: WalletAddress;
+    }): Promise<PaginationResult<AoUserWithdrawal>>;
     getArNSRecord({ name }: {
         name: string;
     }): Promise<AoArNSNameData>;

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

@@ -276,6 +276,17 @@ export type AoGatewayVault = {
 export type AoAllGatewayVaults = AoGatewayVault & {
     gatewayAddress: WalletAddress;
 };
+/**
+ * A pending or matured stake withdrawal owned by a wallet. Covers both
+ * operator-stake decreases and delegate-stake decreases — discriminate with
+ * `isDelegate`. A withdrawal is claimable when `Date.now() >= endTimestamp`.
+ *
+ * Solana-only: AO releases withdrawals automatically at maturity and has no
+ * equivalent per-owner read.
+ */
+export type AoUserWithdrawal = AoAllGatewayVaults & {
+    isDelegate: boolean;
+};
 export type AoJoinNetworkParams = Pick<AoGateway, 'operatorStake'> & Partial<AoGatewaySettings> & {
     observerAddress?: WalletAddress;
     services?: AoGatewayServices;
@@ -557,6 +568,9 @@ export interface AoARIORead extends ArNSNameResolver {
     getGatewayRegistrySettings(): Promise<AoGatewayRegistrySettings>;
     getAllDelegates(params?: PaginationParams<AoAllDelegates>): Promise<PaginationResult<AoAllDelegates>>;
     getAllGatewayVaults(params?: PaginationParams<AoAllGatewayVaults>): Promise<PaginationResult<AoAllGatewayVaults>>;
+    getWithdrawals(params: PaginationParams<AoUserWithdrawal> & {
+        address: WalletAddress;
+    }): Promise<PaginationResult<AoUserWithdrawal>>;
 }
 export interface AoARIOWrite extends AoARIORead {
     transfer: AoWriteAction<{

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

package/package.json

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