@ardrive/turbo-sdk 1.42.0-alpha.1 → 1.42.0-alpha.3

package/lib/cjs/common/payment.js

@@ -17,7 +17,10 @@ exports.TurboAuthenticatedPaymentService = exports.TurboUnauthenticatedPaymentSe
  * limitations under the License.
  */
 const bignumber_js_1 = require("bignumber.js");
+const types_js_1 = require("../types.js");
 const common_js_1 = require("../utils/common.js");
+const errors_js_1 = require("../utils/errors.js");
+const uuid_js_1 = require("../utils/uuid.js");
 const http_js_1 = require("./http.js");
 const http_js_2 = require("./http.js");
 const logger_js_1 = require("./logger.js");
@@ -94,6 +97,90 @@ class TurboUnauthenticatedPaymentService {
             equivalentWincTokenAmount: actualPaymentAmount.toString(),
         };
     }
+    async getArNSPriceForName(params) {
+        // `async` so a validation failure surfaces as a rejected promise (consistent
+        // with `purchaseArNSName`) rather than a synchronous throw.
+        this.validateArNSPurchaseParams(params);
+        return this.httpService.get({
+            endpoint: `/arns/price/${params.intent.toLowerCase()}/${params.name}${this.buildArNSPurchaseQuery(params)}`,
+        });
+    }
+    /**
+     * Fail fast (client-side) on malformed ArNS requests so JS callers that bypass
+     * the compile-time intent unions get a clear `ProvidedInputError` instead of an
+     * opaque service 4xx. Enforces the required fields per intent:
+     *  - `Buy-Name`: `type` ('lease' | 'permabuy'); leases also need `years`.
+     *    `processId` is OPTIONAL — omit it to have the bundler custodially
+     *    provision the ANT (Turbo owns it), supply it for a user-owned ANT.
+     *  - `Extend-Lease`: positive `years`
+     *  - `Increase-Undername-Limit`: positive `increaseQty`
+     *  - `Upgrade-Name`: just `name`
+     */
+    validateArNSPurchaseParams(params) {
+        const p = params;
+        if (!types_js_1.arNSPurchaseIntents.includes(p.intent)) {
+            throw new errors_js_1.ProvidedInputError(`Invalid ArNS intent '${p.intent}'. Expected one of: ${types_js_1.arNSPurchaseIntents.join(', ')}.`);
+        }
+        if (typeof p.name !== 'string' || p.name.length === 0) {
+            throw new errors_js_1.ProvidedInputError('An ArNS `name` is required.');
+        }
+        const isPositiveNumber = (v) => typeof v === 'number' && Number.isFinite(v) && v > 0;
+        switch (p.intent) {
+            case 'Buy-Name':
+                if (p.type !== 'lease' && p.type !== 'permabuy') {
+                    throw new errors_js_1.ProvidedInputError("Buy-Name requires a `type` of 'lease' or 'permabuy'.");
+                }
+                // `processId` is optional for Buy-Name: omitting it drives the
+                // bundler's custodial provisioning path (Turbo spawns + owns the ANT).
+                // If supplied it must be a non-empty string (user-owned ANT).
+                if (p.processId !== undefined &&
+                    (typeof p.processId !== 'string' || p.processId.length === 0)) {
+                    throw new errors_js_1.ProvidedInputError('Buy-Name `processId`, when provided, must be a non-empty string (the ANT the name resolves to).');
+                }
+                if (p.type === 'lease' && !isPositiveNumber(p.years)) {
+                    throw new errors_js_1.ProvidedInputError('A lease `Buy-Name` requires a positive `years`.');
+                }
+                break;
+            case 'Extend-Lease':
+                if (!isPositiveNumber(p.years)) {
+                    throw new errors_js_1.ProvidedInputError('Extend-Lease requires a positive `years`.');
+                }
+                break;
+            case 'Increase-Undername-Limit':
+                if (!isPositiveNumber(p.increaseQty)) {
+                    throw new errors_js_1.ProvidedInputError('Increase-Undername-Limit requires a positive `increaseQty`.');
+                }
+                break;
+            case 'Upgrade-Name':
+                break;
+        }
+    }
+    getArNSPurchaseStatus({ nonce, }) {
+        return this.httpService.get({
+            endpoint: `/arns/purchase/${nonce}`,
+        });
+    }
+    buildArNSPurchaseQuery(input) {
+        // The intent-specific union members each carry only their own fields; read
+        // them through a single widened view rather than narrowing per intent.
+        const { type, years, increaseQty, processId, paidBy } = input;
+        const params = new URLSearchParams();
+        if (type !== undefined)
+            params.set('type', type);
+        if (years !== undefined)
+            params.set('years', `${years}`);
+        if (increaseQty !== undefined)
+            params.set('increaseQty', `${increaseQty}`);
+        if (processId !== undefined)
+            params.set('processId', processId);
+        if (paidBy !== undefined) {
+            for (const payer of Array.isArray(paidBy) ? paidBy : [paidBy]) {
+                params.append('paidBy', payer);
+            }
+        }
+        const query = params.toString();
+        return query.length > 0 ? `?${query}` : '';
+    }
     appendPromoCodesToQuery(promoCodes) {
         const promoCodesQuery = promoCodes.join(',');
         return promoCodesQuery ? `promoCode=${promoCodesQuery}` : '';
@@ -259,6 +346,118 @@ class TurboAuthenticatedPaymentService extends TurboUnauthenticatedPaymentServic
         userAddress ??= await this.signer.getNativeAddress();
         return super.getBalance(userAddress);
     }
+    /**
+     * Buy / extend / upgrade an ArNS name, paying with the signer's Turbo credit
+     * balance. The bundler performs the on-chain ARIO purchase and debits credits;
+     * a `402` (FailedRequestError.status === 402) indicates insufficient credits.
+     */
+    async purchaseArNSName(params) {
+        this.validateArNSPurchaseParams(params);
+        // The bundler requires the signed nonce to be a UUID; it also doubles as
+        // the idempotency + status-lookup key (`getArNSPurchaseStatus`).
+        const nonce = (0, uuid_js_1.uuidV4)();
+        const headers = await this.signer.generateSignedRequestHeaders(nonce);
+        let response;
+        try {
+            response = await this.httpService.post({
+                endpoint: `/arns/purchase/${params.intent.toLowerCase()}/${params.name}${this.buildArNSPurchaseQuery(params)}`,
+                headers,
+                // Params travel in the query string + signed headers; the service reads
+                // no body, but the HTTP layer requires a `data` field.
+                data: Buffer.from([]),
+                // Non-idempotent signed write: the nonce is single-use, so a retried
+                // (but already-landed) purchase would 4xx as "already exists". Poll
+                // status by nonce instead of retrying.
+                retry: false,
+            });
+        }
+        catch (error) {
+            // Surface a credit shortfall as a typed, catchable error so callers can
+            // prompt a top-up. The `nonce` is the idempotency key: after topping up,
+            // retry the same purchase (a fresh nonce is fine — the service dedupes by
+            // the on-chain effect, and a captured nonce lets you poll status).
+            if (error instanceof errors_js_1.FailedRequestError && error.status === 402) {
+                throw new errors_js_1.InsufficientCreditsError(error.message);
+            }
+            throw error;
+        }
+        // Normalize both nonce fields to the one we signed so callers can poll with
+        // either `response.nonce` or `response.purchaseReceipt.nonce`.
+        return {
+            ...response,
+            nonce,
+            purchaseReceipt: { ...response.purchaseReceipt, nonce },
+        };
+    }
+    buyArNSName(params) {
+        return this.purchaseArNSName({
+            ...params,
+            intent: 'Buy-Name',
+        });
+    }
+    extendArNSLease(params) {
+        return this.purchaseArNSName({ ...params, intent: 'Extend-Lease' });
+    }
+    increaseArNSUndernameLimit(params) {
+        return this.purchaseArNSName({
+            ...params,
+            intent: 'Increase-Undername-Limit',
+        });
+    }
+    upgradeArNSName(params) {
+        return this.purchaseArNSName({ ...params, intent: 'Upgrade-Name' });
+    }
+    // ---- ArNS ANT custody: self-custody exit + manage records ----
+    // Canonical ACTION-BOUND message. MUST match the bundler's
+    // buildArNSCustodyMessage byte-for-byte (newline-delimited) or every signature
+    // is rejected. The bundler reconstructs this from the request and verifies the
+    // signature over `message + nonce`, so a captured signature can't be replayed
+    // against a different operation/params.
+    buildArNSCustodyMessage(action, fields) {
+        return ['arns', action, ...fields].join('\n');
+    }
+    /**
+     * Self-custody exit: move a Turbo-custodied ANT to a Solana pubkey you control.
+     * Authenticated with an action-bound, single-use signature.
+     */
+    async transferArNSAnt({ antId, target, }) {
+        const nonce = (0, uuid_js_1.uuidV4)();
+        const headers = await this.signer.generateSignedRequestHeaders(nonce, this.buildArNSCustodyMessage('transfer', [antId, target]));
+        return this.httpService.post({
+            endpoint: `/arns/transfer/${antId}?target=${encodeURIComponent(target)}`,
+            headers,
+            data: Buffer.from([]),
+            retry: false, // single-use action-bound nonce; don't re-POST on 5xx
+        });
+    }
+    /** Set a resolution record on a custodied ANT (undername defaults to '@'). */
+    async setArNSRecord({ antId, undername = '@', transactionId, ttlSeconds, }) {
+        const nonce = (0, uuid_js_1.uuidV4)();
+        const headers = await this.signer.generateSignedRequestHeaders(nonce, this.buildArNSCustodyMessage('set-record', [
+            antId,
+            undername,
+            transactionId,
+            String(ttlSeconds),
+        ]));
+        const query = `?undername=${encodeURIComponent(undername)}&transactionId=${transactionId}&ttlSeconds=${ttlSeconds}`;
+        return this.httpService.post({
+            endpoint: `/arns/manage/${antId}/set-record${query}`,
+            headers,
+            data: Buffer.from([]),
+            retry: false, // single-use action-bound nonce; don't re-POST on 5xx
+        });
+    }
+    /** Remove a resolution record (an undername) from a custodied ANT. */
+    async removeArNSRecord({ antId, undername, }) {
+        const nonce = (0, uuid_js_1.uuidV4)();
+        const headers = await this.signer.generateSignedRequestHeaders(nonce, this.buildArNSCustodyMessage('remove-record', [antId, undername]));
+        return this.httpService.post({
+            endpoint: `/arns/manage/${antId}/remove-record?undername=${encodeURIComponent(undername)}`,
+            headers,
+            data: Buffer.from([]),
+            retry: false, // single-use action-bound nonce; don't re-POST on 5xx
+        });
+    }
     async getCreditShareApprovals({ userAddress, }) {
         userAddress ??= await this.signer.getNativeAddress();
         return super.getCreditShareApprovals({ userAddress });

package/lib/cjs/common/signer.js

@@ -73,15 +73,27 @@ class TurboDataItemAbstractSigner {
                 return (0, base64_js_1.ownerToAddress)(owner);
         }
     }
-    async generateSignedRequestHeaders() {
-        const nonce = (0, crypto_2.randomBytes)(16).toString('hex');
-        const buffer = Buffer.from(nonce);
+    async generateSignedRequestHeaders(
+    // Callers may supply the nonce (e.g. a UUID required by some routes); the
+    // nonce round-trips to the service in `x-nonce` unchanged.
+    nonce = (0, crypto_2.randomBytes)(16).toString('hex'), 
+    // Optional ACTION-BINDING data prepended to the nonce for SIGNING only (not
+    // sent): the service reconstructs the same string from the request and
+    // verifies the signature over `additionalData + nonce`. This binds the
+    // signature to a specific operation + params so it can't be replayed against
+    // a different request. Omitted → signs the bare nonce (unchanged behavior).
+    additionalData) {
+        const buffer = Buffer.from((additionalData ?? '') + nonce);
         const signature = await this.signer.sign(Uint8Array.from(buffer));
         const publicKey = (0, base64_js_1.toB64Url)(this.signer.publicKey);
         return {
             'x-public-key': publicKey,
             'x-nonce': nonce,
             'x-signature': (0, base64_js_1.toB64Url)(Buffer.from(signature)),
+            // Advertise the signature scheme so the service verifies with the right
+            // algorithm. Absent this, the server defaults to Arweave and every
+            // non-Arweave signed request (Ethereum, Solana, …) fails verification.
+            'x-signature-type': this.signer.signatureType.toString(),
         };
     }
     async getPublicKey() {

package/lib/cjs/common/turbo.js

@@ -54,6 +54,18 @@ class TurboUnauthenticatedClient {
     getBalance(address) {
         return this.paymentService.getBalance(address);
     }
+    /**
+     * Returns the price in 'winc' (and mARIO) to buy/extend/upgrade an ArNS name.
+     */
+    getArNSPriceForName(params) {
+        return this.paymentService.getArNSPriceForName(params);
+    }
+    /**
+     * Returns the status of an ArNS purchase by its nonce.
+     */
+    getArNSPurchaseStatus(p) {
+        return this.paymentService.getArNSPurchaseStatus(p);
+    }
     /**
      * Returns a list of all supported fiat currencies.
      */
@@ -159,6 +171,38 @@ class TurboAuthenticatedClient extends TurboUnauthenticatedClient {
     getBalance(userAddress) {
         return this.paymentService.getBalance(userAddress);
     }
+    /**
+     * Buys, extends, or upgrades an ArNS name, paying with the signer's Turbo
+     * credit balance. Poll {@link getArNSPurchaseStatus} with the returned nonce.
+     */
+    purchaseArNSName(params) {
+        return this.paymentService.purchaseArNSName(params);
+    }
+    /** Buys a new ArNS name (lease or permabuy). */
+    buyArNSName(params) {
+        return this.paymentService.buyArNSName(params);
+    }
+    /** Extends the lease on an existing ArNS name. */
+    extendArNSLease(params) {
+        return this.paymentService.extendArNSLease(params);
+    }
+    /** Increases the undername limit on an existing ArNS name. */
+    increaseArNSUndernameLimit(params) {
+        return this.paymentService.increaseArNSUndernameLimit(params);
+    }
+    /** Upgrades an ArNS lease to a permabuy. */
+    upgradeArNSName(params) {
+        return this.paymentService.upgradeArNSName(params);
+    }
+    transferArNSAnt(params) {
+        return this.paymentService.transferArNSAnt(params);
+    }
+    setArNSRecord(params) {
+        return this.paymentService.setArNSRecord(params);
+    }
+    removeArNSRecord(params) {
+        return this.paymentService.removeArNSRecord(params);
+    }
     /**
      * Returns a list of all credit share approvals for the user.
      */

package/lib/cjs/types.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validChunkingModes = exports.isJWK = exports.isWebUploadFolderParams = exports.isNodeUploadFolderParams = exports.multipartFinalizedStatus = exports.multipartFailedStatus = exports.multipartPendingStatus = exports.X402Funding = exports.OnDemandFunding = exports.ExistingBalanceFunding = exports.supportedEvmSignerTokens = exports.tokenTypes = exports.fiatCurrencyTypes = void 0;
+exports.arNSPurchaseIntents = exports.validChunkingModes = exports.isJWK = exports.isWebUploadFolderParams = exports.isNodeUploadFolderParams = exports.multipartFinalizedStatus = exports.multipartFailedStatus = exports.multipartPendingStatus = exports.X402Funding = exports.OnDemandFunding = exports.ExistingBalanceFunding = exports.supportedEvmSignerTokens = exports.tokenTypes = exports.fiatCurrencyTypes = void 0;
 exports.isCurrency = isCurrency;
 exports.isKyvePrivateKey = isKyvePrivateKey;
 exports.isEthPrivateKey = isEthPrivateKey;
@@ -108,3 +108,10 @@ function isEthereumWalletAdapter(walletAdapter) {
     return 'getSigner' in walletAdapter;
 }
 exports.validChunkingModes = ['force', 'disabled', 'auto'];
+// ===== ArNS purchases paid with Turbo credits (via the bundler REST API) =====
+exports.arNSPurchaseIntents = [
+    'Buy-Name',
+    'Extend-Lease',
+    'Increase-Undername-Limit',
+    'Upgrade-Name',
+];

package/lib/cjs/utils/errors.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AbortError = exports.ProvidedInputError = exports.FailedRequestError = exports.UnauthenticatedRequestError = exports.BaseError = void 0;
+exports.AbortError = exports.InsufficientCreditsError = exports.ProvidedInputError = exports.FailedRequestError = exports.UnauthenticatedRequestError = exports.BaseError = void 0;
 /**
  * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
  *
@@ -42,6 +42,24 @@ class ProvidedInputError extends BaseError {
     }
 }
 exports.ProvidedInputError = ProvidedInputError;
+/**
+ * Raised when a credit-paid operation (e.g. an ArNS purchase) is rejected by the
+ * service because the paying wallet does not hold enough Turbo credits. Maps the
+ * bundler's HTTP `402 Payment Required` response to a typed, catchable error so
+ * callers can prompt a top-up without string-matching on messages.
+ *
+ * Recovery: top up the balance, then retry the SAME operation reusing the
+ * captured `nonce` (the nonce is the idempotency key), or mint a fresh request.
+ */
+class InsufficientCreditsError extends BaseError {
+    constructor(message) {
+        super(message ??
+            'Insufficient Turbo credits to complete this purchase. Top up your balance and retry.');
+        /** Always the HTTP status that produced this error. */
+        this.status = 402;
+    }
+}
+exports.InsufficientCreditsError = InsufficientCreditsError;
 class AbortError extends BaseError {
     constructor(message = 'Request was aborted') {
         super(message);

package/lib/cjs/utils/uuid.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uuidV4 = uuidV4;
+/**
+ * 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.
+ */
+const crypto_1 = require("crypto");
+/**
+ * RFC 4122 version 4 UUID, derived from `randomBytes` (already used across the
+ * SDK in both the node and web builds). Avoids depending on
+ * `crypto.randomUUID`, whose availability varies by runtime/polyfill.
+ */
+function uuidV4() {
+    const bytes = (0, crypto_1.randomBytes)(16);
+    bytes[6] = (bytes[6] & 0x0f) | 0x40; // version 4
+    bytes[8] = (bytes[8] & 0x3f) | 0x80; // RFC 4122 variant
+    const hex = bytes.toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/lib/cjs/web/signer.js

@@ -64,9 +64,11 @@ class TurboWebArweaveSigner extends signer_js_1.TurboDataItemAbstractSigner {
             dataItemSizeFactory: () => signedDataItemSize,
         };
     }
-    async generateSignedRequestHeaders() {
+    async generateSignedRequestHeaders(nonce, additionalData) {
         await this.setPublicKey();
-        return super.generateSignedRequestHeaders();
+        // Pass through the caller's nonce + action-binding data (previously dropped,
+        // which would override a route-required UUID nonce and the H-2 binding).
+        return super.generateSignedRequestHeaders(nonce, additionalData);
     }
     async signData(dataToSign) {
         await this.setPublicKey();

package/lib/esm/cli/cli.js

@@ -20,6 +20,7 @@ import { DataItem } from '@dha-team/arbundles';
 import { program } from 'commander';
 import { readFileSync, readdirSync } from 'fs';
 import { version } from '../version.js';
+import { arnsPrice, arnsPurchaseStatus, buyArNSName, extendArNSLease, increaseArNSUndernames, removeArNSRecord, setArNSRecord, transferArNSAnt, upgradeArNSName, } from './commands/arns.js';
 import { fiatEstimate } from './commands/fiatEstimate.js';
 import { balance, cryptoFund, price, topUp, uploadFile, uploadFolder, } from './commands/index.js';
 import { listShares } from './commands/listShares.js';
@@ -27,7 +28,7 @@ import { revokeCredits } from './commands/revokeCredits.js';
 import { shareCredits } from './commands/shareCredits.js';
 import { tokenPrice } from './commands/tokenPrice.js';
 import { x402UploadUnsignedFile } from './commands/x402UploadUnsignedData.js';
-import { globalOptions, listSharesOptions, optionMap, revokeCreditsOptions, shareCreditsOptions, uploadFileOptions, uploadFolderOptions, walletOptions, } from './options.js';
+import { arnsPriceOptions, arnsPurchaseStatusOptions, buyArNSNameOptions, extendArNSLeaseOptions, globalOptions, increaseArNSUndernamesOptions, listSharesOptions, optionMap, removeArNSRecordOptions, revokeCreditsOptions, setArNSRecordOptions, shareCreditsOptions, transferArNSAntOptions, upgradeArNSNameOptions, uploadFileOptions, uploadFolderOptions, walletOptions, } from './options.js';
 import { applyOptions, runCommand } from './utils.js';
 applyOptions(program
     .name('turbo')
@@ -84,6 +85,51 @@ applyOptions(program
     .description('Lists all given or received Turbo credit share approvals for specified address or connected wallet'), listSharesOptions).action(async (_commandOptions, command) => {
     await runCommand(command, listShares);
 });
+applyOptions(program
+    .command('arns-price')
+    .description('Get the Turbo Credit (winc + mARIO) price to buy, extend, increase undernames, or upgrade an ArNS name'), arnsPriceOptions).action(async (_commandOptions, command) => {
+    await runCommand(command, arnsPrice);
+});
+applyOptions(program
+    .command('buy-arns-name')
+    .description('Buy an ArNS name (lease or permabuy) with Turbo Credits'), buyArNSNameOptions).action(async (_commandOptions, command) => {
+    await runCommand(command, buyArNSName);
+});
+applyOptions(program
+    .command('extend-arns-lease')
+    .description('Extend an ArNS name lease with Turbo Credits'), extendArNSLeaseOptions).action(async (_commandOptions, command) => {
+    await runCommand(command, extendArNSLease);
+});
+applyOptions(program
+    .command('increase-arns-undernames')
+    .description('Increase the undername limit of an ArNS name with Turbo Credits'), increaseArNSUndernamesOptions).action(async (_commandOptions, command) => {
+    await runCommand(command, increaseArNSUndernames);
+});
+applyOptions(program
+    .command('upgrade-arns-name')
+    .description('Upgrade an ArNS leased name to a permabuy with Turbo Credits'), upgradeArNSNameOptions).action(async (_commandOptions, command) => {
+    await runCommand(command, upgradeArNSName);
+});
+applyOptions(program
+    .command('arns-purchase-status')
+    .description('Get the status of an ArNS purchase by its nonce'), arnsPurchaseStatusOptions).action(async (_commandOptions, command) => {
+    await runCommand(command, arnsPurchaseStatus);
+});
+applyOptions(program
+    .command('transfer-arns-ant')
+    .description('Transfer a Turbo-custodied ANT to a Solana pubkey you control'), transferArNSAntOptions).action(async (_commandOptions, command) => {
+    await runCommand(command, transferArNSAnt);
+});
+applyOptions(program
+    .command('set-arns-record')
+    .description('Set a resolution record on a Turbo-custodied ANT'), setArNSRecordOptions).action(async (_commandOptions, command) => {
+    await runCommand(command, setArNSRecord);
+});
+applyOptions(program
+    .command('remove-arns-record')
+    .description('Remove a resolution record (undername) from a Turbo-custodied ANT'), removeArNSRecordOptions).action(async (_commandOptions, command) => {
+    await runCommand(command, removeArNSRecord);
+});
 applyOptions(program
     .command('inspect-data-items')
     .description('Lists all given or received Turbo credit share approvals for specified address or connected wallet'), [optionMap.folderPath]).action(async (_commandOptions, command) => {