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

package/lib/esm/cli/utils.js

@@ -14,26 +14,17 @@
  * limitations under the License.
  */
 import { readFileSync } from 'fs';
-/**
- * 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.
- */
-import { EthereumSigner } from '@dha-team/arbundles';
-import { connect } from '@permaweb/aoconnect';
+import { address, createKeyPairSignerFromBytes, createSolanaRpcSubscriptions, } from '@solana/kit';
+import bs58 from 'bs58';
 import { program } from 'commander';
 import prompts from 'prompts';
-import { ANT, ANTRegistry, ANT_REGISTRY_ID, ANT_REGISTRY_TESTNET_ID, AOProcess, ARIO, ARIOToken, ARIO_DEVNET_PROCESS_ID, ARIO_MAINNET_PROCESS_ID, ARIO_TESTNET_PROCESS_ID, ArweaveSigner, DEFAULT_CU_URL, Logger, createAoSigner, fromB64Url, fundFromOptions, initANTStateForAddress, isValidFundFrom, isValidIntent, mARIOToken, sha256B64Url, validIntents, } from '../node/index.js';
+import { ANTRegistry } from '../common/ant-registry.js';
+import { ANT } from '../common/ant.js';
+import { ARIO } from '../common/io.js';
+import { Logger } from '../common/logger.js';
+import { createCircuitBreakerRpc, defaultFallbackUrl, } from '../solana/rpc-circuit-breaker.js';
+import { fundFromOptions, isValidFundFrom, isValidIntent, validIntents, } from '../types/io.js';
+import { ARIOToken, mARIOToken } from '../types/token.js';
 import { globalOptions } from './options.js';
 export const defaultTtlSecondsCLI = 3600;
 export function stringifyJsonForCLIDisplay(json) {
@@ -81,46 +72,6 @@ export function makeCommand({ description, name, options = [], action, }) {
     }
     return appliedCommand;
 }
-export function arioProcessIdFromOptions({ arioProcessId, devnet, testnet, }) {
-    if (arioProcessId !== undefined) {
-        return arioProcessId;
-    }
-    if (devnet) {
-        return ARIO_DEVNET_PROCESS_ID;
-    }
-    if (testnet) {
-        return ARIO_TESTNET_PROCESS_ID;
-    }
-    return ARIO_MAINNET_PROCESS_ID;
-}
-export function antRegistryIdFromOptions({ antRegistryProcessId, testnet, }) {
-    if (antRegistryProcessId !== undefined) {
-        return antRegistryProcessId;
-    }
-    if (testnet) {
-        return ANT_REGISTRY_TESTNET_ID;
-    }
-    return ANT_REGISTRY_ID;
-}
-function walletFromOptions({ privateKey, walletFile, }) {
-    if (privateKey !== undefined) {
-        return JSON.parse(privateKey);
-    }
-    if (walletFile !== undefined) {
-        return JSON.parse(readFileSync(walletFile, 'utf-8'));
-    }
-    return undefined;
-}
-export function requiredJwkFromOptions(options) {
-    const jwk = walletFromOptions(options);
-    if (jwk === undefined) {
-        throw new Error('No JWK provided for signing!\nPlease provide a stringified JWK with `--private-key` or the file path of a jwk.json file with `--wallet-file`');
-    }
-    return jwk;
-}
-export function jwkToAddress(jwk) {
-    return sha256B64Url(fromB64Url(jwk.n));
-}
 function setLoggerIfDebug(options) {
     if (options.debug) {
         Logger.default.setLogLevel('debug');
@@ -130,68 +81,107 @@ export function getLoggerFromOptions(options) {
     setLoggerIfDebug(options);
     return Logger.default;
 }
-function aoProcessFromOptions(options) {
-    return new AOProcess({
-        processId: arioProcessIdFromOptions(options),
-        ao: connect({
-            MODE: 'legacy',
-            CU_URL: options.cuUrl,
-        }),
-    });
-}
 export function readARIOFromOptions(options) {
     setLoggerIfDebug(options);
+    const rpcUrl = options.rpcUrl ?? 'https://api.mainnet-beta.solana.com';
     return ARIO.init({
-        hyperbeamUrl: options.hyperbeamUrl,
-        process: aoProcessFromOptions({
-            cuUrl: DEFAULT_CU_URL,
-            ...options,
-        }),
-        paymentUrl: options.paymentUrl,
+        rpc: createCliRpc(rpcUrl),
+        ...(options.coreProgramId
+            ? { coreProgramId: address(options.coreProgramId) }
+            : {}),
+        ...(options.garProgramId
+            ? { garProgramId: address(options.garProgramId) }
+            : {}),
+        ...(options.arnsProgramId
+            ? { arnsProgramId: address(options.arnsProgramId) }
+            : {}),
     });
 }
-export function readANTRegistryFromOptions(options) {
+export async function readANTRegistryFromOptions(options) {
+    setLoggerIfDebug(options);
+    const rpcUrl = options.rpcUrl ?? 'https://api.mainnet-beta.solana.com';
     return ANTRegistry.init({
-        process: aoProcessFromOptions(options),
-        hyperbeamUrl: options.hyperbeamUrl,
+        rpc: createCliRpc(rpcUrl),
+        ...(options.antProgramId
+            ? { antProgramId: address(options.antProgramId) }
+            : {}),
     });
 }
-export function contractSignerFromOptions(options) {
-    const wallet = walletFromOptions(options);
-    if (wallet === undefined) {
-        return undefined;
+/** Derive a WS URL from an HTTP/HTTPS RPC URL by swapping the scheme. */
+function wsUrlFromRpcUrl(rpcUrl) {
+    // Surfpool and `solana-test-validator` follow Solana's well-known localhost
+    // convention: HTTP RPC on 8899 and WebSocket on 8900 (a separate port).
+    // Public RPCs (mainnet/devnet/testnet) put both on the same port (443/443),
+    // so a naive `http→ws` swap works there but breaks against any local
+    // validator. Bump the port iff we recognise the localhost+8899 pair.
+    let url;
+    try {
+        url = new URL(rpcUrl);
     }
-    const token = options.token ?? 'arweave';
-    if (token === 'ethereum') {
-        const signer = new EthereumSigner(wallet);
-        // For EthereumSigner, we need to convert the JWK to a string
-        return { signer, signerAddress: signer.publicKey.toString('hex') };
+    catch {
+        return rpcUrl.replace(/^http/, 'ws');
     }
-    // TODO: Support other wallet types
-    const signer = new ArweaveSigner(wallet);
-    return { signer, signerAddress: jwkToAddress(wallet) };
-}
-export function requiredContractSignerFromOptions(options) {
-    const contractSigner = contractSignerFromOptions(options);
-    if (contractSigner === undefined) {
-        throw new Error('No signer provided for signing!\nPlease provide a stringified JWK or Ethereum private key with `--private-key` or the file path of an arweave.jwk.json or eth.private.key.txt file with `--wallet-file`');
+    const isLocalhost = url.hostname === 'localhost' ||
+        url.hostname === '127.0.0.1' ||
+        url.hostname === '0.0.0.0';
+    if (isLocalhost && url.port === '8899') {
+        url.port = '8900';
     }
-    return contractSigner;
+    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+    return url.toString().replace(/\/$/, '');
+}
+/**
+ * Create a {@link SolanaRpc} wrapped with a circuit-breaker that falls back to
+ * the cluster's public RPC when the primary endpoint becomes unhealthy.
+ */
+function createCliRpc(rpcUrl) {
+    return createCircuitBreakerRpc({
+        primaryUrl: rpcUrl,
+        fallbackUrl: defaultFallbackUrl(rpcUrl),
+    });
 }
-export function requiredAoSignerFromOptions(options) {
-    return createAoSigner(requiredContractSignerFromOptions(options).signer);
+/**
+ * Load a Solana KeyPairSigner from --private-key (base58) or --wallet-file
+ * (JSON array of bytes). Throws with a helpful message if neither is set.
+ */
+async function loadSolanaSignerFromOptions(options) {
+    let secretKey;
+    if (options.privateKey) {
+        secretKey = bs58.decode(options.privateKey);
+    }
+    else if (options.walletFile) {
+        const raw = readFileSync(options.walletFile, 'utf-8');
+        secretKey = new Uint8Array(JSON.parse(raw));
+    }
+    else {
+        throw new Error('Solana write operations require a signer.\n' +
+            'Provide a Solana keypair with --wallet-file <path-to-keypair.json> ' +
+            'or --private-key <base58-encoded-key>');
+    }
+    return createKeyPairSignerFromBytes(secretKey);
 }
-export function writeARIOFromOptions(options) {
-    const { signer, signerAddress } = requiredContractSignerFromOptions(options);
+export async function writeARIOFromOptions(options) {
     setLoggerIfDebug(options);
+    const rpcUrl = options.rpcUrl ?? 'https://api.mainnet-beta.solana.com';
+    const signer = await loadSolanaSignerFromOptions(options);
     return {
         ario: ARIO.init({
-            process: aoProcessFromOptions(options),
+            rpc: createCliRpc(rpcUrl),
+            rpcSubscriptions: createSolanaRpcSubscriptions(wsUrlFromRpcUrl(rpcUrl)),
             signer,
-            paymentUrl: options.paymentUrl,
-            hyperbeamUrl: options.hyperbeamUrl,
+            // Forward program-id overrides so localnet / devnet writes target the
+            // deployed program IDs instead of falling back to mainnet defaults.
+            ...(options.coreProgramId
+                ? { coreProgramId: address(options.coreProgramId) }
+                : {}),
+            ...(options.garProgramId
+                ? { garProgramId: address(options.garProgramId) }
+                : {}),
+            ...(options.arnsProgramId
+                ? { arnsProgramId: address(options.arnsProgramId) }
+                : {}),
         }),
-        signerAddress,
+        signerAddress: signer.address,
     };
 }
 export function formatARIOWithCommas(value) {
@@ -205,14 +195,51 @@ export function formatARIOWithCommas(value) {
 export function formatMARIOToARIOWithCommas(value) {
     return formatARIOWithCommas(value.toARIO());
 }
-/** helper to get address from --address option first, then check wallet options  */
+/**
+ * Resolve the wallet address from CLI options. Priority order:
+ *   1. `--address <addr>` — used verbatim.
+ *   2. `--wallet-file <path-to-keypair.json>` — derive the Solana pubkey
+ *      from the keypair file (last 32 bytes of the 64-byte secret-key
+ *      array are the public key; base58-encode them).
+ *   3. `--private-key <base58-secret>` — base58-decode the secret, take
+ *      the trailing 32 bytes as the pubkey. Matches the keypair-file
+ *      path; kept aligned with `loadSolanaSignerFromOptions` so cost
+ *      / funding lookups work even when the user authenticates with
+ *      only a private key.
+ *
+ * Returns `undefined` when none of those is set. Use
+ * `requiredAddressFromOptions` for callers that must have an address.
+ */
 export function addressFromOptions(options) {
     if (options.address !== undefined) {
         return options.address;
     }
-    const signer = contractSignerFromOptions(options);
-    if (signer !== undefined) {
-        return signer.signerAddress;
+    if (options.walletFile !== undefined) {
+        try {
+            const raw = readFileSync(options.walletFile, 'utf-8');
+            const bytes = new Uint8Array(JSON.parse(raw));
+            // Solana keypair JSON files are a 64-byte Uint8Array: first 32 bytes
+            // are the seed/secret, last 32 bytes are the Ed25519 public key.
+            if (bytes.length !== 64) {
+                throw new Error(`Wallet file is ${bytes.length} bytes — expected 64-byte Solana keypair JSON`);
+            }
+            return bs58.encode(bytes.slice(32));
+        }
+        catch (err) {
+            throw new Error(`Failed to read Solana pubkey from --wallet-file '${options.walletFile}': ${err.message}`);
+        }
+    }
+    if (options.privateKey !== undefined) {
+        try {
+            const bytes = bs58.decode(options.privateKey);
+            if (bytes.length !== 64) {
+                throw new Error(`Decoded private key is ${bytes.length} bytes — expected 64 (32-byte secret + 32-byte pubkey)`);
+            }
+            return bs58.encode(bytes.slice(32));
+        }
+        catch (err) {
+            throw new Error(`Failed to derive Solana pubkey from --private-key: ${err.message}`);
+        }
     }
     return undefined;
 }
@@ -303,44 +330,8 @@ export function customTagsFromOptions(options) {
         tags,
     };
 }
-export function servicesFromOptions(services) {
-    if (services === undefined || services === null || services === '') {
-        return undefined;
-    }
-    try {
-        const parsed = JSON.parse(services);
-        // Validate structure
-        if (!parsed.bundlers || !Array.isArray(parsed.bundlers)) {
-            throw new Error('Services must have a "bundlers" array');
-        }
-        if (parsed.bundlers.length > 20) {
-            throw new Error('Maximum 20 bundlers allowed');
-        }
-        // Validate each bundler
-        for (const bundler of parsed.bundlers) {
-            if (!bundler.fqdn || typeof bundler.fqdn !== 'string') {
-                throw new Error('Each bundler must have a valid "fqdn" string');
-            }
-            if (typeof bundler.port !== 'number' ||
-                bundler.port < 0 ||
-                bundler.port > 65535) {
-                throw new Error('Each bundler must have a valid "port" (0-65535)');
-            }
-            if (bundler.protocol !== 'https') {
-                throw new Error('Each bundler protocol must be "https"');
-            }
-            if (!bundler.path || typeof bundler.path !== 'string') {
-                throw new Error('Each bundler must have a valid "path" string');
-            }
-        }
-        return parsed;
-    }
-    catch (error) {
-        throw new Error(`Invalid services JSON: ${error instanceof Error ? error.message : String(error)}`);
-    }
-}
 export function gatewaySettingsFromOptions(options) {
-    const { allowDelegatedStaking, autoStake, delegateRewardShareRatio, fqdn, label, minDelegatedStake, note, observerAddress, port, properties, allowedDelegates, services, } = options;
+    const { allowDelegatedStaking, autoStake, delegateRewardShareRatio, fqdn, label, minDelegatedStake, note, observerAddress, port, properties, allowedDelegates, } = options;
     return {
         observerAddress,
         allowDelegatedStaking,
@@ -355,7 +346,6 @@ export function gatewaySettingsFromOptions(options) {
         note,
         port: port !== undefined ? +port : undefined,
         properties,
-        services: servicesFromOptions(services),
     };
 }
 export function requiredTargetAndQuantityFromOptions(options) {
@@ -444,27 +434,27 @@ export function requiredProcessIdFromOptions(o) {
     }
     return o.processId;
 }
-function ANTProcessFromOptions(options) {
-    return new AOProcess({
-        processId: requiredProcessIdFromOptions(options),
-        ao: connect({
-            MODE: 'legacy',
-            CU_URL: options.cuUrl,
-        }),
-    });
-}
-export function readANTFromOptions(options) {
+export async function readANTFromOptions(options) {
+    const rpcUrl = options.rpcUrl ?? 'https://api.mainnet-beta.solana.com';
     return ANT.init({
-        process: ANTProcessFromOptions(options),
-        hyperbeamUrl: options.hyperbeamUrl,
+        processId: requiredProcessIdFromOptions(options),
+        rpc: createCliRpc(rpcUrl),
+        ...(options.antProgramId
+            ? { antProgramId: address(options.antProgramId) }
+            : {}),
     });
 }
-export function writeANTFromOptions(options, signer) {
-    signer ??= requiredContractSignerFromOptions(options).signer;
+export async function writeANTFromOptions(options) {
+    const rpcUrl = options.rpcUrl ?? 'https://api.mainnet-beta.solana.com';
+    const kitSigner = await loadSolanaSignerFromOptions(options);
     return ANT.init({
-        process: ANTProcessFromOptions(options),
-        signer,
-        hyperbeamUrl: options.hyperbeamUrl,
+        processId: requiredProcessIdFromOptions(options),
+        rpc: createCliRpc(rpcUrl),
+        rpcSubscriptions: createSolanaRpcSubscriptions(wsUrlFromRpcUrl(rpcUrl)),
+        signer: kitSigner,
+        ...(options.antProgramId
+            ? { antProgramId: address(options.antProgramId) }
+            : {}),
     });
 }
 export function booleanFromOptions(options, key) {
@@ -512,19 +502,55 @@ export function requiredPositiveIntegerFromOptions(options, key) {
     }
     return value;
 }
-export function getANTStateFromOptions(options) {
-    return initANTStateForAddress({
-        owner: requiredAddressFromOptions(options),
-        targetId: options.target,
-        controllers: options.controllers,
-        description: options.description,
-        ticker: options.ticker,
-        name: options.name,
-        keywords: options.keywords,
-        logo: options.logo,
-        ttlSeconds: options.ttlSeconds !== undefined
-            ? +options.ttlSeconds
-            : defaultTtlSecondsCLI,
+/**
+ * Spawn a fresh ANT on Solana from CLI options.
+ *
+ * Resolves the signer the same way `writeARIOFromOptions` does (KeyPairSigner
+ * from `--wallet-file` or `--private-key`), then bundles MPL Core `CreateV1` +
+ * `ario_ant::initialize` into a single transaction. The signer's address
+ * becomes the ANT owner on chain — no separate `--address` is required.
+ *
+ * Maps the user-facing options (`--name`, `--ticker`, `--description`,
+ * `--keywords`, `--logo`, `--target` for the @ record tx id) onto the Solana
+ * `InitializeAntParams` payload.
+ */
+export async function spawnSolanaANTFromOptions(options) {
+    setLoggerIfDebug(options);
+    const { spawnSolanaANT } = await import('../solana/spawn-ant.js');
+    const rpcUrl = options.rpcUrl ?? 'https://api.mainnet-beta.solana.com';
+    const kitSigner = await loadSolanaSignerFromOptions(options);
+    const name = options.name ?? `ANT-${kitSigner.address.slice(0, 8)}`;
+    // ANT NFT metadata URI — required so the asset renders correctly in
+    // marketplaces. Caller must upload a JSON metadata file (build via
+    // `buildAntMetadata` from `@ar.io/sdk/solana`, host on Arweave via Turbo
+    // or any other gateway) and pass the resulting URI here.
+    const metadataUri = options.metadataUri;
+    if (!metadataUri || typeof metadataUri !== 'string') {
+        throw new Error('spawn-ant: --metadata-uri is required.\n\n' +
+            'Build the JSON metadata with `buildAntMetadata` from `@ar.io/sdk/solana`,\n' +
+            'upload it to Arweave (free for files under 100 KiB via @ardrive/turbo-sdk\n' +
+            'with a `HexSolanaSigner`), then pass the resulting URI:\n' +
+            '  --metadata-uri "ar://<txid>"            (canonical AR.IO scheme)\n' +
+            '  --metadata-uri "https://<gateway>/raw/<txid>"   (immediate render)\n\n' +
+            'See sdk/scripts/devnet-validation/populate-ant.ts for an end-to-end example.');
+    }
+    return spawnSolanaANT({
+        rpc: createCliRpc(rpcUrl),
+        rpcSubscriptions: createSolanaRpcSubscriptions(wsUrlFromRpcUrl(rpcUrl)),
+        signer: kitSigner,
+        state: {
+            name,
+            uri: metadataUri,
+            ticker: options.ticker,
+            description: options.description,
+            keywords: options.keywords,
+            logo: options.logo,
+            // `--target` carries the @ record's tx id for the initial record.
+            transactionId: options.target,
+        },
+        ...(options.antProgramId
+            ? { antProgramId: address(options.antProgramId) }
+            : {}),
     });
 }
 export function getTokenCostParamsFromOptions(o) {
@@ -557,6 +583,86 @@ export function fundFromFromOptions(o) {
 export function referrerFromOptions(o) {
     return o.referrer;
 }
+/** Parse `--withdrawal-id` from CLI options into a bigint. */
+export function withdrawalIdFromOptions(o) {
+    if (o.withdrawalId === undefined)
+        return undefined;
+    try {
+        return BigInt(o.withdrawalId);
+    }
+    catch {
+        throw new Error(`Invalid --withdrawal-id: '${o.withdrawalId}' is not a valid u64 integer`);
+    }
+}
+/**
+ * Parse `--funding-plan-json` into a `FundingSourceSpec[]`. Validates each
+ * entry's `kind` against the on-chain enum and parses `amount` as a bigint.
+ * Each Delegation/OperatorStake entry MAY carry a `gateway` field (base58
+ * Solana address) — required when the plan spans multiple gateways.
+ *
+ * Format examples:
+ *   '[{"kind":"balance","amount":"100"},{"kind":"withdrawal","amount":"500"}]'
+ *   '[{"kind":"delegation","amount":"100","gateway":"Gw1..."},{"kind":"delegation","amount":"50","gateway":"Gw2..."}]'
+ *
+ * Returns undefined when the flag isn't set; throws Error on malformed JSON
+ * or unknown kinds.
+ */
+export function fundingPlanFromOptions(o) {
+    if (!o.fundingPlanJson)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(o.fundingPlanJson);
+    }
+    catch (err) {
+        throw new Error(`--funding-plan-json is not valid JSON: ${err.message}`);
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error('--funding-plan-json must be a JSON array');
+    }
+    const validKinds = new Set([
+        'balance',
+        'delegation',
+        'operatorStake',
+        'withdrawal',
+    ]);
+    return parsed.map((entry, idx) => {
+        if (typeof entry !== 'object' ||
+            entry === null ||
+            typeof entry.kind !== 'string' ||
+            typeof entry.amount !== 'string') {
+            throw new Error(`--funding-plan-json[${idx}] must be { kind: string, amount: string, gateway?: string }`);
+        }
+        const e = entry;
+        if (!validKinds.has(e.kind)) {
+            throw new Error(`--funding-plan-json[${idx}].kind must be one of ${[...validKinds].join(', ')} (got '${e.kind}')`);
+        }
+        let amount;
+        try {
+            amount = BigInt(e.amount);
+        }
+        catch {
+            throw new Error(`--funding-plan-json[${idx}].amount '${e.amount}' is not a valid u64`);
+        }
+        if (amount <= 0n) {
+            throw new Error(`--funding-plan-json[${idx}].amount must be > 0 (got ${e.amount})`);
+        }
+        const out = {
+            kind: e.kind,
+            amount,
+        };
+        if (e.gateway !== undefined) {
+            if (typeof e.gateway !== 'string') {
+                throw new Error(`--funding-plan-json[${idx}].gateway must be a base58 Solana address`);
+            }
+            if (e.kind !== 'delegation' && e.kind !== 'operatorStake') {
+                throw new Error(`--funding-plan-json[${idx}].gateway is only valid for kind 'delegation' or 'operatorStake' (got '${e.kind}')`);
+            }
+            out.gateway = e.gateway;
+        }
+        return out;
+    });
+}
 export function assertLockLengthInRange(lockLengthMs, assertMin = true) {
     const minLockLengthMs = 1209600000; // 14 days
     const maxLockLengthMs = 378432000000; // ~12 years