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

package/lib/esm/common/payment.js

@@ -14,7 +14,11 @@
  * limitations under the License.
  */
 import { BigNumber } from 'bignumber.js';
+import { arNSPurchaseIntents, fiatCurrencyTypes, isCurrency, } from '../types.js';
 import { isAnyValidUserAddress } from '../utils/common.js';
+import { FailedRequestError, FiatPaymentsDisabledError, InsufficientCreditsError, ProvidedInputError, } from '../utils/errors.js';
+import { uuidV4 } from '../utils/uuid.js';
+import { arNSKeywordsField, arNSMetadataField, arNSOwnerProofHeaders, buildArNSCustodyMessage, } from './arnsActions.js';
 import { defaultRetryConfig } from './http.js';
 import { TurboHTTPService } from './http.js';
 import { Logger } from './logger.js';
@@ -34,7 +38,7 @@ export class TurboUnauthenticatedPaymentService {
     }
     async getBalance(address) {
         const balance = await this.httpService.get({
-            endpoint: `/account/balance/${this.token}?address=${address}`,
+            endpoint: `/account/balance/${this.token}?address=${encodeURIComponent(address)}`,
             allowedStatuses: [200, 404],
         });
         return balance.winc
@@ -47,6 +51,31 @@ export class TurboUnauthenticatedPaymentService {
                 receivedApprovals: [],
             };
     }
+    async getFreeStatus(address) {
+        const status = await this.httpService.get({
+            endpoint: `/account/free?address=${encodeURIComponent(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 };
+    }
+    /**
+     * Returns the ArNS names a wallet owns or controls -- both custodial names
+     * bought via Turbo's ArNS-with-credits feature (Turbo may spawn and hold
+     * the ANT on the caller's behalf, depending on the buy) and self-custody
+     * names, in one list. See `TurboArNSName` for field semantics, including
+     * the `custodial` flag distinguishing the two.
+     *
+     * To read a name's current records or lease/expiration state, use
+     * `@ar.io/sdk` directly against the returned `antId` -- it talks to the
+     * chain directly and needs no round-trip through this SDK/backend.
+     */
+    getArNSNames(address) {
+        return this.httpService.get({
+            endpoint: `/arns/my-names/${encodeURIComponent(address)}`,
+        });
+    }
     getFiatRates() {
         return this.httpService.get({
             endpoint: '/rates',
@@ -91,6 +120,206 @@ 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);
+        const price = await this.httpService.get({
+            endpoint: `/arns/price/${params.intent.toLowerCase()}/${encodeURIComponent(params.name)}${this.buildArNSPurchaseQuery(params)}`,
+        });
+        // Normalize the figure to charge into ONE field. `winc` is the name only
+        // and excludes the ANT spawn surcharge — for a Buy-Name that surcharge can
+        // exceed the name's own price, so a caller reading `winc` silently
+        // under-quotes every purchase. Surfacing `wincTotal` makes the correct
+        // field the obvious one.
+        return {
+            ...price,
+            wincTotal: price.wincTotalWithAntSpawn ?? price.winc,
+        };
+    }
+    /**
+     * Preview the flat credits margin one of the eight non-purchase actions
+     * (everything except Buy-Name/Extend-Lease/Upgrade-Name/
+     * Increase-Undername-Limit) will debit, without creating it. Those four
+     * purchase actions are priced by `getArNSPriceForName` instead — their
+     * cost is dominated by the ARIO purchase, not this margin, so this route
+     * rejects them.
+     *
+     * No signature required: this mirrors `getArNSPriceForName`'s read-only,
+     * unauthenticated shape rather than `getArNSActionStatus`'s (which happens
+     * to live on the authenticated client today despite needing no signature
+     * either).
+     */
+    async getArNSActionPrice(action) {
+        return this.httpService.get({
+            endpoint: `/arns/actions/${action}/price`,
+        });
+    }
+    /**
+     * 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/${encodeURIComponent(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}` : '';
+    }
+    /**
+     * Quote a fiat (Stripe) ArNS purchase — buy a name with a credit card in one
+     * step, with no Turbo Credits top-up in between.
+     *
+     * Returns the recorded `purchaseQuote` (its `nonce` is what
+     * `getArNSPurchaseStatus` polls) plus the Stripe `paymentSession` to complete
+     * payment with. For `payment-intent`, confirm client-side with
+     * `stripe.confirmCardPayment(paymentSession.client_secret, ...)`, then poll
+     * the nonce until the purchase reports success or failure.
+     *
+     * Throws {@link FiatPaymentsDisabledError} when the service has Stripe turned
+     * off (normal in the testnet sandbox) so callers can fall back to the
+     * credit-paid path without string-matching a generic 503.
+     */
+    async getArNSFiatPurchaseQuote(params) {
+        this.validateArNSPurchaseParams(params);
+        const { address, currency, method = 'payment-intent', promoCodes = [], } = params;
+        if (typeof address !== 'string' || address.length === 0) {
+            throw new ProvidedInputError('A destination `address` is required for a fiat ArNS purchase quote.');
+        }
+        if (!isCurrency(currency)) {
+            throw new ProvidedInputError(`Invalid currency '${currency}'. Supported: ${fiatCurrencyTypes.join(', ')}`);
+        }
+        // Every interpolated segment is encoded. Five user-controlled values land in
+        // the path here, and an unencoded one (e.g. a name or address containing
+        // `../`) would silently retarget the request at another route.
+        const segments = [
+            method,
+            address,
+            currency,
+            params.intent,
+            params.name,
+        ].map((segment) => encodeURIComponent(segment));
+        const query = this.buildArNSFiatQuoteQuery(params, promoCodes);
+        try {
+            return await this.httpService.get({
+                endpoint: `/arns/quote/${segments.join('/')}${query}`,
+            });
+        }
+        catch (error) {
+            // The service returns 503 both for "Stripe is disabled" and for internal
+            // errors, so the body is what disambiguates them.
+            if (error instanceof FailedRequestError &&
+                error.status === 503 &&
+                /Fiat \(Stripe\).*disabled/i.test(error.message)) {
+                throw new FiatPaymentsDisabledError(error.message);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Query string for a fiat quote. Distinct from `buildArNSPurchaseQuery`
+     * because this route takes `uiMode` + its paired URLs and has no `paidBy`
+     * (fiat has no delegated payer), and because promo codes must be REPEATED
+     * params here: the service reads them with `parseQueryParams`, which treats a
+     * comma-joined string as one code rather than several.
+     */
+    buildArNSFiatQuoteQuery(params, promoCodes) {
+        const { type, years, increaseQty, processId } = params;
+        const search = new URLSearchParams();
+        if (type !== undefined)
+            search.set('type', type);
+        if (years !== undefined)
+            search.set('years', `${years}`);
+        if (increaseQty !== undefined)
+            search.set('increaseQty', `${increaseQty}`);
+        if (processId !== undefined)
+            search.set('processId', processId);
+        const uiMode = params.uiMode;
+        if (uiMode !== undefined)
+            search.set('uiMode', uiMode);
+        if (uiMode === 'embedded') {
+            const { returnUrl } = params;
+            if (returnUrl !== undefined)
+                search.set('returnUrl', returnUrl);
+        }
+        else {
+            const { successUrl, cancelUrl } = params;
+            if (successUrl !== undefined)
+                search.set('successUrl', successUrl);
+            if (cancelUrl !== undefined)
+                search.set('cancelUrl', cancelUrl);
+        }
+        for (const code of promoCodes) {
+            search.append('promoCode', code);
+        }
+        const query = search.toString();
+        return query.length > 0 ? `?${query}` : '';
+    }
     appendPromoCodesToQuery(promoCodes) {
         const promoCodesQuery = promoCodes.join(',');
         return promoCodesQuery ? `promoCode=${promoCodesQuery}` : '';
@@ -191,7 +420,7 @@ export class TurboUnauthenticatedPaymentService {
     }
     async getCreditShareApprovals({ userAddress, }) {
         const response = await this.httpService.get({
-            endpoint: `/account/approvals/get?userAddress=${userAddress}`,
+            endpoint: `/account/approvals/get?userAddress=${encodeURIComponent(userAddress)}`,
             allowedStatuses: [200, 404],
         });
         if (response?.givenApprovals === undefined &&
@@ -255,6 +484,323 @@ export class TurboAuthenticatedPaymentService extends TurboUnauthenticatedPaymen
         userAddress ??= await this.signer.getNativeAddress();
         return super.getBalance(userAddress);
     }
+    /**
+     * Quote a fiat (Stripe) ArNS purchase. `address` defaults to this signer's
+     * native address — the wallet that will own the name — so the common case
+     * needs no address at all. Pass one explicitly to buy on another wallet's
+     * behalf; the route takes the destination as a path param and requires no
+     * signature, which is why it is available unauthenticated too.
+     */
+    async getArNSFiatPurchaseQuote(params) {
+        const address = params.address ?? (await this.signer.getNativeAddress());
+        return super.getArNSFiatPurchaseQuote({
+            ...params,
+            address,
+        });
+    }
+    async getFreeStatus(userAddress) {
+        userAddress ??= await this.signer.getNativeAddress();
+        return super.getFreeStatus(userAddress);
+    }
+    /**
+     * The signer's OWN completed top-up history (crypto + fiat), merged newest
+     * first and keyset-paginated. This is a SIGNED GET: unlike `getBalance` /
+     * `getFreeStatus` (which name a wallet by `?address=`), payment history is
+     * self-scoped and returns only the rows belonging to the signing wallet — the
+     * service reads the address from the signature, never a query param.
+     *
+     * We sign the bare nonce (no action-binding of `limit`/`cursor`) to match the
+     * service's `verifySignature` middleware; the pagination params ride in the
+     * query string. Pass `cursor` from a prior response to fetch the next page.
+     */
+    async getPaymentHistory({ limit, cursor, } = {}) {
+        const headers = await this.signer.generateSignedRequestHeaders();
+        const query = new URLSearchParams();
+        if (limit !== undefined) {
+            query.set('limit', `${limit}`);
+        }
+        if (cursor !== undefined) {
+            query.set('cursor', cursor);
+        }
+        const queryString = query.toString();
+        return this.httpService.get({
+            endpoint: `/account/payments${queryString ? `?${queryString}` : ''}`,
+            headers,
+            allowedStatuses: [200],
+        });
+    }
+    /**
+     * 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.
+     */
+    // ===== ArNS actions — the sponsored surface =====
+    //
+    // Every ArNS operation is an ACTION, and an action has exactly one of two
+    // shapes, chosen by the SERVER rather than the caller: either Turbo already
+    // holds the authority (`completed`), or the ANT owner must sign a transaction
+    // Turbo has already fee-payer-signed (`awaiting-signature`).
+    //
+    // The shape is not stable per action, which is why callers must branch on
+    // `status` and never on which action they asked for: `set-record` completes
+    // alone while Turbo is a controller, and degrades to `awaiting-signature`
+    // the moment the customer revokes Turbo.
+    //
+    // This replaced `/arns/purchase/{intent}/{name}`, `/arns/transfer/{antId}`
+    // and `/arns/manage/*`, which were deleted along with Turbo-custodial ANTs.
+    // Turbo now takes custody of nothing: every ANT is minted straight to the
+    // customer.
+    /**
+     * Create an action. Returns `completed` or `awaiting-signature`.
+     *
+     * Credits are debited HERE, not at `/sign`. Capture the returned `nonce`
+     * before prompting for a signature: it is the idempotency key, and polling
+     * it is how you resume. Never re-create an action to "retry" — that debits
+     * a second time. An abandoned action is refunded automatically.
+     */
+    async createArNSAction(action, params = {}, ownerProof) {
+        const nonce = uuidV4();
+        const headers = {
+            ...(await this.signer.generateSignedRequestHeaders(nonce)),
+            'content-type': 'application/json',
+        };
+        // Record actions carry a SECOND signature, from the ANT owner's Solana key
+        // over a different message. It travels in its own `x-owner-*` headers
+        // because two signatures cannot share one header set.
+        if (ownerProof !== undefined) {
+            Object.assign(headers, await arNSOwnerProofHeaders(ownerProof.owner, ownerProof.message, uuidV4()));
+        }
+        try {
+            return await this.httpService.post({
+                endpoint: `/arns/actions/${action}`,
+                headers,
+                data: Buffer.from(JSON.stringify(params)),
+                // Non-idempotent signed write that has already debited. A blind retry
+                // risks paying twice for one name; poll the nonce instead.
+                retry: false,
+            });
+        }
+        catch (error) {
+            if (error instanceof FailedRequestError && error.status === 402) {
+                throw new InsufficientCreditsError(error.message);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Submit the owner-signed transaction for an `awaiting-signature` action.
+     *
+     * `signedTransaction` is the FULL serialized transaction, base64 — not just
+     * the signature. Replaying a completed action returns `alreadyCompleted:
+     * true` rather than buying twice, so this is safe to call again if a
+     * response is lost.
+     */
+    async signArNSAction(nonce, signedTransaction) {
+        return this.httpService.post({
+            endpoint: `/arns/actions/${nonce}/sign`,
+            headers: {
+                ...(await this.signer.generateSignedRequestHeaders(uuidV4())),
+                'content-type': 'application/json',
+            },
+            data: Buffer.from(JSON.stringify({ transaction: signedTransaction })),
+            retry: false,
+        });
+    }
+    /**
+     * Status of an action by nonce. Open — no signature required — so it works
+     * from a status page or callback handler that never holds the payer's key.
+     *
+     * Terminal success carries `messageId`; terminal failure carries
+     * `failedDate`.
+     */
+    async getArNSActionStatus(nonce) {
+        return this.httpService.get({
+            endpoint: `/arns/actions/${nonce}`,
+        });
+    }
+    /**
+     * Run an action to a terminal state, signing if the server asks for it.
+     *
+     * This is the two-shape branch, once, in one place — so callers cannot
+     * hardcode which actions need a signature and break when a customer
+     * exercises ownership.
+     */
+    async completeArNSAction(action, params, owner, opts = {}, ownerProofMessage) {
+        const created = await this.createArNSAction(action, params, owner !== undefined && ownerProofMessage !== undefined
+            ? { owner, message: ownerProofMessage }
+            : undefined);
+        // Fires before any wallet prompt: the action is already debited, so the
+        // caller needs the nonce persisted even if the user walks away here.
+        await opts.onNonce?.(created.nonce);
+        if (created.status === 'completed')
+            return created;
+        if (owner === undefined) {
+            throw new Error(`ArNS action "${action}" requires the ANT owner's signature, but no owner signer was provided. ` +
+                `Pass \`owner\`, or drive createArNSAction/signArNSAction yourself. ` +
+                `Nonce ${created.nonce} is already debited — poll it rather than re-creating.`);
+        }
+        const signed = await owner.signTransaction(created.transaction);
+        return this.signArNSAction(created.nonce, signed);
+    }
+    /**
+     * Buy a name. The ANT is minted straight to `owner` — Turbo never holds it.
+     *
+     * This is the ONLY action that always needs the owner's signature:
+     * `ario_ant::initialize` is the one instruction in the whole lifecycle that
+     * requires the ANT owner's key. The customer signs once, here, and never
+     * again unless they change controllers or transfer the name.
+     *
+     * The owner needs a Solana key to sign with, NOT a funded one — Turbo pays
+     * every lamport of fee and rent.
+     */
+    async buyArNSName({ name, owner, type = 'lease', years, paidBy, onNonce, }) {
+        return this.completeArNSAction('buy-name', {
+            name,
+            ownerAddress: await owner.getAddress(),
+            type,
+            ...(years !== undefined ? { years } : {}),
+            ...(paidBy !== undefined ? { paidBy } : {}),
+        }, owner, { onNonce });
+    }
+    /** Extend a lease. Permissionless on chain — no owner signature needed. */
+    async extendArNSLease({ name, years, paidBy, onNonce, }) {
+        return this.completeArNSAction('extend-lease', { name, years, ...(paidBy !== undefined ? { paidBy } : {}) }, undefined, { onNonce });
+    }
+    /** Upgrade a lease to a permanent name. No owner signature needed. */
+    async upgradeArNSName({ name, paidBy, onNonce, }) {
+        return this.completeArNSAction('upgrade-name', { name, ...(paidBy !== undefined ? { paidBy } : {}) }, undefined, { onNonce });
+    }
+    /** Raise the undername limit. No owner signature needed. */
+    async increaseArNSUndernameLimit({ name, increaseQty, paidBy, onNonce, }) {
+        return this.completeArNSAction('increase-undername-limit', { name, increaseQty, ...(paidBy !== undefined ? { paidBy } : {}) }, undefined, { onNonce });
+    }
+    /**
+     * Point a name (or undername) at an Arweave transaction.
+     *
+     * Costs a small credit margin — never SOL, which Turbo sponsors. Completes in one call while Turbo is
+     * a controller of the ANT, and returns `awaiting-signature` once the customer
+     * has revoked Turbo, at which point `owner` signs it themselves. Both paths
+     * are handled here.
+     *
+     * The owner proof is required EITHER WAY: Turbo is directing its own
+     * controller authority over an asset someone else owns, so nothing on chain
+     * records the owner's consent and we demand it. It is a MESSAGE signature,
+     * not a transaction — cheap and offline, but still a wallet prompt.
+     */
+    async setArNSRecord({ antId, owner, transactionId, undername = '@', ttlSeconds = 3600, onNonce, }) {
+        return this.completeArNSAction('set-record', {
+            antId,
+            ownerAddress: await owner.getAddress(),
+            transactionId,
+            undername,
+            ttlSeconds,
+        }, owner, { onNonce }, buildArNSCustodyMessage('set-record', [
+            antId,
+            undername,
+            transactionId,
+            String(ttlSeconds),
+        ]));
+    }
+    /** Remove a record (an undername). Costs credits, never SOL. */
+    async removeArNSRecord({ antId, owner, undername, onNonce, }) {
+        return this.completeArNSAction('remove-record', { antId, ownerAddress: await owner.getAddress(), undername }, owner, { onNonce }, buildArNSCustodyMessage('remove-record', [antId, undername]));
+    }
+    /**
+     * Edit a RECORD's metadata — its display name, logo, description, keywords.
+     *
+     * Costs a small credit margin (never SOL), and is owner-or-controller on
+     * chain, so it behaves exactly like
+     * {@link setArNSRecord}: Turbo-alone while it is a controller, owner-signed
+     * after a revoke.
+     *
+     * Fields are TRI-STATE. Omit one to leave it unchanged; pass `null` to clear
+     * it. Those are bound distinctly by the owner proof, so "clear the
+     * description" and "set it to empty" are different authorizations.
+     *
+     * Note this is RECORD metadata. ANT-level metadata (the ANT's own name,
+     * ticker, description, keywords, logo) is NOT sponsored and stays on the
+     * direct-signer path via `@ar.io/sdk`.
+     */
+    async setArNSRecordMetadata({ antId, owner, undername = '@', displayName, recordLogo, recordDescription, recordKeywords, onNonce, }) {
+        return this.completeArNSAction('set-record-metadata', {
+            antId,
+            ownerAddress: await owner.getAddress(),
+            undername,
+            // Sent explicitly, including `null`, so the server sees the same
+            // tri-state the proof was signed over.
+            ...(displayName !== undefined ? { displayName } : {}),
+            ...(recordLogo !== undefined ? { recordLogo } : {}),
+            ...(recordDescription !== undefined ? { recordDescription } : {}),
+            ...(recordKeywords !== undefined ? { recordKeywords } : {}),
+        }, owner, { onNonce }, buildArNSCustodyMessage('set-record-metadata', [
+            antId,
+            undername,
+            arNSMetadataField(displayName),
+            arNSMetadataField(recordLogo),
+            arNSMetadataField(recordDescription),
+            arNSKeywordsField(recordKeywords),
+        ]));
+    }
+    /** Clear a record's metadata. Costs credits, never SOL; same two-shape rules. */
+    async removeArNSRecordMetadata({ antId, owner, undername, onNonce, }) {
+        return this.completeArNSAction('remove-record-metadata', { antId, ownerAddress: await owner.getAddress(), undername }, owner, { onNonce }, buildArNSCustodyMessage('remove-record-metadata', [antId, undername]));
+    }
+    /**
+     * Hand ONE record to another address.
+     *
+     * Distinct from {@link transferArNSAnt}, which hands over the whole ANT and
+     * every record on it. Confusing the two gives away far more than intended.
+     */
+    async transferArNSRecord({ antId, owner, undername, target, onNonce, }) {
+        return this.completeArNSAction('transfer-record', { antId, ownerAddress: await owner.getAddress(), undername, target }, owner, { onNonce }, buildArNSCustodyMessage('transfer-record', [antId, undername, target]));
+    }
+    /**
+     * Grant controller rights on the ANT. Omit `target` for Turbo itself, which
+     * is what makes `setArNSRecord` a single call.
+     *
+     * Owner-signed: changing an ANT's access control is an owner-only
+     * instruction. Costs a small credit margin; Turbo funds the ACL page growth
+     * in SOL.
+     */
+    async addArNSController({ antId, owner, target, onNonce, }) {
+        return this.completeArNSAction('add-controller', {
+            antId,
+            ownerAddress: await owner.getAddress(),
+            ...(target !== undefined ? { target } : {}),
+        }, owner, { onNonce });
+    }
+    /**
+     * Revoke controller rights — the escape hatch that keeps "Turbo is not a
+     * custodian" honest.
+     *
+     * Always available, and needs nothing from Turbo but the fee. Costs a small
+     * credit margin rather than SOL.
+     * After revoking, `setArNSRecord` keeps working: it simply starts returning
+     * `awaiting-signature` so the owner signs their own record writes.
+     */
+    async removeArNSController({ antId, owner, target, onNonce, }) {
+        return this.completeArNSAction('remove-controller', {
+            antId,
+            ownerAddress: await owner.getAddress(),
+            ...(target !== undefined ? { target } : {}),
+        }, owner, { onNonce });
+    }
+    /**
+     * Hand the ANT to a new owner. Irreversible: after this lands, `owner` no
+     * longer controls the name. Owner-signed, and sponsored like the rest.
+     */
+    async transferArNSAnt({ antId, owner, target, onNonce, }) {
+        return this.completeArNSAction('transfer', { antId, ownerAddress: await owner.getAddress(), target }, owner, { onNonce });
+    }
+    /**
+     * Defaults to the signer's own address when `userAddress` is omitted
+     * (`null`/`undefined`). Passing `''` does NOT trigger this default --
+     * mirrors `getBalance`'s existing behavior above.
+     */
+    async getArNSNames(userAddress) {
+        userAddress ??= await this.signer.getNativeAddress();
+        return super.getArNSNames(userAddress);
+    }
     async getCreditShareApprovals({ userAddress, }) {
         userAddress ??= await this.signer.getNativeAddress();
         return super.getCreditShareApprovals({ userAddress });

package/lib/esm/common/signer.js

@@ -27,7 +27,7 @@ import { computeAddress } from 'ethers';
 import nacl from 'tweetnacl';
 import { createWalletClient, custom, http } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
-import { baseSepolia } from 'viem/chains';
+import { base } from 'viem/chains';
 import { isEthereumWalletAdapter, isSolanaWalletAdapter, } from '../types.js';
 import { fromB64Url, ownerToAddress as ownerToB64Address, toB64Url, } from '../utils/base64.js';
 import { Logger } from './logger.js';
@@ -53,7 +53,6 @@ export class TurboDataItemAbstractSigner {
             case 'base-eth':
             case 'usdc':
             case 'base-usdc':
-            case 'base-ario':
             case 'polygon-usdc':
                 return computeAddress(computePublicKey(fromB64Url(owner)));
             case 'kyve':
@@ -66,15 +65,27 @@ export class TurboDataItemAbstractSigner {
                 return ownerToB64Address(owner);
         }
     }
-    async generateSignedRequestHeaders() {
-        const nonce = 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 = 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 = toB64Url(this.signer.publicKey);
         return {
             'x-public-key': publicKey,
             'x-nonce': nonce,
             'x-signature': 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() {
@@ -152,13 +163,23 @@ export class TurboDataItemAbstractSigner {
         return this.signer.sign(dataToSign);
     }
 }
+/**
+ * Builds the wallet client x402-fetch signs payment authorizations with.
+ *
+ * The chain matters because `wrapFetchWithPayment` maps `walletClient.chain.id`
+ * to a network name and prefers the matching entry in the service's `accepts`
+ * list. The upload service advertises Base mainnet (`base`), and x402 support
+ * here is limited to `base-usdc`, so mainnet is the correct default. Callers
+ * needing another network can supply their own signer via
+ * `X402Funding({ signer })`.
+ */
 export async function makeX402Signer(arbundlesSigner) {
     // Node: our SDK uses EthereumSigner with a raw private key
     if (arbundlesSigner instanceof EthereumSigner) {
         return createWalletClient({
             account: privateKeyToAccount(('0x' +
                 Buffer.from(arbundlesSigner.key).toString('hex'))),
-            chain: baseSepolia,
+            chain: base,
             transport: http(),
         });
     }
@@ -177,7 +198,7 @@ export async function makeX402Signer(arbundlesSigner) {
         const account = accounts[0];
         return createWalletClient({
             account,
-            chain: baseSepolia,
+            chain: base,
             transport: custom(provider),
         });
     }