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

package/lib/esm/solana/clusters.js

@@ -0,0 +1,111 @@
+/**
+ * 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.
+ */
+/**
+ * Cluster-specific deployment constants for AR.IO programs.
+ *
+ * The program-ID constants in `./constants.ts` (e.g. `ARIO_CORE_PROGRAM_ID`)
+ * are codama *placeholders* (`ARioCoreProgramXXX…`), not real on-chain
+ * addresses — consumers must pass real IDs via `ARIO.init({ programIds })`.
+ * This module exposes the deployed sets per cluster: `MAINNET_PROGRAM_IDS`
+ * and `DEVNET_PROGRAM_IDS`.
+ *
+ * Only root facts live here: program IDs, the RPC URL, and the ARIO mint.
+ * Everything else is derived rather than stored — config/settings PDAs come
+ * from the codama `find*Pda` helpers in `@ar.io/solana-contracts` (seeded by
+ * the program IDs below), and genesis-time token accounts (treasury / stake)
+ * are read on-chain from the ArioConfig / GarSettings accounts at runtime
+ * (see `io-writeable.ts` `getGarConfig`). Nothing to keep in sync, nothing to
+ * drift.
+ *
+ * Usage:
+ * ```ts
+ * import { ARIO } from '@ar.io/sdk';
+ * import { DEVNET_PROGRAM_IDS, DEVNET_RPC_URL } from '@ar.io/sdk/solana';
+ * import { createSolanaRpc, createSolanaRpcSubscriptions } from '@solana/kit';
+ *
+ * const rpc = createSolanaRpc(DEVNET_RPC_URL);
+ * const rpcSubscriptions = createSolanaRpcSubscriptions(
+ *   DEVNET_RPC_URL.replace(/^https/, 'wss'),
+ * );
+ * const ario = ARIO.init({
+ *   backend: 'solana',
+ *   rpc,
+ *   rpcSubscriptions,
+ *   programIds: DEVNET_PROGRAM_IDS,
+ * });
+ * ```
+ */
+import { address } from '@solana/kit';
+/**
+ * Default JSON-RPC URL for Solana mainnet-beta.
+ *
+ * The public endpoint rate-limits aggressively — for production use a premium
+ * RPC (QuickNode / Helius / Triton). Derive the WS URL with
+ * `MAINNET_RPC_URL.replace(/^https/, 'wss')`.
+ */
+export const MAINNET_RPC_URL = 'https://api.mainnet-beta.solana.com';
+/**
+ * Default JSON-RPC URL for the Solana devnet cluster.
+ *
+ * Public devnet rate-limits aggressively — for high-volume work, swap in
+ * a premium RPC (QuickNode / Helius / Triton). Derive the WS URL with
+ * `DEVNET_RPC_URL.replace(/^https/, 'wss')`.
+ */
+export const DEVNET_RPC_URL = 'https://api.devnet.solana.com';
+/**
+ * AR.IO program IDs deployed on Solana mainnet-beta.
+ *
+ * Shape matches the `programIds` argument of
+ * `ARIO.init({ backend: 'solana', programIds, ... })`.
+ */
+export const MAINNET_PROGRAM_IDS = {
+    core: address('73YoECm6NKXpVRoe5f1Q9BcP5DJGPFUjnFy6AxBE5Nvh'),
+    gar: address('89fNiiwgpFSPHKuqfNUkgYTYjtAJAhyqHjXmgXeppGpf'),
+    arns: address('2yCUx5edFvUrkibYaUa2ZXWyx9kuJkS8CwyzsgHPWdZZ'),
+    ant: address('2MWexMHfMhGJwMHv9Qm9YAVCqjUFUJwDJAysW4oCUGk5'),
+    antEscrow: address('5HZhe9UqKL5zAsdz81nuuaxV41h8bFhudzxxBigAQndM'),
+};
+/**
+ * Mainnet attestor pubkey — the key that signs cross-protocol attestations
+ * (e.g. escrow recipient proofs). Deployment metadata; not consumed by the
+ * SDK, exposed here for reference/verification by downstream tooling.
+ */
+export const MAINNET_ATTESTOR_PUBKEY = address('7XtUnotZAeYZNzVSYV5nb7S9YH9qHXyVFM6NeNMu6efE');
+/**
+ * Mainnet upgrade/admin authority pubkey — holds the upgrade authority for
+ * the programs above. Deployment metadata; not consumed by the SDK, exposed
+ * here for reference.
+ */
+export const MAINNET_AUTHORITY_PUBKEY = address('45ZuEb1Jk7pbjshD1BVasBekAXhimdWuJjyswQzMyTB1');
+// TODO(mainnet): placeholder — this reuses the devnet mint and is WRONG for
+// mainnet. Replace with the real mainnet ARIO mint once it is known.
+/** ARIO SPL Token mint on Solana mainnet-beta. */
+export const MAINNET_ARIO_MINT = address('6vTw5CysRXQ4ybbHkDUiisHWVsBeMtUzYvJqs2iqHyaN');
+/**
+ * AR.IO program IDs deployed on Solana devnet (staging).
+ *
+ * Shape matches the `programIds` argument of
+ * `ARIO.init({ backend: 'solana', programIds, ... })`.
+ */
+export const DEVNET_PROGRAM_IDS = {
+    core: address('8Njx9wPkXiNzDCgjwVsJFRjpAEV34gGW3n8DzX3V23m1'),
+    gar: address('7WsDTrtZBsfKtnP33XkjuqXCY69JE7n4QVYpynqJCFxz'),
+    arns: address('6EZNezcg4rc5hnh8HG34vGquT3WpW5xXypzPb24uyEpp'),
+    ant: address('DbHbRwUD1oAn1mrDSqtWtvwGcNrmhWdD2g8L4xmeQ7NX'),
+    antEscrow: address('bttco5oAnBwCucG63iKokBJCZmNr493f3Ewe9LM3oTx'),
+};
+/** ARIO SPL Token mint on devnet (Staging v2). */
+export const DEVNET_ARIO_MINT = address('6vTw5CysRXQ4ybbHkDUiisHWVsBeMtUzYvJqs2iqHyaN');

package/lib/esm/solana/constants.js

@@ -0,0 +1,146 @@
+/**
+ * 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 program IDs and PDA seed constants for AR.IO programs.
+ *
+ * These must match the seeds defined in the Anchor programs under
+ * contracts/programs/{ario-core,ario-gar,ario-arns,ario-ant}/src/.
+ */
+import { address } from '@solana/kit';
+// Program IDs — placeholder addresses (replace with deployed program IDs)
+export const ARIO_CORE_PROGRAM_ID = address('73YoECm6NKXpVRoe5f1Q9BcP5DJGPFUjnFy6AxBE5Nvh');
+export const ARIO_GAR_PROGRAM_ID = address('89fNiiwgpFSPHKuqfNUkgYTYjtAJAhyqHjXmgXeppGpf');
+export const ARIO_ARNS_PROGRAM_ID = address('2yCUx5edFvUrkibYaUa2ZXWyx9kuJkS8CwyzsgHPWdZZ');
+export const ARIO_ANT_PROGRAM_ID = address('2MWexMHfMhGJwMHv9Qm9YAVCqjUFUJwDJAysW4oCUGk5');
+export const ARIO_ANT_ESCROW_PROGRAM_ID = address('5HZhe9UqKL5zAsdz81nuuaxV41h8bFhudzxxBigAQndM');
+export const ARIO_TOKEN_MINT_ADDRESS = address('DcNnMuFxwhgV4WY1HVSaSEgr92bv2b1vUvEKiNxWqHdF');
+export const MPL_CORE_PROGRAM_ID = address('CoREENxT6tW1HoK8ypY1SxRMZTcVPm7R94rH4PZNhX7d');
+// Token constants
+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
+// =========================================
+export const ARIO_CONFIG_SEED = Buffer.from('ario_config');
+export const VAULT_SEED = Buffer.from('vault');
+export const VAULT_COUNTER_SEED = Buffer.from('vault_counter');
+export const BALANCE_SEED = Buffer.from('balance');
+export const PRIMARY_NAME_SEED = Buffer.from('primary_name');
+export const PRIMARY_NAME_REQUEST_SEED = Buffer.from('primary_name_request');
+export const PRIMARY_NAME_REVERSE_SEED = Buffer.from('primary_name_reverse');
+// =========================================
+// PDA Seeds — ario-gar
+// =========================================
+export const GATEWAY_REGISTRY_SEED = Buffer.from('gateway_registry');
+export const GAR_SETTINGS_SEED = Buffer.from('gar_settings');
+export const GATEWAY_SEED = Buffer.from('gateway');
+export const DELEGATION_SEED = Buffer.from('delegation');
+export const WITHDRAWAL_SEED = Buffer.from('withdrawal');
+export const WITHDRAWAL_COUNTER_SEED = Buffer.from('withdrawal_counter');
+export const ALLOWLIST_SEED = Buffer.from('allowlist');
+export const EPOCH_SEED = Buffer.from('epoch');
+export const EPOCH_SETTINGS_SEED = Buffer.from('epoch_settings');
+export const OBSERVATION_SEED = Buffer.from('observation');
+export const REDELEGATION_SEED = Buffer.from('redelegation');
+export const OBSERVER_LOOKUP_SEED = Buffer.from('observer_lookup');
+// =========================================
+// PDA Seeds — ario-arns
+// =========================================
+export const ARNS_REGISTRY_SEED = Buffer.from('name_registry');
+export const ARNS_SETTINGS_SEED = Buffer.from('arns_config');
+export const ARNS_RECORD_SEED = Buffer.from('arns_record');
+export const RESERVED_NAME_SEED = Buffer.from('reserved_name');
+export const RETURNED_NAME_SEED = Buffer.from('returned_name');
+export const DEMAND_FACTOR_SEED = Buffer.from('demand_factor');
+/**
+ * Byte offsets of fixed-size fields within an `ArnsRecord` account.
+ *
+ * Used as `memcmp` filter offsets for `getProgramAccounts` so callers
+ * can resolve "which ArNS record points at this ANT mint?" as a true
+ * point query instead of scanning every record. Mirrors the
+ * `ArnsRecord::ANT_OFFSET` / `OWNER_OFFSET` constants in
+ * `contracts/programs/ario-arns/src/state/mod.rs` — keep them in
+ * sync if the on-chain layout ever changes.
+ */
+export const ARNS_RECORD_NAME_HASH_OFFSET = 8;
+export const ARNS_RECORD_OWNER_OFFSET = 8 + 32; // 40
+export const ARNS_RECORD_ANT_OFFSET = 8 + 32 + 32; // 72
+// =========================================
+// PDA Seeds — ario-ant
+// =========================================
+export const ANT_CONFIG_VERSION = 1;
+export const ANT_CONFIG_SEED = Buffer.from('ant_config');
+export const ANT_CONTROLLERS_SEED = Buffer.from('ant_controllers');
+export const ANT_RECORD_SEED = Buffer.from('ant_record');
+export const ANT_RECORD_META_SEED = Buffer.from('ant_record_meta');
+// Per-user paginated ACL (ADR-012). See `docs/ACCOUNT_SCALING_PATTERNS.md`
+// Pattern C: a head `AclConfig` plus deterministically-addressed `AclPage`s
+// indexed by `u64` little-endian page idx.
+export const ACL_CONFIG_SEED = Buffer.from('acl_config');
+export const ACL_PAGE_SEED = Buffer.from('acl_page');
+/**
+ * Maximum live entries per `AclPage` (must match the on-chain constant).
+ *
+ * Each entry is 33 bytes (`Pubkey + u8`). 256 entries = 8_448 bytes raw —
+ * fits the default 32 KiB BPF heap with margin and stays well under the
+ * 10 KiB per-tx realloc cap when allocated at full size.
+ */
+export const MAX_ACL_PAGE_ENTRIES = 256;
+/** ACL relationship roles (encoded as `u8` on each `AclEntry`). */
+export const ACL_ROLE_OWNER = 0;
+export const ACL_ROLE_CONTROLLER = 1;
+// =========================================
+// PDA Seeds — ario-ant-escrow
+// =========================================
+export const ESCROW_ANT_SEED = Buffer.from('escrow_ant');
+export const ESCROW_TOKEN_SEED = Buffer.from('escrow_token');
+export const ESCROW_VAULT_SEED = Buffer.from('escrow_vault');
+// =========================================
+// ario-ant-escrow protocol constants (must match Rust state.rs)
+// =========================================
+export const ESCROW_PROTOCOL_ARWEAVE = 0;
+export const ESCROW_PROTOCOL_ETHEREUM = 1;
+export const ESCROW_ARWEAVE_PUBKEY_LEN = 512;
+export const ESCROW_ETHEREUM_PUBKEY_LEN = 20;
+export const ESCROW_RECIPIENT_PUBKEY_MAX_LEN = 512;
+export const ESCROW_ASSET_TYPE_TOKEN = 1;
+export const ESCROW_ASSET_TYPE_VAULT = 2;
+// =========================================
+// Protocol constants (must match Rust)
+// =========================================
+// Multi-protocol target constants (must match ario-ant/src/state.rs)
+export const PROTOCOL_ARWEAVE = 0;
+export const PROTOCOL_IPFS = 1;
+export const MAX_TARGET_LENGTH = 128;
+export const MAX_NAME_LENGTH = 51;
+export const MIN_TTL_SECONDS = 60;
+export const MAX_TTL_SECONDS = 86_400;
+export const MAX_CONTROLLERS = 10;
+export const EPOCH_DURATION_SECONDS = 86_400;
+export const WITHDRAWAL_LOCK_PERIOD = 30 * 86_400; // 30 days in seconds
+export const MIN_OPERATOR_STAKE = 20_000 * ONE_TOKEN; // 20,000 ARIO
+export const MIN_DELEGATION_AMOUNT = 10 * ONE_TOKEN; // 10 ARIO
+export const LEASE_GRACE_PERIOD = 14 * 86_400; // 14 days
+export const PRIMARY_NAME_REQUEST_EXPIRY = 7 * 86_400; // 7 days
+export const MAX_GATEWAYS = 3000;
+export const MAX_NAMES = 50_000;

package/lib/esm/solana/delegation-math.js

@@ -0,0 +1,112 @@
+/**
+ * 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.
+ */
+/**
+ * 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);
+}
+/**
+ * Select the delegations worth compounding, from decoded delegations + a map
+ * of their gateways' reward accumulators. Pure (no I/O) so it's unit-testable
+ * independently of RPC; `SolanaARIOReadable.getDelegationsToCompound` is just
+ * fetch+decode wrapped around this.
+ *
+ * A delegation is included when its pending reward (live balance − settled
+ * principal) exceeds `minPendingRewards`, EXCEPT when its gateway is `leaving`
+ * (those settle via `claim_delegate_from_leaving_gateway`, not compounding) or
+ * its gateway is missing/unreadable. Compounding sub-threshold dust only
+ * advances `reward_debt` for no balance gain, so it's filtered out.
+ */
+export function selectCompoundableDelegations(delegations, gatewaysByOperator, minPendingRewards = 0) {
+    const out = [];
+    for (const del of delegations) {
+        const gw = gatewaysByOperator.get(del.gateway);
+        if (!gw || gw.status === 'leaving')
+            continue;
+        const live = computeLiveDelegationBalance({
+            delegatedStake: del.delegatedStake,
+            rewardDebt: del.rewardDebt,
+            cumulativeRewardPerToken: gw.cumulativeRewardPerToken,
+        });
+        const pendingRewards = live - del.delegatedStake;
+        if (pendingRewards <= minPendingRewards)
+            continue;
+        out.push({
+            gatewayAddress: del.gateway,
+            delegatorAddress: del.delegator,
+            pendingRewards,
+        });
+    }
+    return out;
+}