@ar.io/sdk 3.24.0 → 4.0.0-alpha.2

package/lib/types/solana/funding-plan.d.ts

@@ -0,0 +1,225 @@
+/**
+ * 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.
+ */
+/**
+ * Multi-source, multi-gateway funding plan builder + executor for the AR.IO
+ * Solana SDK.
+ *
+ * Lua-faithful port of `gar.getFundingPlan` / `gar.applyFundingPlan` from
+ * `ar-io-network-process/src/gar.lua`. Supports Delegation sources across
+ * multiple gateways in a single plan (closes BD-076).
+ *
+ * Drawdown order (matches Lua exactly):
+ *   1. Balance — taken first when `fundFrom in {'balance','any','plan'}`
+ *      (`planBalanceDrawdown` in gar.lua:1456)
+ *   2. Withdrawal vaults — sorted asc by `available_at`, oldest-maturing
+ *      first (`planVaultsDrawdown` in gar.lua:1510). Gateway-independent.
+ *   3. Excess delegated stake — iterates ALL gateways the user has delegated
+ *      on (Lua-sorted: desc excess, asc perf, desc total stake, desc start
+ *      timestamp). Up to MAX_DELEGATION_SOURCES gateways per plan.
+ *      (`planExcessStakesDrawdown` in gar.lua:1559)
+ *   4. Minimum delegated stake — drains the floor on each touched gateway,
+ *      auto-vaulting the residue. Same gateway iteration order as step 3.
+ *      (`planMinimumStakesDrawdown` in gar.lua:1585)
+ *
+ * Operator stake is a Solana extension: Lua's funding plans never touch it.
+ * The picker excludes operator stake unless `opts.fundAsOperator === true`.
+ *
+ * The on-chain `pay_from_funding_plan` ix caps the source list at
+ * MAX_FUNDING_SOURCES (5) and Delegation sources at MAX_DELEGATION_SOURCES (3)
+ * (see `programs/ario-gar/src/state/mod.rs`). The planner enforces the same
+ * caps so `executeFundingPlan` calls never get rejected for
+ * `TooManyFundingSources` / `TooManyDelegationSources`.
+ */
+import { AccountRole, type Address, type Rpc, type SolanaRpcApi, type SolanaRpcApiMainnet } from '@solana/kit';
+/**
+ * The discovery + executor accept either the dev/test or the mainnet RPC API
+ * shape — they only use methods that are common to both (`getProgramAccounts`,
+ * `getAccountInfo`).
+ */
+export type FundingPlanRpc = Rpc<SolanaRpcApi> | Rpc<SolanaRpcApiMainnet>;
+import { type FundingSourceKind, type FundingSourceSpec } from '../types/io.js';
+/**
+ * Hard cap on funding-plan length — must stay in sync with the on-chain
+ * `MAX_FUNDING_SOURCES` constant (`programs/ario-gar/src/state/mod.rs`).
+ */
+export declare const MAX_FUNDING_SOURCES = 5;
+/**
+ * Hard cap on Delegation sources within a single plan — must stay in sync
+ * with the on-chain `MAX_DELEGATION_SOURCES` constant.
+ */
+export declare const MAX_DELEGATION_SOURCES = 3;
+/** A single source the user can draw from. Discovery returns these. */
+export type DiscoveredFundingSource = {
+    kind: 'balance';
+    available: bigint;
+} | {
+    kind: 'delegation';
+    gateway: Address;
+    available: bigint;
+    /** Per-gateway floor; the residue auto-vaults if drained below this. */
+    minDelegationAmount: bigint;
+    /** Gateway performance ratio — used for Lua-faithful sort order. */
+    performanceRatio: number;
+    /** Total delegated stake on the gateway — secondary sort key. */
+    totalDelegatedStake: bigint;
+    /** Gateway start timestamp — tertiary sort key. */
+    startTimestamp: bigint;
+} | {
+    kind: 'operatorStake';
+    gateway: Address;
+    available: bigint;
+    minOperatorStake: bigint;
+} | {
+    kind: 'withdrawal';
+    withdrawalId: bigint;
+    gateway: Address;
+    available: bigint;
+    availableAt: bigint;
+};
+/** Output of `buildFundingPlan` when a plan covers the requested amount. */
+export type FundingPlan = {
+    /** Source specs in declaration order — passed verbatim to the on-chain ix. */
+    sources: FundingSourceSpec[];
+    /**
+     * Per-source bound gateway, in declaration order. `undefined` for Balance
+     * and Withdrawal sources; set for Delegation and OperatorStake sources.
+     * Used by the executor to materialize per-source gateway PDA slots in
+     * `remaining_accounts`.
+     */
+    gatewayPerSource: (Address | undefined)[];
+    /**
+     * Indexes (into `sources`) of Delegation sources that will trigger an
+     * on-chain residue auto-vault (drained below `min_delegation_amount`).
+     * The executor must supply that many trailing residue_vault PDAs in
+     * `remaining_accounts`, in the same order as these indexes.
+     */
+    residueDelegationIndexes: number[];
+    /** Whether any Balance source is in the plan (drives optional `payer_token_account`). */
+    hasBalanceSource: boolean;
+};
+/** Discriminated error emitted when no plan covers the requested amount. */
+export type InsufficientFundingError = {
+    kind: 'InsufficientFunding';
+    amountNeeded: bigint;
+    shortfall: bigint;
+    availableSources: DiscoveredFundingSource[];
+    message: string;
+};
+export type BuildFundingPlanOpts = {
+    /** SDK fundFrom mode — drives source preferences (balance / stakes / withdrawal / plan / any). */
+    fundFrom?: 'balance' | 'stakes' | 'withdrawal' | 'plan' | 'any';
+    /**
+     * When set, prefer this gateway first when iterating stake-locked
+     * delegation sources. Other gateways are still considered for additional
+     * fill (up to MAX_DELEGATION_SOURCES total).
+     */
+    preferGateway?: Address;
+    /** Solana extension: include OperatorStake in the picker. Default false (Lua parity). */
+    fundAsOperator?: boolean;
+    /** When set, use only sources of this kind (single-source mode). */
+    restrictToKind?: FundingSourceKind;
+};
+/**
+ * Enumerate the user's fund-from-eligible sources via `getProgramAccounts`
+ * + targeted reads.
+ *
+ * `getProgramAccounts` is restricted on most public Solana RPCs; callers
+ * pointing at default endpoints should switch to a DAS-equivalent RPC
+ * (Helius, Triton, etc.) or pass an explicit `sources` array on the
+ * fee-paying ix to skip discovery.
+ *
+ * Returns sources sorted in the Lua-faithful drawdown order so callers can
+ * iterate without re-sorting.
+ */
+export declare function discoverFundingSources(rpc: FundingPlanRpc, owner: Address, opts: {
+    /** Mint of ARIO; required to compute the user's ATA. */
+    arioMint: Address;
+    /** Optional: pre-fetched balance from the user's ATA (bypasses RPC). */
+    balanceOverride?: bigint;
+    /** Optional ario-gar program override (defaults to deployed program). */
+    garProgram?: Address;
+}): Promise<DiscoveredFundingSource[]>;
+/**
+ * Build a multi-source funding plan that covers `amountNeeded` mARIO.
+ *
+ * Returns `{ kind: 'InsufficientFunding', ... }` when no plan covers the
+ * amount given the supplied sources — caller handles by topping up balance,
+ * choosing a different gateway, or surfacing the error to the user.
+ *
+ * Multi-gateway: Delegation sources span up to MAX_DELEGATION_SOURCES (3)
+ * different gateways. The planner iterates delegations in Lua-faithful order
+ * (or `opts.preferGateway` first if set), drawing excess from each before
+ * falling back to floor-draining (which auto-vaults the residue).
+ *
+ * OperatorStake (Solana extension) is bound to a single gateway when present.
+ * Withdrawal sources have NO gateway constraint.
+ */
+export declare function buildFundingPlan(sources: DiscoveredFundingSource[], amountNeeded: bigint, opts?: BuildFundingPlanOpts): FundingPlan | InsufficientFundingError;
+/**
+ * Materialize a `FundingPlan` into the per-source PDAs the on-chain ix
+ * expects in `remaining_accounts`.
+ *
+ * Layout (per source, in declaration order):
+ *   - Balance:        0 slots
+ *   - Delegation:     2 slots [gateway_pda, delegation_pda]
+ *   - OperatorStake:  1 slot  [gateway_pda]
+ *   - Withdrawal:     1 slot  [withdrawal_pda]
+ *
+ * Followed by N residue_vault PDAs (in the order produced by
+ * `predictResidueVaults`), one per element of `plan.residueDelegationIndexes`.
+ */
+export declare function buildFundingPlanRemainingAccounts(plan: FundingPlan, owner: Address, opts?: {
+    /** Per-source override for Withdrawal PDAs. By index of Withdrawal sources in plan. */
+    withdrawalIds?: bigint[];
+    /** Residue-vault PDAs from `predictResidueVaults`, in plan order. */
+    residueVaults?: Address[];
+    garProgram?: Address;
+}): Promise<{
+    address: Address;
+    role: AccountRole;
+}[]>;
+/**
+ * Pure helper: given an array of explicit `FundingSourceSpec`s and the
+ * decoded (delegation.amount, gateway.minDelegationAmount) for each
+ * Delegation source, return the indexes of sources that will trigger an
+ * on-chain residue auto-vault (post-drain in `(0, min)`).
+ *
+ * `delegationStates[i]` matches `sources[i]` by index — entries for non-
+ * Delegation sources are ignored. Pass `undefined` for those slots.
+ *
+ * Caller is responsible for fetching the on-chain state; this function
+ * is intentionally pure to keep it unit-testable without mocking RPC.
+ */
+export declare function computeResidueIndexes(sources: {
+    kind: string;
+    amount: bigint;
+}[], delegationStates: ({
+    delegationAmount: bigint;
+    minDelegationAmount: bigint;
+} | undefined)[]): number[];
+/**
+ * Predict the residue Withdrawal PDAs the on-chain ix will use for any
+ * Delegation source draining sub-min. Returns one PDA per
+ * `plan.residueDelegationIndexes` entry, sequenced from the user's current
+ * `WithdrawalCounter.next_id`.
+ */
+export declare function predictResidueVaults(rpc: FundingPlanRpc, owner: Address, plan: FundingPlan, opts?: {
+    garProgram?: Address;
+}): Promise<{
+    residueVaults: Address[];
+    withdrawalCounter: Address;
+    nextId: bigint;
+}>;

package/lib/types/solana/index.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 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 backend for the AR.IO SDK.
+ *
+ * This module provides Solana-native implementations of the AR.IO read/write
+ * interfaces, allowing consumers to interact with AR.IO protocol state
+ * stored on Solana instead of AO. All primitives come from `@solana/kit` —
+ * `@solana/web3.js` is not used.
+ *
+ * Usage:
+ * ```ts
+ * import {
+ *   createSolanaRpc,
+ *   createSolanaRpcSubscriptions,
+ *   generateKeyPairSigner,
+ * } from '@solana/kit';
+ * import {
+ *   SolanaARIOReadable,
+ *   SolanaARIOWriteable,
+ *   SolanaANTReadable,
+ * } from '@ar.io/sdk/solana';
+ *
+ * const rpc = createSolanaRpc('https://api.mainnet-beta.solana.com');
+ *
+ * // Read-only (RPC only)
+ * const ario = new SolanaARIOReadable({ rpc });
+ *
+ * // Read-write (signer + subscriptions client needed for confirmation)
+ * const rpcSubscriptions = createSolanaRpcSubscriptions(
+ *   'wss://api.mainnet-beta.solana.com',
+ * );
+ * const signer = await generateKeyPairSigner();
+ * const arioWrite = new SolanaARIOWriteable({ rpc, rpcSubscriptions, signer });
+ *
+ * // ANT (Arweave Name Token)
+ * const ant = new SolanaANTReadable({
+ *   rpc,
+ *   processId: 'MetaplexCoreAssetAddress...',
+ * });
+ * ```
+ */
+export * from '../common/index.js';
+export * from '../types/index.js';
+export * from '../utils/index.js';
+export { ARWEAVE_TX_REGEX, AR_IO_PROTOCOL, arweaveUri, FQDN_REGEX, MARIO_PER_ARIO, } from '../constants.js';
+export { SolanaARIOReadable } from './io-readable.js';
+export { type CrankAction, type CrankEpochStepOptions, type CrankEpochStepResult, isInvalidGatewayAccountError, SolanaARIOWriteable, } from './io-writeable.js';
+export { SolanaANTReadable } from './ant-readable.js';
+export { SolanaANTWriteable } from './ant-writeable.js';
+export { SolanaANTRegistryReadable } from './ant-registry-readable.js';
+export type { SolanaANTRegistryConfig } from './ant-registry-readable.js';
+export { SolanaANTRegistryWriteable } from './ant-registry-writeable.js';
+export type { SolanaANTRegistryWriteableConfig } from './ant-registry-writeable.js';
+export type { AclMaintenanceOp, AclMaintenanceRole, } from '../types/ant-registry.js';
+export { ANTEscrow, TokenEscrow, assertVaultClaimable, isVaultClaimable, CLOCK_SKEW_TOLERANCE_SECONDS, } from './escrow.js';
+export type { ANTEscrowConfig, EscrowAntState, EscrowAssetType, EscrowProtocol, EscrowTokenState, } from './escrow.js';
+export { canonicalMessage, canonicalMessageV2, deriveRecipientId, bytesToHexLower, } from './canonical-message.js';
+export type { CanonicalMessageInput, CanonicalMessageV2Input, EscrowNetwork, } from './canonical-message.js';
+export { spawnSolanaANT, ARIO_LOGO_TX_ID, DEFAULT_ANT_TRANSACTION_ID, } from './spawn-ant.js';
+export type { SpawnSolanaANTParams, SpawnSolanaANTResult, SpawnSolanaANTState, } from './spawn-ant.js';
+export { hashName, getArioConfigPDA, getBalancePDA, getVaultPDA, getVaultCounterPDA, getPrimaryNamePDA, getPrimaryNameRequestPDA, getGatewayRegistryPDA, getGarSettingsPDA, getGatewayPDA, getDelegationPDA, getWithdrawalPDA, getWithdrawalCounterPDA, getAllowlistPDA, getEpochPDA, getEpochSettingsPDA, getObservationPDA, getArnsRegistryPDA, getArnsSettingsPDA, getArnsRecordPDA, getArnsRecordPDAFromHash, getReservedNamePDA, getReturnedNamePDA, getDemandFactorPDA, getPrimaryNameReversePDA, getRedelegationRecordPDA, getAntConfigPDA, getAntControllersPDA, getAntRecordPDA, getAclConfigPDA, getAclPagePDA, getEscrowAntPDA, getEscrowTokenPDA, getEscrowVaultPDA, } from './pda.js';
+export { BorshReader, BorshWriter, deserializeGateway, deserializeArnsRecord, deserializeVault, deserializeDelegation, deserializeBalance, deserializeEpochSettings, deserializeArioConfig, deserializeDemandFactor, deserializeReservedName, deserializeReturnedName, deserializeWithdrawal, deserializeRedelegationRecord, deserializePrimaryNameRequest, deserializePrimaryName, deserializeAllowlist, deserializeGarSettings, deserializeEpochSettingsFull, deserializeEpoch, deserializeObservation, deserializeAntConfig, deserializeAntControllers, deserializeAntRecord, deserializeAclConfig, deserializeAclPage, } from './deserialize.js';
+export type { DeserializedAclEntry } from './deserialize.js';
+export { predictPrescribedObservers, type RegistrySlotWeight, } from './predict-prescribed-observers.js';
+export * from './constants.js';
+export * from './clusters.js';
+export { createCircuitBreakerRpc, defaultFallbackUrl, } from './rpc-circuit-breaker.js';
+export type { CircuitBreakerRpcConfig, CircuitBreakerRpcOptions, } from './rpc-circuit-breaker.js';
+export { withRetry, isRetryableError } from './retry.js';
+export type { RetryOptions } from './retry.js';
+export type { SolanaConfig, SolanaReadConfig, SolanaWriteConfig, SolanaRpc, SolanaRpcSubscriptions, SolanaSigner, SolanaTransactionResult, AccountData, } from './types.js';
+export { parseTransactionEvents, parseEventsFromLogs, isEvent, } from './events.js';
+export type { AnyEvent, AnyArioCoreEvent, AnyArioGarEvent, AnyArioArnsEvent, AnyArioAntEvent, AnyArioAntEscrowEvent, EventName, } from './events.js';

package/lib/types/solana/instruction.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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.
+ */
+/**
+ * Common Solana program/sysvar addresses used by the SDK.
+ *
+ * All AR.IO and Metaplex Core instructions are now built via Codama-generated
+ * builders under `./generated/<program>/instructions/*`. This module only
+ * re-exports the AR.IO program IDs and a few sysvar/system constants that
+ * the rest of the SDK still references by name.
+ */
+import { type Address } from '@solana/kit';
+import { ARIO_ANT_PROGRAM_ID, ARIO_ARNS_PROGRAM_ID, ARIO_CORE_PROGRAM_ID, ARIO_GAR_PROGRAM_ID } from './constants.js';
+/**
+ * System program (11111111111111111111111111111111).
+ * Kit-native equivalent of web3.js's `SystemProgram.programId`.
+ */
+export declare const SYSTEM_PROGRAM_ADDRESS: Address;
+/**
+ * SPL Token program address.
+ */
+export declare const TOKEN_PROGRAM_ADDRESS: Address;
+/**
+ * Rent sysvar address.
+ */
+export declare const SYSVAR_RENT_ADDRESS: Address;
+export { ARIO_CORE_PROGRAM_ID, ARIO_GAR_PROGRAM_ID, ARIO_ARNS_PROGRAM_ID, ARIO_ANT_PROGRAM_ID, };