@ar.io/sdk 3.24.0 → 4.0.0-solana.10

package/lib/esm/cli/options.js

@@ -53,6 +53,69 @@ export const optionMap = {
         alias: '--hyperbeam-url <hyperbeamUrl>',
         description: 'The URL for a custom hyperbeam node',
     },
+    ao: {
+        alias: '--ao',
+        description: 'Use the legacy AO backend instead of Solana',
+        type: 'boolean',
+    },
+    rpcUrl: {
+        alias: '--rpc-url <rpcUrl>',
+        description: 'Solana RPC URL (defaults to mainnet-beta)',
+    },
+    antProgramId: {
+        alias: '--ant-program-id <antProgramId>',
+        description: 'Override the ario-ant program id (Solana backend). Defaults to the SDK-bundled mainnet id; ' +
+            'set this when querying localnet/devnet (see migration/localnet/out/localnet.env -> ARIO_ANT_PROGRAM_ID).',
+    },
+    coreProgramId: {
+        alias: '--core-program-id <coreProgramId>',
+        description: 'Override the ario-core program id (Solana backend). See ARIO_CORE_PROGRAM_ID in localnet.env.',
+    },
+    garProgramId: {
+        alias: '--gar-program-id <garProgramId>',
+        description: 'Override the ario-gar program id (Solana backend). See ARIO_GAR_PROGRAM_ID in localnet.env.',
+    },
+    arnsProgramId: {
+        alias: '--arns-program-id <arnsProgramId>',
+        description: 'Override the ario-arns program id (Solana backend). See ARIO_ARNS_PROGRAM_ID in localnet.env.',
+    },
+    escrowProgramId: {
+        alias: '--escrow-program-id <escrowProgramId>',
+        description: 'Override the ario-ant-escrow program id. Defaults to the SDK-bundled placeholder; ' +
+            'set when running against a deployed devnet/mainnet instance.',
+    },
+    ant: {
+        alias: '--ant <antMint>',
+        description: 'The Metaplex Core ANT mint pubkey (base58)',
+    },
+    recipientArweave: {
+        alias: '--recipient-arweave <jwkFile>',
+        description: 'Path to an Arweave JWK file. The "n" field (RSA-4096 modulus) is used as the escrow recipient identity.',
+    },
+    recipientEthereum: {
+        alias: '--recipient-ethereum <0xAddress>',
+        description: 'A 0x-prefixed Ethereum address to use as the escrow recipient identity.',
+    },
+    newRecipientArweave: {
+        alias: '--new-recipient-arweave <jwkFile>',
+        description: 'New Arweave JWK file (for `escrow update-recipient`).',
+    },
+    newRecipientEthereum: {
+        alias: '--new-recipient-ethereum <0xAddress>',
+        description: 'New Ethereum address (for `escrow update-recipient`).',
+    },
+    signatureFile: {
+        alias: '--signature-file <path>',
+        description: 'Path to a binary signature file (512 bytes for Arweave PSS, 65 bytes for Ethereum r||s||v).',
+    },
+    saltLen: {
+        alias: '--salt-len <bytes>',
+        description: 'PSS salt length (Arweave only; defaults to 32, the wallet-default).',
+    },
+    claimant: {
+        alias: '--claimant <pubkey>',
+        description: 'Solana pubkey that will receive the ANT on claim.',
+    },
     cuUrl: {
         alias: '--cu-url <cuUrl>',
         description: 'The URL for a custom compute unit',
@@ -236,7 +299,11 @@ export const optionMap = {
     },
     transactionId: {
         alias: '--transaction-id <transactionId>',
-        description: 'The transaction ID to interact with',
+        description: 'The content target (Arweave TX ID, IPFS CID, etc.)',
+    },
+    targetProtocol: {
+        alias: '--target-protocol <targetProtocol>',
+        description: 'Storage protocol for the target: "arweave" (default) or "ipfs"',
     },
     ttlSeconds: {
         alias: '--ttl-seconds <ttlSeconds>',
@@ -275,7 +342,31 @@ export const optionMap = {
     },
     fundFrom: {
         alias: '--fund-from <fundFrom>',
-        description: 'Where to fund the action from. e.g. "balance", "stakes", or "any',
+        description: 'Funding source: balance | stakes | withdrawal | plan | any | turbo. ' +
+            "'stakes' requires --gateway-address (uses delegation; add --fund-as-operator " +
+            "for operator stake). 'withdrawal' requires --withdrawal-id. 'plan' / 'any' " +
+            'use the multi-source funding plan (see --funding-plan-json or auto-discover).',
+    },
+    gatewayAddress: {
+        alias: '--gateway-address <gatewayAddress>',
+        description: 'Gateway operator address for funding from stakes. Required when --fund-from is "stakes"',
+    },
+    fundAsOperator: {
+        alias: '--fund-as-operator',
+        description: 'Fund from operator stake instead of delegation (default: delegation)',
+        type: 'boolean',
+    },
+    withdrawalId: {
+        alias: '--withdrawal-id <withdrawalId>',
+        description: 'Withdrawal vault id (u64) — required when --fund-from is "withdrawal" (Solana). ' +
+            'Find with `ar.io listMyWithdrawals` or query Withdrawal PDAs directly.',
+    },
+    fundingPlanJson: {
+        alias: '--funding-plan-json <json>',
+        description: 'Explicit funding plan as JSON: [{"kind":"balance","amount":"100"},...]. ' +
+            "Used when --fund-from is 'plan' or 'any' to bypass auto-discovery. " +
+            "kind is 'balance' | 'delegation' | 'operatorStake' | 'withdrawal'; " +
+            'amount is a string-encoded mARIO bigint. Sum must equal the operation cost.',
     },
     revokable: {
         alias: '--revokable',
@@ -307,6 +398,10 @@ export const optionMap = {
         alias: '--module <module>',
         description: 'The module ID to use for spawning the ANT process',
     },
+    metadataUri: {
+        alias: '--metadata-uri <metadataUri>',
+        description: 'Solana spawn-ant only: URI baked into the Metaplex Core asset (e.g. "ar://<txid>" or "https://<gateway>/raw/<txid>"). Build the JSON with `buildAntMetadata` from `@ar.io/sdk/solana` and upload via Turbo. See sdk/scripts/devnet-validation/populate-ant.ts.',
+    },
     token: {
         alias: '-t, --token <type>',
         description: 'Crypto token type for wallet or action',
@@ -326,6 +421,35 @@ export const optionMap = {
         description: 'Reassign all affiliated names to the new process',
         type: 'boolean',
     },
+    // -----------------------------------------------------------------
+    // Prune / cleanup flags (Solana-only — see pruneCommands.ts)
+    // -----------------------------------------------------------------
+    gateway: {
+        alias: '--gateway <gateway>',
+        description: 'The gateway operator address (prune / finalize commands)',
+    },
+    delegator: {
+        alias: '--delegator <delegator>',
+        description: 'The delegator address (close-empty-delegation)',
+    },
+    observer: {
+        alias: '--observer <observer>',
+        description: 'The observer address (close-observation)',
+    },
+    max: {
+        alias: '--max <max>',
+        description: 'Per-tx batch size (1-255, u8) for prune-expired-names / prune-returned-names',
+    },
+    arnsRecords: {
+        alias: '--arns-records <arnsRecords...>',
+        description: 'Explicit ArnsRecord PDAs to prune. Default: discover via getExpiredArnsRecords.',
+        type: 'array',
+    },
+    returnedNames: {
+        alias: '--returned-names <returnedNames...>',
+        description: 'Explicit ReturnedName PDAs to prune. Default: discover via getExpiredReturnedNames.',
+        type: 'array',
+    },
 };
 export const walletOptions = [
     optionMap.walletFile,
@@ -342,12 +466,22 @@ export const globalOptions = [
     optionMap.arioProcessId,
     optionMap.cuUrl,
     optionMap.hyperbeamUrl,
+    optionMap.ao,
+    optionMap.rpcUrl,
+    optionMap.antProgramId,
+    optionMap.coreProgramId,
+    optionMap.garProgramId,
+    optionMap.arnsProgramId,
 ];
 export const writeActionOptions = [optionMap.skipConfirmation, optionMap.tags];
 export const arnsPurchaseOptions = [
     ...writeActionOptions,
     optionMap.name,
     optionMap.fundFrom,
+    optionMap.gatewayAddress,
+    optionMap.fundAsOperator,
+    optionMap.withdrawalId,
+    optionMap.fundingPlanJson,
     optionMap.paidBy,
     optionMap.paymentUrl,
     optionMap.referrer,
@@ -437,10 +571,15 @@ export const antStateOptions = [
     optionMap.ttlSeconds,
     optionMap.logo,
     optionMap.module,
+    // Required for Solana spawn-ant; ignored by AO. Without this entry,
+    // Commander rejects --metadata-uri as an unknown option even though
+    // spawnSolanaANTFromOptions in utils.ts reads it as `(options as any).metadataUri`.
+    optionMap.metadataUri,
 ];
 export const setAntBaseNameOptions = [
     optionMap.processId,
     optionMap.transactionId,
+    optionMap.targetProtocol,
     optionMap.ttlSeconds,
     optionMap.owner,
     optionMap.displayName,

package/lib/esm/cli/utils.js

@@ -14,26 +14,13 @@
  * 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, createSolanaRpc, 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 { 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, Logger, createAoSigner, fromB64Url, fundFromOptions, initANTStateForAddress, isValidFundFrom, isValidIntent, mARIOToken, sha256B64Url, validIntents, } from '../node/index.js';
 import { globalOptions } from './options.js';
 export const defaultTtlSecondsCLI = 3600;
 export function stringifyJsonForCLIDisplay(json) {
@@ -141,19 +128,46 @@ function aoProcessFromOptions(options) {
 }
 export function readARIOFromOptions(options) {
     setLoggerIfDebug(options);
+    if (options.ao) {
+        return ARIO.init({
+            hyperbeamUrl: options.hyperbeamUrl,
+            process: aoProcessFromOptions({
+                cuUrl: 'http://localhost:6363',
+                ...options,
+            }),
+            paymentUrl: options.paymentUrl,
+        });
+    }
+    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,
+        backend: 'solana',
+        rpc: createSolanaRpc(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);
+    if (options.ao) {
+        return ANTRegistry.init({
+            process: aoProcessFromOptions(options),
+            hyperbeamUrl: options.hyperbeamUrl,
+        });
+    }
+    const rpcUrl = options.rpcUrl ?? 'https://api.mainnet-beta.solana.com';
     return ANTRegistry.init({
-        process: aoProcessFromOptions(options),
-        hyperbeamUrl: options.hyperbeamUrl,
+        backend: 'solana',
+        rpc: createSolanaRpc(rpcUrl),
+        ...(options.antProgramId
+            ? { antProgramId: address(options.antProgramId) }
+            : {}),
     });
 }
 export function contractSignerFromOptions(options) {
@@ -181,17 +195,85 @@ export function requiredContractSignerFromOptions(options) {
 export function requiredAoSignerFromOptions(options) {
     return createAoSigner(requiredContractSignerFromOptions(options).signer);
 }
-export function writeARIOFromOptions(options) {
-    const { signer, signerAddress } = requiredContractSignerFromOptions(options);
+/** 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);
+    }
+    catch {
+        return rpcUrl.replace(/^http/, 'ws');
+    }
+    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';
+    }
+    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+    return url.toString().replace(/\/$/, '');
+}
+/**
+ * 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 async function writeARIOFromOptions(options) {
     setLoggerIfDebug(options);
+    if (options.ao) {
+        const { signer, signerAddress } = requiredContractSignerFromOptions(options);
+        return {
+            ario: ARIO.init({
+                process: aoProcessFromOptions(options),
+                signer,
+                paymentUrl: options.paymentUrl,
+                hyperbeamUrl: options.hyperbeamUrl,
+            }),
+            signerAddress,
+        };
+    }
+    const rpcUrl = options.rpcUrl ?? 'https://api.mainnet-beta.solana.com';
+    const signer = await loadSolanaSignerFromOptions(options);
     return {
         ario: ARIO.init({
-            process: aoProcessFromOptions(options),
+            backend: 'solana',
+            rpc: createSolanaRpc(rpcUrl),
+            rpcSubscriptions: createSolanaRpcSubscriptions(wsUrlFromRpcUrl(rpcUrl)),
             signer,
-            paymentUrl: options.paymentUrl,
-            hyperbeamUrl: options.hyperbeamUrl,
+            // Forward program-id overrides to mirror `readARIOFromOptions` so
+            // localnet / devnet writes target the deployed program IDs instead of
+            // silently falling back to the SDK's 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) {
@@ -453,18 +535,43 @@ function ANTProcessFromOptions(options) {
         }),
     });
 }
-export function readANTFromOptions(options) {
+export async function readANTFromOptions(options) {
+    if (options.ao) {
+        return ANT.init({
+            process: ANTProcessFromOptions(options),
+            hyperbeamUrl: options.hyperbeamUrl,
+        });
+    }
+    const rpcUrl = options.rpcUrl ?? 'https://api.mainnet-beta.solana.com';
     return ANT.init({
-        process: ANTProcessFromOptions(options),
-        hyperbeamUrl: options.hyperbeamUrl,
+        backend: 'solana',
+        processId: requiredProcessIdFromOptions(options),
+        rpc: createSolanaRpc(rpcUrl),
+        ...(options.antProgramId
+            ? { antProgramId: address(options.antProgramId) }
+            : {}),
     });
 }
-export function writeANTFromOptions(options, signer) {
-    signer ??= requiredContractSignerFromOptions(options).signer;
+export async function writeANTFromOptions(options, signer) {
+    if (options.ao) {
+        signer ??= requiredContractSignerFromOptions(options).signer;
+        return ANT.init({
+            process: ANTProcessFromOptions(options),
+            signer,
+            hyperbeamUrl: options.hyperbeamUrl,
+        });
+    }
+    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,
+        backend: 'solana',
+        processId: requiredProcessIdFromOptions(options),
+        rpc: createSolanaRpc(rpcUrl),
+        rpcSubscriptions: createSolanaRpcSubscriptions(wsUrlFromRpcUrl(rpcUrl)),
+        signer: kitSigner,
+        ...(options.antProgramId
+            ? { antProgramId: address(options.antProgramId) }
+            : {}),
     });
 }
 export function booleanFromOptions(options, key) {
@@ -527,6 +634,60 @@ export function getANTStateFromOptions(options) {
             : 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 CLI's AO-shaped options (`--name`, `--ticker`, `--description`,
+ * `--keywords`, `--logo`, `--target` for the @ record tx id) onto the Solana
+ * `InitializeAntParams` payload. AO-only state fields like `controllers` and
+ * `balances` are intentionally dropped — they don't exist on Solana.
+ */
+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: createSolanaRpc(rpcUrl),
+        rpcSubscriptions: createSolanaRpcSubscriptions(wsUrlFromRpcUrl(rpcUrl)),
+        signer: kitSigner,
+        state: {
+            name,
+            uri: metadataUri,
+            ticker: options.ticker,
+            description: options.description,
+            keywords: options.keywords,
+            logo: options.logo,
+            // `--target` is the AO convention for the @ record's tx id (see
+            // initANTStateForAddress). Reuse it on Solana so the CLI surface stays
+            // identical between backends.
+            transactionId: options.target,
+        },
+        ...(options.antProgramId
+            ? { antProgramId: address(options.antProgramId) }
+            : {}),
+    });
+}
 export function getTokenCostParamsFromOptions(o) {
     o.intent ??= 'Buy-Name';
     o.type ??= 'lease';
@@ -557,6 +718,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

package/lib/esm/common/ant-registry.js

@@ -20,10 +20,32 @@ import { AOProcess, InvalidContractConfigurationError } from './index.js';
 import { Logger } from './logger.js';
 export class ANTRegistry {
     static init(config) {
-        if (config !== undefined && 'signer' in config) {
-            return new AoANTRegistryWriteable(config);
+        if (config && 'backend' in config && config.backend === 'solana') {
+            return (async () => {
+                if ('signer' in config) {
+                    const { SolanaANTRegistryWriteable } = await import('../solana/ant-registry-writeable.js');
+                    return new SolanaANTRegistryWriteable({
+                        rpc: config.rpc,
+                        signer: config.signer,
+                        commitment: config.commitment,
+                        logger: config.logger,
+                        antProgramId: config.antProgramId,
+                    });
+                }
+                const { SolanaANTRegistryReadable } = await import('../solana/ant-registry-readable.js');
+                return new SolanaANTRegistryReadable({
+                    rpc: config.rpc,
+                    commitment: config.commitment,
+                    logger: config.logger,
+                    antProgramId: config.antProgramId,
+                });
+            })();
+        }
+        const aoConfig = config;
+        if (aoConfig !== undefined && 'signer' in aoConfig) {
+            return new AoANTRegistryWriteable(aoConfig);
         }
-        return new AoANTRegistryReadable(config);
+        return new AoANTRegistryReadable(aoConfig);
     }
 }
 export class AoANTRegistryReadable {

package/lib/esm/common/ant.js

@@ -32,10 +32,14 @@ export class ANT {
     static get versions() {
         return ANTVersions.init();
     }
-    /**
-     * Spawn a new ANT.
-     */
-    static spawn = spawnANT;
+    static async spawn(params) {
+        if (params && params.backend === 'solana') {
+            const { spawnSolanaANT } = await import('../solana/spawn-ant.js');
+            const { backend: _backend, ...rest } = params;
+            return spawnSolanaANT(rest);
+        }
+        return spawnANT(params);
+    }
     /**
      * Fork an ANT to a new process.
      *
@@ -188,7 +192,48 @@ export class ANT {
         return { forkedProcessId, reassignedNames, failedReassignedNames };
     }
     static init(config) {
-        if (config !== undefined && 'signer' in config) {
+        // Solana backend — async, loads transport lazily to keep AO-only bundles small
+        if ('backend' in config && config.backend === 'solana') {
+            return (async () => {
+                const { SolanaANTReadable } = await import('../solana/ant-readable.js');
+                const { SolanaANTWriteable } = await import('../solana/ant-writeable.js');
+                // ADR-016 / BD-100: when no explicit `antProgramId` is passed,
+                // resolve it from the asset's `ANT Program` Attributes-plugin
+                // entry. Without this auto-detection, third-party (BYO-ANT)
+                // assets would silently mis-derive PDAs through the canonical
+                // default. Users who already know the program (e.g. immediately
+                // after `ANT.spawn`) can short-circuit by passing it explicitly.
+                let antProgramId = config.antProgramId;
+                if (!antProgramId) {
+                    const { fetchAntProgramFromAsset } = await import('../solana/mpl-core.js');
+                    const { ARIO_ANT_PROGRAM_ID } = await import('../solana/constants.js');
+                    const { address } = await import('@solana/kit');
+                    const detected = await fetchAntProgramFromAsset(config.rpc, address(config.processId), { commitment: config.commitment ?? 'confirmed' });
+                    antProgramId = detected ?? ARIO_ANT_PROGRAM_ID;
+                }
+                if (config.signer) {
+                    if (!config.rpcSubscriptions) {
+                        throw new Error('ANT.init({ backend: "solana", signer }) requires rpcSubscriptions for transaction confirmation.');
+                    }
+                    return new SolanaANTWriteable({
+                        rpc: config.rpc,
+                        rpcSubscriptions: config.rpcSubscriptions,
+                        processId: config.processId,
+                        signer: config.signer,
+                        commitment: config.commitment,
+                        antProgramId,
+                    });
+                }
+                return new SolanaANTReadable({
+                    rpc: config.rpc,
+                    processId: config.processId,
+                    commitment: config.commitment,
+                    antProgramId,
+                });
+            })();
+        }
+        // AO backend (stays sync)
+        if ('signer' in config) {
             return new AoANTWriteable(config);
         }
         return new AoANTReadable(config);