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

package/lib/esm/solana/ant-writeable.js

@@ -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.
  *
@@ -101,7 +116,7 @@ export class SolanaANTWriteable extends SolanaANTReadable {
         // Per-record metadata (display name / logo / description / keywords)
         // moved out of `set_record` into a dedicated `set_record_metadata`
         // instruction when `AntRecord` was split (ARNS-712). These fields are
-        // not part of `AoANTSetUndernameRecordParams` today, but we keep the
+        // not part of `ANTSetUndernameRecordParams` today, but we keep the
         // forward path here so callers can pass them on the params object and
         // we'll bundle a `set_record_metadata` ix into the same tx.
         const extra = params;
@@ -264,21 +279,37 @@ export class SolanaANTWriteable extends SolanaANTReadable {
         const newOwnerDest = await this.registry.resolveDestinationAclAccounts({
             user: newOwner,
         });
-        // Resolve the old owner's source ACL accounts. The current owner
-        // *must* have a live `(asset, Owner)` entry — every spawn /
-        // import path seeds it, so a missing entry indicates state
-        // corruption. We surface that as `AclEntryNotFound` from the
-        // contract by passing the derived PDAs as a fallback rather than
-        // failing client-side here.
+        // Resolve the old owner's source ACL accounts. If the entry is
+        // missing (e.g. the ANT was acquired via a marketplace transfer or
+        // before the ACL system existed), heal it by bootstrapping the
+        // config/page and recording the owner entry so the on-chain
+        // transfer handler can successfully remove it.
         const oldOwnerSource = await this.registry.resolveSourceAclAccountsForEntry({
             user: oldOwner,
             asset: this.mint,
             role: 'owner',
         });
-        const oldOwnerAclConfigPda = oldOwnerSource?.aclConfigPda ??
-            (await this.registry.deriveAclConfigPda(oldOwner));
-        const oldOwnerAclPagePda = oldOwnerSource?.aclPagePda ??
-            (await this.registry.deriveAclPagePda(oldOwner, 0n));
+        let oldOwnerAclConfigPda;
+        let oldOwnerAclPagePda;
+        const oldOwnerHealIxs = [];
+        if (oldOwnerSource) {
+            oldOwnerAclConfigPda = oldOwnerSource.aclConfigPda;
+            oldOwnerAclPagePda = oldOwnerSource.aclPagePda;
+        }
+        else {
+            const dest = await this.registry.resolveDestinationAclAccounts({
+                user: oldOwner,
+            });
+            oldOwnerAclConfigPda = dest.aclConfigPda;
+            oldOwnerAclPagePda = dest.aclPagePda;
+            oldOwnerHealIxs.push(...dest.prepIxs);
+            oldOwnerHealIxs.push(await this.registry.buildRecordIx({
+                user: oldOwner,
+                asset: this.mint,
+                role: 'owner',
+                pageIdx: dest.pageIdx,
+            }));
+        }
         const transferIx = await getTransferInstructionAsync({
             asset: this.mint,
             caller: this.signer,
@@ -306,6 +337,7 @@ export class SolanaANTWriteable extends SolanaANTReadable {
             controllers: exControllers,
         });
         const sig = await this.sendTransaction([
+            ...oldOwnerHealIxs,
             ...newOwnerDest.prepIxs,
             transferIx,
             ...cleanupIxs,

package/lib/esm/solana/ata.js

@@ -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/esm/solana/canonical-message.js

@@ -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>
@@ -22,8 +40,9 @@
  * - Ethereum: `wallet.signMessage(bytes)` → 65-byte ECDSA + EIP-191 sig
  *   (the wallet applies the EIP-191 prefix; on-chain code re-applies it).
  */
-/** Header literal — must match Rust `CANONICAL_HEADER`. */
-const CANONICAL_HEADER = 'ar.io ant-escrow claim v1';
+import { sha256 } from '@noble/hashes/sha256';
+/** Header literal — must match Rust `ANT_ESCROW_CLAIM_HEADER`. */
+const CANONICAL_HEADER = 'ar.io ant-escrow claim';
 /**
  * Build the canonical claim message bytes. UTF-8 encoded, no trailing
  * newline, exactly the format shown in the docstring.
@@ -37,21 +56,23 @@ export function canonicalMessage(input) {
     }
     const text = `${CANONICAL_HEADER}\n` +
         `network: ${input.network}\n` +
+        `recipient: ${deriveRecipientId(input.recipient)}\n` +
         `ant: ${input.antMint}\n` +
         `claimant: ${input.claimant}\n` +
         `nonce: ${bytesToHexLower(input.nonce)}`;
     return new TextEncoder().encode(text);
 }
-/** Header literal — must match Rust `CANONICAL_HEADER_V2`. */
-const CANONICAL_HEADER_V2 = 'ar.io escrow claim v2';
+/** Header literal — must match Rust `ESCROW_CLAIM_HEADER`. */
+const CANONICAL_HEADER_V2 = 'ar.io escrow claim';
 /**
  * Build the v2 canonical claim message bytes for token/vault escrows.
  * UTF-8 encoded, no trailing newline.
  *
  * 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>
@@ -70,6 +91,7 @@ export function canonicalMessageV2(input) {
     }
     const text = `${CANONICAL_HEADER_V2}\n` +
         `network: ${input.network}\n` +
+        `recipient: ${deriveRecipientId(input.recipient)}\n` +
         `type: ${input.assetType}\n` +
         `asset: ${bytesToHexLower(input.assetId)}\n` +
         `amount: ${input.amount.toString()}\n` +
@@ -80,6 +102,20 @@ export function canonicalMessageV2(input) {
 // =========================================
 // Shared utilities
 // =========================================
+/**
+ * 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 function deriveRecipientId(recipient) {
+    if (recipient.length === 0) {
+        throw new Error('deriveRecipientId: recipient bytes must be non-empty');
+    }
+    // Node's 'base64url' encoding is unpadded — matches the Rust no-pad alphabet.
+    return Buffer.from(sha256(recipient)).toString('base64url');
+}
 /** Lowercase-hex encoding. Matches Rust `encode_hex_lowercase`. */
 export function bytesToHexLower(bytes) {
     let s = '';

package/lib/esm/solana/clusters.js

@@ -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 { 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.
  *
@@ -38,25 +66,44 @@ import { address } from '@solana/kit';
  */
 export 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 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');
+/** ARIO SPL Token mint on Solana mainnet-beta. */
+export const MAINNET_ARIO_MINT = address('DcNnMuFxwhgV4WY1HVSaSEgr92bv2b1vUvEKiNxWqHdF');
+/**
+ * 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 const DEVNET_PROGRAM_IDS = {
-    core: address('83CQLP848zzCgnZ4LTq87g6hvxTooNLX7YXXkUUGv5ig'),
-    gar: address('AF8QAEaR4hzsqeUDwEdeTXMYtdyFegTENBdnJro6WVLR'),
-    arns: address('2HgSCKYjcapJPdHRKqkLrGXm7kvBmCP45ZyhWEm87oM1'),
-    ant: address('8ZMuXhiK7DorjPUg8RB1rzu7CvsABMk38WDJRbM62y2C'),
-    antEscrow: null,
+    core: address('8Njx9wPkXiNzDCgjwVsJFRjpAEV34gGW3n8DzX3V23m1'),
+    gar: address('7WsDTrtZBsfKtnP33XkjuqXCY69JE7n4QVYpynqJCFxz'),
+    arns: address('6EZNezcg4rc5hnh8HG34vGquT3WpW5xXypzPb24uyEpp'),
+    ant: address('DbHbRwUD1oAn1mrDSqtWtvwGcNrmhWdD2g8L4xmeQ7NX'),
+    antEscrow: address('bttco5oAnBwCucG63iKokBJCZmNr493f3Ewe9LM3oTx'),
 };
-/** ARIO SPL Token mint on devnet. */
-export const DEVNET_ARIO_MINT = address('BZ3nczDe8To3c39eN7Beq9FW34BveUcEs9sDNkbGxn4U');
-/** Protocol treasury token account on devnet (owner = ArioConfig PDA). */
-export const DEVNET_TREASURY_TOKEN_ACCOUNT = address('WLh1PNwSg5QstPeATJxD21cb6wvYkj4ibQetkz5RTn3');
-/** Protocol stake token account on devnet (owner = GatewaySettings PDA). */
-export const DEVNET_STAKE_TOKEN_ACCOUNT = address('6vV7qQTf8Bv6SVagLKMSj3dnK7Vv9uaiujpMsHTJ2onF');
+/** ARIO SPL Token mint on devnet (Staging v2). */
+export const DEVNET_ARIO_MINT = address('6vTw5CysRXQ4ybbHkDUiisHWVsBeMtUzYvJqs2iqHyaN');

package/lib/esm/solana/constants.js

@@ -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.
  *
@@ -6,11 +21,12 @@
  */
 import { address } from '@solana/kit';
 // Program IDs — placeholder addresses (replace with deployed program IDs)
-export const ARIO_CORE_PROGRAM_ID = address('ARioCoreProgramXXXXXXXXXXXXXXXXXXXXXXXXXXXXX');
-export const ARIO_GAR_PROGRAM_ID = address('ARioGarProgramXXXXXXXXXXXXXXXXXXXXXXXXXXXXX');
-export const ARIO_ARNS_PROGRAM_ID = address('ARioArnsProgXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX');
-export const ARIO_ANT_PROGRAM_ID = address('ARioAntProgXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX');
-export const ARIO_ANT_ESCROW_PROGRAM_ID = address('ARioAntEscrowXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX');
+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;

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

@@ -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.
+ */
 /**
  * Delegation balance math.
  *
@@ -61,3 +76,37 @@ export function computeLiveDelegationBalance({ delegatedStake, rewardDebt, cumul
     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;
+}