@ar.io/sdk 4.0.0-solana.9 → 4.0.0

package/lib/types/solana/ant-writeable.d.ts

@@ -1,3 +1,18 @@
+/**
+ * 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 implementation of ANT (Arweave Name Token) write interface.
  *
@@ -29,9 +44,9 @@
  */
 import { type Address, type Commitment, type Instruction } from '@solana/kit';
 import type { ILogger } from '../common/logger.js';
-import type { AoANTRegistryRead } from '../types/ant-registry.js';
-import type { AoANTSetBaseNameRecordParams, AoANTSetUndernameRecordParams } from '../types/ant.js';
-import type { AoMessageResult, WriteOptions } from '../types/common.js';
+import type { ANTRegistryRead } from '../types/ant-registry.js';
+import type { ANTSetBaseNameRecordParams, ANTSetUndernameRecordParams } from '../types/ant.js';
+import type { MessageResult, WriteOptions } from '../types/common.js';
 import { SolanaANTReadable } from './ant-readable.js';
 import { SolanaANTRegistryWriteable } from './ant-registry-writeable.js';
 import type { SolanaRpc, SolanaRpcSubscriptions, SolanaSigner } from './types.js';
@@ -63,9 +78,9 @@ export declare class SolanaANTWriteable extends SolanaANTReadable {
      * Override the readable's registry with the writeable variant — gives
      * us the preflight resolvers + the spawn / ex-controller workflow
      * helpers, while preserving `accessControlList` reads from the
-     * parent's `AoANTRegistryRead` surface.
+     * parent's `ANTRegistryRead` surface.
      */
-    readonly registry: SolanaANTRegistryWriteable & AoANTRegistryRead;
+    readonly registry: SolanaANTRegistryWriteable & ANTRegistryRead;
     constructor(config: {
         rpc: SolanaRpc;
         rpcSubscriptions: SolanaRpcSubscriptions;
@@ -93,63 +108,63 @@ export declare class SolanaANTWriteable extends SolanaANTReadable {
      * doesn't need its own ACL plumbing.
      */
     protected sendTransaction(instructions: Instruction[]): Promise<string>;
-    setRecord(params: AoANTSetUndernameRecordParams, _options?: WriteOptions): Promise<AoMessageResult>;
-    setBaseNameRecord(params: AoANTSetBaseNameRecordParams, options?: WriteOptions): Promise<AoMessageResult>;
-    setUndernameRecord(params: AoANTSetUndernameRecordParams, options?: WriteOptions): Promise<AoMessageResult>;
+    setRecord(params: ANTSetUndernameRecordParams, _options?: WriteOptions): Promise<MessageResult>;
+    setBaseNameRecord(params: ANTSetBaseNameRecordParams, options?: WriteOptions): Promise<MessageResult>;
+    setUndernameRecord(params: ANTSetUndernameRecordParams, options?: WriteOptions): Promise<MessageResult>;
     removeRecord(params: {
         undername: string;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     removeUndernameRecord(params: {
         undername: string;
-    }, options?: WriteOptions): Promise<AoMessageResult>;
+    }, options?: WriteOptions): Promise<MessageResult>;
     transferRecord(params: {
         undername: string;
         recipient: string;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     addController(params: {
         controller: string;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     removeController(params: {
         controller: string;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     setName(params: {
         name: string;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     setTicker(params: {
         ticker: string;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     setDescription(params: {
         description: string;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     setKeywords(params: {
         keywords: string[];
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     setLogo(params: {
         txId: string;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     transfer(params: {
         target: string;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
-    reconcile(_options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
+    reconcile(_options?: WriteOptions): Promise<MessageResult>;
     releaseName(_params: {
         name: string;
         arioProcessId: string;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     reassignName(_params: {
         name: string;
         arioProcessId: string;
         antProcessId: string;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     approvePrimaryNameRequest(_params: {
         name: string;
         address: string;
         arioProcessId: string;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     removePrimaryNames(_params: {
         names: string[];
         arioProcessId: string;
         notifyOwners?: boolean;
-    }, _options?: WriteOptions): Promise<AoMessageResult>;
+    }, _options?: WriteOptions): Promise<MessageResult>;
     /**
      * Migrate this ANT's on-chain state to the latest schema version.
      * On Solana, "upgrade" means per-ANT data migration, not process forking.

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

@@ -1,3 +1,18 @@
+/**
+ * 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.
+ */
 /**
  * Associated Token Account derivation, kit-native.
  * Mirrors the classic SPL `getAssociatedTokenAddress` function but returns

package/lib/types/solana/canonical-message.d.ts

@@ -1,17 +1,35 @@
+/**
+ * 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.
+ */
 /**
  * Canonical claim-message helper for `ario-ant-escrow`.
  *
  * Produces the EXACT bytes a recipient signs to release an escrowed
  * ANT. Output MUST be byte-identical to the Rust implementation in
- * `contracts/programs/ario-ant-escrow/src/canonical.rs::build_canonical_message`.
- * Cross-language equivalence is asserted by `canonical-message.test.ts`
- * which spawns the Rust `canonical` example binary and diffs the bytes.
+ * `ario-ant-escrow/src/canonical.rs::build_ant_escrow_claim_message`
+ * (header `ANT_ESCROW_CLAIM_HEADER = "ar.io ant-escrow claim"`). The on-chain
+ * program reconstructs these exact bytes and verifies the signature against
+ * them, so any drift (header, field set, or ordering) makes every claim fail
+ * `EthereumAddressMismatch` / signature verification.
  *
  * Format (UTF-8, line-feed separated, no trailing newline):
  *
  * ```text
- * ar.io ant-escrow claim v1
+ * ar.io ant-escrow claim
  * network: <network>
+ * recipient: <base64url(sha256(recipient_pubkey)) — 43 chars, no pad>
  * ant: <ant_mint_base58>
  * claimant: <claimant_solana_pubkey_base58>
  * nonce: <nonce_hex_lowercase>
@@ -35,6 +53,12 @@ export interface CanonicalMessageInput {
     /** Solana pubkey that will receive the ANT on claim. Bound into the
      *  signature so front-runners can't redirect. */
     claimant: Address;
+    /** Recipient identity pubkey bytes the deposit targeted (ETH 20-byte
+     *  address, Solana 32-byte pubkey, or Arweave RSA modulus). Bound into the
+     *  message as `recipient: base64url(sha256(bytes))` to match the contract's
+     *  `derive_recipient_id_b64url`. REQUIRED — the program reconstructs this
+     *  line, so omitting it makes the claim mismatch. */
+    recipient: Uint8Array;
     /** 32-byte anti-replay nonce — read from the EscrowAnt account. */
     nonce: Uint8Array;
 }
@@ -57,6 +81,12 @@ export interface CanonicalMessageV2Input {
     amount: bigint;
     /** Solana pubkey that will receive the tokens on claim. */
     claimant: Address;
+    /** Recipient identity pubkey bytes the deposit targeted (ETH 20-byte
+     *  address, Solana 32-byte pubkey, or Arweave RSA modulus). Bound into the
+     *  message as `recipient: base64url(sha256(bytes))` to match the contract's
+     *  `derive_recipient_id_b64url`. REQUIRED — the program reconstructs this
+     *  line, so omitting it makes the claim mismatch. */
+    recipient: Uint8Array;
     /** 32-byte anti-replay nonce — read from the EscrowToken account. */
     nonce: Uint8Array;
 }
@@ -66,8 +96,9 @@ export interface CanonicalMessageV2Input {
  *
  * Format:
  * ```text
- * ar.io escrow claim v2
+ * ar.io escrow claim
  * network: <network>
+ * recipient: <base64url(sha256(recipient_pubkey)) — 43 chars, no pad>
  * type: <token|vault>
  * asset: <asset_id_hex_lowercase_64chars>
  * amount: <u64_decimal>
@@ -78,5 +109,13 @@ export interface CanonicalMessageV2Input {
  * @throws if `assetId` or `nonce` aren't exactly 32 bytes.
  */
 export declare function canonicalMessageV2(input: CanonicalMessageV2Input): Uint8Array;
+/**
+ * Recipient identity bound into the claim message — `base64url(sha256(bytes))`
+ * with no padding (32-byte hash → 43 chars). Byte-identical to the contract's
+ * `canonical.rs::derive_recipient_id_b64url`. Input is the recipient pubkey
+ * bytes the deposit targeted (ETH 20-byte address / Solana 32-byte pubkey /
+ * Arweave RSA modulus, etc.).
+ */
+export declare function deriveRecipientId(recipient: Uint8Array): string;
 /** Lowercase-hex encoding. Matches Rust `encode_hex_lowercase`. */
 export declare function bytesToHexLower(bytes: Uint8Array): string;

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

@@ -1,14 +1,34 @@
+/**
+ * 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.
  *
- * Mainnet IDs are baked into the IDL at codegen time and surfaced via the
- * placeholder constants in `./constants.ts` (e.g. `ARIO_CORE_PROGRAM_ID`).
- * This module exposes the same values for *other* clusters where the
- * programs are deployed at non-default addresses — primarily devnet.
+ * 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`.
  *
- * Source of truth: `/devnet-config.json` at the repo root. Keep these
- * exports in sync when devnet is redeployed; the bundled drift test
- * (`clusters.test.ts`) will fail CI on mismatch.
+ * 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
@@ -29,6 +49,14 @@
  * ```
  */
 import { type 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 declare const MAINNET_RPC_URL = "https://api.mainnet-beta.solana.com";
 /**
  * Default JSON-RPC URL for the Solana devnet cluster.
  *
@@ -38,25 +66,44 @@ import { type Address } from '@solana/kit';
  */
 export declare const DEVNET_RPC_URL = "https://api.devnet.solana.com";
 /**
- * AR.IO program IDs deployed on Solana devnet.
+ * AR.IO program IDs deployed on Solana mainnet-beta.
  *
  * Shape matches the `programIds` argument of
  * `ARIO.init({ backend: 'solana', programIds, ... })`.
+ */
+export declare const MAINNET_PROGRAM_IDS: {
+    readonly core: Address<"73YoECm6NKXpVRoe5f1Q9BcP5DJGPFUjnFy6AxBE5Nvh">;
+    readonly gar: Address<"89fNiiwgpFSPHKuqfNUkgYTYjtAJAhyqHjXmgXeppGpf">;
+    readonly arns: Address<"2yCUx5edFvUrkibYaUa2ZXWyx9kuJkS8CwyzsgHPWdZZ">;
+    readonly ant: Address<"2MWexMHfMhGJwMHv9Qm9YAVCqjUFUJwDJAysW4oCUGk5">;
+    readonly 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 declare const MAINNET_ATTESTOR_PUBKEY: Address;
+/**
+ * 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 declare const MAINNET_AUTHORITY_PUBKEY: Address;
+/** ARIO SPL Token mint on Solana mainnet-beta. */
+export declare const MAINNET_ARIO_MINT: Address;
+/**
+ * AR.IO program IDs deployed on Solana devnet (staging).
  *
- * `antEscrow` is `null` because `ario-ant-escrow` is not deployed on
- * devnet — the `sol_big_mod_exp` syscall it depends on is inactive on
- * all public clusters today.
+ * Shape matches the `programIds` argument of
+ * `ARIO.init({ backend: 'solana', programIds, ... })`.
  */
 export declare const DEVNET_PROGRAM_IDS: {
-    readonly core: Address<"83CQLP848zzCgnZ4LTq87g6hvxTooNLX7YXXkUUGv5ig">;
-    readonly gar: Address<"AF8QAEaR4hzsqeUDwEdeTXMYtdyFegTENBdnJro6WVLR">;
-    readonly arns: Address<"2HgSCKYjcapJPdHRKqkLrGXm7kvBmCP45ZyhWEm87oM1">;
-    readonly ant: Address<"8ZMuXhiK7DorjPUg8RB1rzu7CvsABMk38WDJRbM62y2C">;
-    readonly antEscrow: Address | null;
+    readonly core: Address<"8Njx9wPkXiNzDCgjwVsJFRjpAEV34gGW3n8DzX3V23m1">;
+    readonly gar: Address<"7WsDTrtZBsfKtnP33XkjuqXCY69JE7n4QVYpynqJCFxz">;
+    readonly arns: Address<"6EZNezcg4rc5hnh8HG34vGquT3WpW5xXypzPb24uyEpp">;
+    readonly ant: Address<"DbHbRwUD1oAn1mrDSqtWtvwGcNrmhWdD2g8L4xmeQ7NX">;
+    readonly antEscrow: Address<"bttco5oAnBwCucG63iKokBJCZmNr493f3Ewe9LM3oTx">;
 };
-/** ARIO SPL Token mint on devnet. */
+/** ARIO SPL Token mint on devnet (Staging v2). */
 export declare const DEVNET_ARIO_MINT: Address;
-/** Protocol treasury token account on devnet (owner = ArioConfig PDA). */
-export declare const DEVNET_TREASURY_TOKEN_ACCOUNT: Address;
-/** Protocol stake token account on devnet (owner = GatewaySettings PDA). */
-export declare const DEVNET_STAKE_TOKEN_ACCOUNT: Address;

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

@@ -1,3 +1,18 @@
+/**
+ * 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.
  *
@@ -10,6 +25,7 @@ export declare const ARIO_GAR_PROGRAM_ID: Address;
 export declare const ARIO_ARNS_PROGRAM_ID: Address;
 export declare const ARIO_ANT_PROGRAM_ID: Address;
 export declare const ARIO_ANT_ESCROW_PROGRAM_ID: Address;
+export declare const ARIO_TOKEN_MINT_ADDRESS: Address;
 export declare const MPL_CORE_PROGRAM_ID: Address;
 export declare const TOKEN_DECIMALS = 6;
 export declare const ONE_TOKEN = 1000000;

package/lib/types/solana/delegation-math.d.ts

@@ -18,3 +18,28 @@ export declare function computeLiveDelegationBalance({ delegatedStake, rewardDeb
     rewardDebt: bigint;
     cumulativeRewardPerToken: bigint;
 }): number;
+/**
+ * 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 declare function selectCompoundableDelegations(delegations: Array<{
+    gateway: string;
+    delegator: string;
+    delegatedStake: number;
+    rewardDebt: bigint;
+}>, gatewaysByOperator: Map<string, {
+    cumulativeRewardPerToken: bigint;
+    status: string;
+}>, minPendingRewards?: number): Array<{
+    gatewayAddress: string;
+    delegatorAddress: string;
+    pendingRewards: number;
+}>;