@ardrive/turbo-sdk 1.41.3 → 1.42.0-alpha.10

package/lib/esm/cli/options.js

@@ -73,16 +73,6 @@ export const optionMap = {
         description: 'Set a custom payment service URL',
         default: undefined,
     },
-    processId: {
-        alias: '--process-id <processId>',
-        description: 'Set a custom target process ID for the action',
-        default: undefined,
-    },
-    cuUrl: {
-        alias: '--cu-url <cuUrl>',
-        description: 'Set a custom CU URL for the action',
-        default: undefined,
-    },
     dev: {
         alias: '--dev',
         description: 'Enable Turbo development endpoints',
@@ -196,6 +186,60 @@ export const optionMap = {
         alias: '--max-crypto-top-up-value <maxCryptoTopUpValue>',
         description: 'Maximum crypto top-up value to use for the upload. Defaults to no limit.',
     },
+    // ---- ArNS (paid with Turbo Credits) ----
+    arnsName: {
+        alias: '--name <name>',
+        description: 'ArNS name to price, buy, or manage',
+    },
+    arnsType: {
+        alias: '--type <type>',
+        description: "ArNS purchase type for Buy-Name: 'lease' or 'permabuy'",
+    },
+    arnsYears: {
+        alias: '--years <years>',
+        description: 'Lease duration in years (Buy-Name lease / Extend-Lease)',
+    },
+    arnsIncreaseQty: {
+        alias: '--increase-qty <qty>',
+        description: 'Number of additional undernames (Increase-Undername-Limit)',
+    },
+    arnsOwnerKey: {
+        alias: '--owner-key <base58SolanaSecretKey>',
+        description: 'Base58 Solana secret key that OWNS the ANT and signs for it. Separate from the wallet paying in Turbo Credits — the owner needs a key to sign with, not SOL: Turbo pays every fee and rent',
+    },
+    arnsNonce: {
+        alias: '--nonce <nonce>',
+        description: 'ArNS purchase nonce to look up the status for',
+    },
+    arnsAntId: {
+        alias: '--ant-id <antId>',
+        description: 'ANT (Metaplex Core asset) ID to transfer or manage',
+    },
+    arnsTarget: {
+        alias: '--target <address>',
+        description: 'Target Solana pubkey to transfer the ANT to',
+    },
+    arnsUndername: {
+        alias: '--undername <undername>',
+        description: "ArNS undername record to set or remove (defaults to '@')",
+    },
+    arnsTransactionId: {
+        alias: '--transaction-id <transactionId>',
+        description: 'Arweave transaction ID the ArNS record resolves to',
+    },
+    arnsTtlSeconds: {
+        alias: '--ttl-seconds <ttlSeconds>',
+        description: 'TTL in seconds for the ArNS record',
+    },
+    // ---- Payment history ----
+    limit: {
+        alias: '--limit <limit>',
+        description: 'Max number of payment-history rows to return (1-100, default 50)',
+    },
+    cursor: {
+        alias: '--cursor <cursor>',
+        description: 'Opaque pagination cursor from a prior payment-history response',
+    },
 };
 export const walletOptions = [
     optionMap.walletFile,
@@ -249,3 +293,72 @@ export const shareCreditsOptions = [
 ];
 export const revokeCreditsOptions = [...walletOptions, optionMap.address];
 export const listSharesOptions = revokeCreditsOptions;
+// ---- ArNS command option sets (token + --payment-url come from globalOptions) ----
+export const arnsPriceOptions = [
+    optionMap.arnsName,
+    optionMap.arnsType,
+    optionMap.arnsYears,
+    optionMap.arnsIncreaseQty,
+];
+export const arnsFiatQuoteOptions = [
+    optionMap.arnsName,
+    optionMap.arnsType,
+    optionMap.arnsYears,
+    optionMap.arnsIncreaseQty,
+    optionMap.address,
+    optionMap.currency,
+    {
+        alias: '--method <method>',
+        description: 'Stripe integration mode: payment-intent (default) or checkout-session',
+    },
+    {
+        alias: '--promo-code <promoCode...>',
+        description: 'Promo code(s) to apply to the fiat price',
+    },
+];
+export const buyArNSNameOptions = [
+    ...walletOptions,
+    optionMap.arnsName,
+    optionMap.arnsType,
+    optionMap.arnsYears,
+    optionMap.arnsOwnerKey,
+    optionMap.paidBy,
+];
+export const extendArNSLeaseOptions = [
+    ...walletOptions,
+    optionMap.arnsName,
+    optionMap.arnsYears,
+    optionMap.paidBy,
+];
+export const increaseArNSUndernamesOptions = [
+    ...walletOptions,
+    optionMap.arnsName,
+    optionMap.arnsIncreaseQty,
+    optionMap.paidBy,
+];
+export const upgradeArNSNameOptions = [
+    ...walletOptions,
+    optionMap.arnsName,
+    optionMap.paidBy,
+];
+export const arnsPurchaseStatusOptions = [optionMap.arnsNonce];
+export const transferArNSAntOptions = [
+    ...walletOptions,
+    optionMap.arnsOwnerKey,
+    optionMap.arnsAntId,
+    optionMap.arnsTarget,
+];
+export const setArNSRecordOptions = [
+    ...walletOptions,
+    optionMap.arnsOwnerKey,
+    optionMap.arnsAntId,
+    optionMap.arnsUndername,
+    optionMap.arnsTransactionId,
+    optionMap.arnsTtlSeconds,
+];
+export const removeArNSRecordOptions = [
+    ...walletOptions,
+    optionMap.arnsOwnerKey,
+    optionMap.arnsAntId,
+    optionMap.arnsUndername,
+];

package/lib/esm/cli/utils.js

@@ -16,7 +16,7 @@
 import bs58 from 'bs58';
 import { readFileSync, statSync } from 'fs';
 import { ExistingBalanceFunding, OnDemandFunding, TurboFactory, X402Funding, defaultTurboConfiguration, developmentTurboConfiguration, fiatCurrencyTypes, isCurrency, isTokenType, privateKeyFromKyveMnemonic, tokenToBaseMap, } from '../node/index.js';
-import { defaultProdAoConfigs, tokenToDevAoConfigMap, tokenToDevGatewayMap, } from '../utils/common.js';
+import { tokenToDevGatewayMap } from '../utils/common.js';
 import { NoWalletProvidedError } from './errors.js';
 export function exitWithErrorLog(error) {
     console.error(error instanceof Error ? error.message : error);
@@ -100,7 +100,9 @@ export async function privateKeyFromOptions({ mnemonic, privateKey, walletFile,
     }
     else if (walletFile !== undefined) {
         const wallet = JSON.parse(readFileSync(walletFile, 'utf-8'));
-        return token === 'solana' ? bs58.encode(wallet) : wallet;
+        return token === 'solana' || token === 'ario'
+            ? bs58.encode(wallet)
+            : wallet;
     }
     else if (privateKey !== undefined) {
         return privateKey;
@@ -114,8 +116,6 @@ export function configFromOptions(options) {
     let paymentUrl = undefined;
     let uploadUrl = undefined;
     let gatewayUrl = undefined;
-    let processId = undefined;
-    let cuUrl = undefined;
     if (options.local && options.dev) {
         throw new Error('Cannot use both --local and --dev flags');
     }
@@ -124,10 +124,6 @@ export function configFromOptions(options) {
         paymentUrl = developmentTurboConfiguration.paymentServiceConfig.url;
         uploadUrl = developmentTurboConfiguration.uploadServiceConfig.url;
         gatewayUrl = tokenToDevGatewayMap[token];
-        if (options.token === 'ario') {
-            processId = tokenToDevAoConfigMap[token].processId;
-            cuUrl = tokenToDevAoConfigMap[token].cuUrl;
-        }
     }
     else if (options.local) {
         // Use local endpoints
@@ -139,10 +135,6 @@ export function configFromOptions(options) {
         // Use default endpoints
         paymentUrl = defaultTurboConfiguration.paymentServiceConfig.url;
         uploadUrl = defaultTurboConfiguration.uploadServiceConfig.url;
-        if (options.token === 'ario') {
-            processId = defaultProdAoConfigs[token].processId;
-            cuUrl = defaultProdAoConfigs[token].cuUrl;
-        }
     }
     // Override gateway, payment, and upload service default endpoints if provided
     if (options.gateway !== undefined) {
@@ -154,19 +146,11 @@ export function configFromOptions(options) {
     if (options.uploadUrl !== undefined) {
         uploadUrl = options.uploadUrl;
     }
-    if (options.cuUrl !== undefined) {
-        cuUrl = options.cuUrl;
-    }
-    if (options.processId !== undefined) {
-        processId = options.processId;
-    }
     const config = {
         paymentServiceConfig: { url: paymentUrl },
         uploadServiceConfig: { url: uploadUrl },
         gatewayUrl,
         token,
-        processId,
-        cuUrl,
     };
     return config;
 }

package/lib/esm/common/arnsActions.js

@@ -0,0 +1,93 @@
+/**
+ * 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 { Keypair, VersionedTransaction } from '@solana/web3.js';
+import bs58 from 'bs58';
+import nacl from 'tweetnacl';
+import { toB64Url } from '../utils/base64.js';
+/**
+ * Canonical ACTION-BOUND message for the owner proof.
+ *
+ * MUST match the bundler's `buildArNSCustodyMessage` byte for byte
+ * (newline-delimited) or every signature is rejected. The bundler rebuilds this
+ * from the request and verifies the signature over `message + nonce`, so a
+ * signature captured for one operation cannot authorize a different one, and
+ * the nonce is consumed on use so the same one cannot be replayed (e.g. to
+ * revert a record to an older value).
+ */
+export function buildArNSCustodyMessage(action, fields) {
+    return ['arns', action, ...fields].join('\n');
+}
+/** Solana's signature-type discriminator in Turbo's signed-request scheme. */
+const SOLANA_SIGNATURE_TYPE = 4;
+/**
+ * The ANT owner's half of the envelope, in its own `x-owner-*` headers.
+ *
+ * Two signatures travel on a record action — the PAYER's signed request over
+ * `"" + nonce`, and the OWNER's action-bound proof over `message + nonce` —
+ * from two different keys, usually on two different chains. They cannot share
+ * one header set: whichever verifier ran second would reject a signature that
+ * was never meant for it.
+ */
+export async function arNSOwnerProofHeaders(owner, message, nonce) {
+    const address = await owner.getAddress();
+    const signature = await owner.signMessage(Uint8Array.from(Buffer.from(message + nonce)));
+    return {
+        // A Solana address IS the base58-encoded 32-byte ed25519 public key, so
+        // decoding the address recovers exactly the bytes the bundler verifies
+        // against. Keeps ArNSOwnerSigner minimal — no separate getPublicKey().
+        'x-owner-public-key': toB64Url(Buffer.from(bs58.decode(address))),
+        'x-owner-nonce': nonce,
+        'x-owner-signature': toB64Url(Buffer.from(signature)),
+        'x-owner-signature-type': String(SOLANA_SIGNATURE_TYPE),
+    };
+}
+/**
+ * Build an {@link ArNSOwnerSigner} from a raw Solana secret key.
+ *
+ * For servers and tests. A browser wallet (Phantom, Solflare, or a console's
+ * embedded wallet) should implement the interface directly against its own
+ * `signTransaction` / `signMessage` rather than exposing a secret key.
+ *
+ * Note the owner needs a key to SIGN with, not a funded account: Turbo is the
+ * fee payer on every sponsored action, so this wallet's SOL balance can stay
+ * at zero for the entire life of the name.
+ */
+export function solanaOwnerSigner(secretKey) {
+    const keypair = Keypair.fromSecretKey(typeof secretKey === 'string' ? bs58.decode(secretKey) : secretKey);
+    return {
+        getAddress: () => keypair.publicKey.toBase58(),
+        signTransaction: async (transactionBase64) => {
+            const tx = VersionedTransaction.deserialize(Buffer.from(transactionBase64, 'base64'));
+            // Sign the bytes as returned. Turbo's fee-payer signature already covers
+            // this exact message; rebuilding it from parts invalidates that and the
+            // submission is rejected.
+            tx.sign([keypair]);
+            return Buffer.from(tx.serialize()).toString('base64');
+        },
+        signMessage: async (message) => nacl.sign.detached(message, keypair.secretKey),
+    };
+}
+/**
+ * Count the signature slots a prepared transaction still has empty.
+ *
+ * Turbo pre-signs as fee payer and leaves exactly one slot for the owner, so a
+ * client can assert that before prompting a wallet — a cheap way to catch a
+ * malformed or already-signed transaction before bothering the user.
+ */
+export function emptySignatureSlots(transactionBase64) {
+    const tx = VersionedTransaction.deserialize(Buffer.from(transactionBase64, 'base64'));
+    return tx.signatures.filter((sig) => sig.every((byte) => byte === 0)).length;
+}

package/lib/esm/common/factory.js

@@ -43,7 +43,7 @@ export class TurboBaseFactory {
             paymentService,
         });
     }
-    getAuthenticatedTurbo({ privateKey, signer: providedSigner, paymentServiceConfig = {}, uploadServiceConfig = {}, token, gatewayUrl, tokenMap, tokenTools, logger, walletAdapter, processId, cuUrl, }) {
+    getAuthenticatedTurbo({ privateKey, signer: providedSigner, paymentServiceConfig = {}, uploadServiceConfig = {}, token, gatewayUrl, tokenMap, tokenTools, logger, walletAdapter, }) {
         token = token === 'pol' ? 'matic' : token;
         if (!token) {
             if (providedSigner) {
@@ -101,8 +101,6 @@ export class TurboBaseFactory {
                 tokenTools = tokenMap.arweave;
             }
             tokenTools = defaultTokenMap[token]?.({
-                cuUrl,
-                processId,
                 gatewayUrl,
                 logger,
             });

package/lib/esm/common/http.js

@@ -30,6 +30,18 @@ const defaultHeaders = {
     'x-turbo-source-version': version,
     'x-turbo-source-identifier': 'turbo-sdk',
 };
+/**
+ * Canonical x402 upload routes on the upload service.
+ *
+ * These were previously `/x402/data-item/{signed,unsigned}`. The service
+ * renamed them to `/x402/upload/*` and kept a `data-item/signed` alias, but not
+ * a `data-item/unsigned` one — so every unsigned x402 upload 404ed. Both
+ * canonical paths are served by all released upload-service versions.
+ */
+export const x402UploadEndpoints = {
+    signed: '/x402/upload/signed',
+    unsigned: '/x402/upload/unsigned',
+};
 export class TurboHTTPService {
     constructor({ url, logger, retryConfig = defaultRetryConfig(logger), }) {
         this.logger = logger;
@@ -43,7 +55,7 @@ export class TurboHTTPService {
             signal,
         }), allowedStatuses);
     }
-    async post({ endpoint, signal, allowedStatuses = [200, 202], headers, data, x402Options, }) {
+    async post({ endpoint, signal, allowedStatuses = [200, 202], headers, data, x402Options, retry = true, }) {
         if (x402Options !== undefined) {
             return this.x402Post({
                 signal,
@@ -55,9 +67,10 @@ export class TurboHTTPService {
         }
         // Convert all data types to fetch-compatible body
         const { body, duplex } = await toFetchBody(data);
-        // Use retry for Buffer/Uint8Array, tryRequest for streams
+        // Use retry for Buffer/Uint8Array, tryRequest for streams. Callers can opt
+        // out of retry for non-idempotent signed writes via `retry: false`.
         const isReusableData = data instanceof Buffer || data instanceof Uint8Array;
-        const requestFn = isReusableData
+        const requestFn = isReusableData && retry
             ? this.withRetry.bind(this)
             : this.tryRequest.bind(this);
         return requestFn(() => fetch(this.baseURL + endpoint, {
@@ -119,7 +132,9 @@ export class TurboHTTPService {
         throw new FailedRequestError('Max retries reached - ' + lastError?.message, lastError?.status);
     }
     async x402Post({ signal, allowedStatuses, headers, data, x402Options, }) {
-        const endpoint = '/x402/data-item/' + (x402Options.unsignedData ? 'unsigned' : 'signed');
+        const endpoint = x402Options.unsignedData
+            ? x402UploadEndpoints.unsigned
+            : x402UploadEndpoints.signed;
         this.logger.debug('Using X402 options for POST request', {
             endpoint,
             x402Options,

package/lib/esm/common/index.js

@@ -15,6 +15,12 @@
  */
 export * from './upload.js';
 export * from './payment.js';
+// The ANT-owner helpers. Without this the documented
+// `import { solanaOwnerSigner } from '@ardrive/turbo-sdk'` does not resolve.
+export * from './arnsActions.js';
 export * from './turbo.js';
 export * from './currency.js';
 export * from './token/index.js';
+// Typed errors so consumers can `catch (e) { if (e instanceof InsufficientCreditsError) ... }`
+// e.g. to prompt a top-up on a 402 ArNS purchase.
+export * from '../utils/errors.js';