@ardrive/turbo-sdk 1.42.0-alpha.2 → 1.42.0-alpha.4

package/lib/esm/cli/commands/arns.js

@@ -0,0 +1,233 @@
+/**
+ * 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 { BigNumber } from 'bignumber.js';
+import { TurboFactory } from '../../node/factory.js';
+import { InsufficientCreditsError } from '../../utils/errors.js';
+import { wincPerCredit } from '../constants.js';
+import { configFromOptions, turboFromOptions } from '../utils.js';
+export function requiredNameFromOptions(options) {
+    if (options.name === undefined || options.name.length === 0) {
+        throw new Error('Must provide an ArNS --name');
+    }
+    return options.name;
+}
+export function positiveIntFromOption(value, flag) {
+    if (value === undefined) {
+        throw new Error(`Must provide ${flag}`);
+    }
+    const num = +value;
+    if (!Number.isFinite(num) || !Number.isInteger(num) || num <= 0) {
+        throw new Error(`${flag} must be a positive integer`);
+    }
+    return num;
+}
+export function typeFromOptions(value) {
+    if (value !== 'lease' && value !== 'permabuy') {
+        throw new Error("Must provide --type of 'lease' or 'permabuy'");
+    }
+    return value;
+}
+export function paidByFromArNSOptions(paidBy) {
+    return paidBy !== undefined && paidBy.length > 0 ? paidBy : undefined;
+}
+// A price quote depends only on the name (length), type, and years — NOT on the
+// ANT the name will resolve to. The service ignores `processId` for pricing, but
+// the SDK's Buy-Name validation still requires a non-empty one, so we substitute
+// this obvious placeholder when the user omits `--process-id` from `arns-price`.
+// (`buy-arns-name` still requires a real `--process-id`.)
+const PRICING_PLACEHOLDER_PROCESS_ID = 'pricing-only-no-process-id';
+/**
+ * Infer the ArNS pricing intent from the provided flags:
+ * - `--type` present            -> Buy-Name (lease needs --years; --process-id optional for pricing)
+ * - `--increase-qty` present    -> Increase-Undername-Limit
+ * - `--years` present (no type) -> Extend-Lease
+ * - otherwise                   -> Upgrade-Name
+ */
+export function arnsPriceParamsFromOptions(options) {
+    const name = requiredNameFromOptions(options);
+    if (options.type !== undefined) {
+        const type = typeFromOptions(options.type);
+        const processId = options.processId ?? PRICING_PLACEHOLDER_PROCESS_ID;
+        if (type === 'lease') {
+            return {
+                intent: 'Buy-Name',
+                name,
+                type: 'lease',
+                years: positiveIntFromOption(options.years, '--years'),
+                processId,
+            };
+        }
+        return {
+            intent: 'Buy-Name',
+            name,
+            type: 'permabuy',
+            processId,
+        };
+    }
+    if (options.increaseQty !== undefined) {
+        return {
+            intent: 'Increase-Undername-Limit',
+            name,
+            increaseQty: positiveIntFromOption(options.increaseQty, '--increase-qty'),
+        };
+    }
+    if (options.years !== undefined) {
+        return {
+            intent: 'Extend-Lease',
+            name,
+            years: positiveIntFromOption(options.years, '--years'),
+        };
+    }
+    return { intent: 'Upgrade-Name', name };
+}
+function creditsFromWinc(winc) {
+    return new BigNumber(winc).dividedBy(wincPerCredit).toFixed(12);
+}
+/** Rethrow a 402 as a clear, actionable "top up" message. */
+async function withCreditErrorMapping(fn) {
+    try {
+        return await fn();
+    }
+    catch (error) {
+        if (error instanceof InsufficientCreditsError) {
+            throw new Error('Insufficient Turbo credits to complete this ArNS purchase. ' +
+                'Top up your balance (e.g. `turbo top-up` or `turbo crypto-fund`) and retry.');
+        }
+        throw error;
+    }
+}
+function logPurchaseResult(action, result) {
+    console.log(JSON.stringify({
+        message: `${action} submitted!`,
+        nonce: result.nonce,
+        arioWriteId: result.arioWriteResult?.id,
+        purchaseReceipt: result.purchaseReceipt,
+    }, null, 2));
+    console.log(`\nTrack this purchase with:\n  turbo arns-purchase-status --nonce ${result.nonce}`);
+}
+export async function arnsPrice(options, turbo) {
+    const params = arnsPriceParamsFromOptions(options);
+    const client = turbo ?? TurboFactory.unauthenticated(configFromOptions(options));
+    const { winc, mARIO } = await client.getArNSPriceForName(params);
+    console.log(JSON.stringify({
+        name: params.name,
+        intent: params.intent,
+        winc,
+        credits: creditsFromWinc(winc),
+        mARIO,
+    }, null, 2));
+}
+export async function buyArNSName(options, turbo) {
+    const name = requiredNameFromOptions(options);
+    const type = typeFromOptions(options.type);
+    const paidBy = paidByFromArNSOptions(options.paidBy);
+    // `--process-id` is OPTIONAL: omit it to have Turbo custodially provision the
+    // ANT (Turbo spawns + owns it — Model A); supply it to point the name at a
+    // user-owned ANT (Model B). When omitted, no `processId` is sent.
+    const processId = options.processId;
+    const client = turbo ?? (await turboFromOptions(options));
+    const result = await withCreditErrorMapping(() => type === 'lease'
+        ? client.buyArNSName({
+            name,
+            type: 'lease',
+            years: positiveIntFromOption(options.years, '--years'),
+            processId,
+            paidBy,
+        })
+        : client.buyArNSName({ name, type: 'permabuy', processId, paidBy }));
+    logPurchaseResult('ArNS name purchase', result);
+}
+export async function extendArNSLease(options, turbo) {
+    const name = requiredNameFromOptions(options);
+    const years = positiveIntFromOption(options.years, '--years');
+    const paidBy = paidByFromArNSOptions(options.paidBy);
+    const client = turbo ?? (await turboFromOptions(options));
+    const result = await withCreditErrorMapping(() => client.extendArNSLease({ name, years, paidBy }));
+    logPurchaseResult('ArNS lease extension', result);
+}
+export async function increaseArNSUndernames(options, turbo) {
+    const name = requiredNameFromOptions(options);
+    const increaseQty = positiveIntFromOption(options.increaseQty, '--increase-qty');
+    const paidBy = paidByFromArNSOptions(options.paidBy);
+    const client = turbo ?? (await turboFromOptions(options));
+    const result = await withCreditErrorMapping(() => client.increaseArNSUndernameLimit({ name, increaseQty, paidBy }));
+    logPurchaseResult('ArNS undername limit increase', result);
+}
+export async function upgradeArNSName(options, turbo) {
+    const name = requiredNameFromOptions(options);
+    const paidBy = paidByFromArNSOptions(options.paidBy);
+    const client = turbo ?? (await turboFromOptions(options));
+    const result = await withCreditErrorMapping(() => client.upgradeArNSName({ name, paidBy }));
+    logPurchaseResult('ArNS name upgrade (to permabuy)', result);
+}
+export async function arnsPurchaseStatus(options, turbo) {
+    if (options.nonce === undefined || options.nonce.length === 0) {
+        throw new Error('Must provide a --nonce to look up purchase status');
+    }
+    const client = turbo ?? TurboFactory.unauthenticated(configFromOptions(options));
+    const status = await client.getArNSPurchaseStatus({ nonce: options.nonce });
+    const state = status.failedDate !== undefined
+        ? 'failed'
+        : status.messageId
+            ? 'success'
+            : 'pending';
+    console.log(JSON.stringify({ state, ...status }, null, 2));
+}
+export async function transferArNSAnt(options, turbo) {
+    if (options.antId === undefined) {
+        throw new Error('Must provide an --ant-id to transfer');
+    }
+    if (options.target === undefined) {
+        throw new Error('Must provide a --target address to transfer the ANT to');
+    }
+    const client = turbo ?? (await turboFromOptions(options));
+    const result = await client.transferArNSAnt({
+        antId: options.antId,
+        target: options.target,
+    });
+    console.log(JSON.stringify({ message: 'ANT transfer submitted!', ...result }, null, 2));
+}
+export async function setArNSRecord(options, turbo) {
+    if (options.antId === undefined) {
+        throw new Error('Must provide an --ant-id to set a record on');
+    }
+    if (options.transactionId === undefined) {
+        throw new Error('Must provide a --transaction-id for the record');
+    }
+    const ttlSeconds = positiveIntFromOption(options.ttlSeconds, '--ttl-seconds');
+    const client = turbo ?? (await turboFromOptions(options));
+    const result = await client.setArNSRecord({
+        antId: options.antId,
+        undername: options.undername ?? '@',
+        transactionId: options.transactionId,
+        ttlSeconds,
+    });
+    console.log(JSON.stringify({ message: 'ArNS record set!', ...result }, null, 2));
+}
+export async function removeArNSRecord(options, turbo) {
+    if (options.antId === undefined) {
+        throw new Error('Must provide an --ant-id to remove a record from');
+    }
+    if (options.undername === undefined || options.undername.length === 0) {
+        throw new Error('Must provide an --undername to remove');
+    }
+    const client = turbo ?? (await turboFromOptions(options));
+    const result = await client.removeArNSRecord({
+        antId: options.antId,
+        undername: options.undername,
+    });
+    console.log(JSON.stringify({ message: 'ArNS record removed!', ...result }, null, 2));
+}

package/lib/esm/cli/commands/freeStatus.js

@@ -0,0 +1,44 @@
+/**
+ * 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 { TurboFactory } from '../../node/factory.js';
+import { addressOrPrivateKeyFromOptions, configFromOptions } from '../utils.js';
+export async function freeStatus(options) {
+    const config = configFromOptions(options);
+    const { address, privateKey } = await addressOrPrivateKeyFromOptions(options);
+    const { bytesRemaining, nativeAddress } = await (async () => {
+        if (address !== undefined) {
+            return {
+                ...(await TurboFactory.unauthenticated(config).getFreeStatus(address)),
+                nativeAddress: address,
+            };
+        }
+        if (privateKey === undefined) {
+            throw new Error('Must provide an (--address) or use a valid wallet');
+        }
+        const turbo = TurboFactory.authenticated({
+            ...config,
+            privateKey,
+        });
+        return {
+            ...(await turbo.getFreeStatus()),
+            nativeAddress: await turbo.signer.getNativeAddress(),
+        };
+    })();
+    console.log(`Turbo free-tier allowance for Native Address "${nativeAddress}"\n` +
+        (bytesRemaining === null
+            ? 'Free bytes remaining: unlimited (exempt/partner wallet)'
+            : `Free bytes remaining: ${bytesRemaining}`));
+}

package/lib/esm/cli/commands/index.js

@@ -13,8 +13,10 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+export * from './arns.js';
 export * from './balance.js';
 export * from './cryptoFund.js';
+export * from './freeStatus.js';
 export * from './price.js';
 export * from './topUp.js';
 export * from './uploadFile.js';

package/lib/esm/cli/options.js

@@ -186,6 +186,51 @@ 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)',
+    },
+    arnsProcessId: {
+        alias: '--process-id <processId>',
+        description: 'ANT process ID the ArNS name resolves to (Buy-Name). Optional: omit for Turbo custodial provisioning (Turbo owns the ANT); supply for a user-owned ANT',
+    },
+    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',
+    },
 };
 export const walletOptions = [
     optionMap.walletFile,
@@ -239,3 +284,54 @@ 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,
+    optionMap.arnsProcessId,
+];
+export const buyArNSNameOptions = [
+    ...walletOptions,
+    optionMap.arnsName,
+    optionMap.arnsType,
+    optionMap.arnsYears,
+    optionMap.arnsProcessId,
+    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.arnsAntId,
+    optionMap.arnsTarget,
+];
+export const setArNSRecordOptions = [
+    ...walletOptions,
+    optionMap.arnsAntId,
+    optionMap.arnsUndername,
+    optionMap.arnsTransactionId,
+    optionMap.arnsTtlSeconds,
+];
+export const removeArNSRecordOptions = [
+    ...walletOptions,
+    optionMap.arnsAntId,
+    optionMap.arnsUndername,
+];

package/lib/esm/common/http.js

@@ -43,7 +43,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 +55,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, {

package/lib/esm/common/index.js

@@ -18,3 +18,6 @@ export * from './payment.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';

package/lib/esm/common/payment.js

@@ -14,7 +14,10 @@
  * limitations under the License.
  */
 import { BigNumber } from 'bignumber.js';
+import { arNSPurchaseIntents, } from '../types.js';
 import { isAnyValidUserAddress } from '../utils/common.js';
+import { FailedRequestError, InsufficientCreditsError, ProvidedInputError, } from '../utils/errors.js';
+import { uuidV4 } from '../utils/uuid.js';
 import { defaultRetryConfig } from './http.js';
 import { TurboHTTPService } from './http.js';
 import { Logger } from './logger.js';
@@ -47,6 +50,15 @@ export class TurboUnauthenticatedPaymentService {
                 receivedApprovals: [],
             };
     }
+    async getFreeStatus(address) {
+        const status = await this.httpService.get({
+            endpoint: `/account/free?address=${address}`,
+            allowedStatuses: [200, 404],
+        });
+        // Normalize: preserve a legitimate `0` (free tier off) or `null` (unlimited),
+        // and coerce a missing field (e.g. a 404 body) to `null`.
+        return { bytesRemaining: status?.bytesRemaining ?? null };
+    }
     getFiatRates() {
         return this.httpService.get({
             endpoint: '/rates',
@@ -91,6 +103,90 @@ export 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 (!arNSPurchaseIntents.includes(p.intent)) {
+            throw new ProvidedInputError(`Invalid ArNS intent '${p.intent}'. Expected one of: ${arNSPurchaseIntents.join(', ')}.`);
+        }
+        if (typeof p.name !== 'string' || p.name.length === 0) {
+            throw new 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 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 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 ProvidedInputError('A lease `Buy-Name` requires a positive `years`.');
+                }
+                break;
+            case 'Extend-Lease':
+                if (!isPositiveNumber(p.years)) {
+                    throw new ProvidedInputError('Extend-Lease requires a positive `years`.');
+                }
+                break;
+            case 'Increase-Undername-Limit':
+                if (!isPositiveNumber(p.increaseQty)) {
+                    throw new 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}` : '';
@@ -255,6 +351,122 @@ export class TurboAuthenticatedPaymentService extends TurboUnauthenticatedPaymen
         userAddress ??= await this.signer.getNativeAddress();
         return super.getBalance(userAddress);
     }
+    async getFreeStatus(userAddress) {
+        userAddress ??= await this.signer.getNativeAddress();
+        return super.getFreeStatus(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 = 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 FailedRequestError && error.status === 402) {
+                throw new 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 = 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 = 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 = 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 });