@ardrive/turbo-sdk 1.42.0-alpha.7 → 1.42.0-alpha.9

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

@@ -31,10 +31,26 @@ exports.removeArNSRecord = removeArNSRecord;
  * limitations under the License.
  */
 const bignumber_js_1 = require("bignumber.js");
+const arnsActions_js_1 = require("../../common/arnsActions.js");
 const factory_js_1 = require("../../node/factory.js");
 const errors_js_1 = require("../../utils/errors.js");
 const constants_js_1 = require("../constants.js");
 const utils_js_1 = require("../utils.js");
+/**
+ * The ANT owner's Solana key.
+ *
+ * Deliberately separate from the wallet that pays: the payer holds Turbo
+ * credits (and may be Arweave or Ethereum), while the owner holds the ANT and
+ * must be Solana. The owner needs a key to SIGN with, not a funded account —
+ * Turbo is the fee payer on every sponsored action.
+ */
+function ownerFromOptions(options) {
+    if (options.ownerKey === undefined || options.ownerKey === '') {
+        throw new Error('Must provide --owner-key (a base58 Solana secret key) — it owns the ANT and signs for it. ' +
+            'This is separate from the wallet paying in Turbo Credits.');
+    }
+    return (0, arnsActions_js_1.solanaOwnerSigner)(options.ownerKey);
+}
 function requiredNameFromOptions(options) {
     if (options.name === undefined || options.name.length === 0) {
         throw new Error('Must provide an ArNS --name');
@@ -128,10 +144,12 @@ async function withCreditErrorMapping(fn) {
 }
 function logPurchaseResult(action, result) {
     console.log(JSON.stringify({
-        message: `${action} submitted!`,
+        message: `${action} completed!`,
         nonce: result.nonce,
-        arioWriteId: result.arioWriteResult?.id,
-        purchaseReceipt: result.purchaseReceipt,
+        antId: result.antId,
+        // Solana transaction id of the on-chain write.
+        messageId: result.messageId,
+        ...(result.alreadyCompleted === true ? { alreadyCompleted: true } : {}),
     }, null, 2));
     console.log(`\nTrack this purchase with:\n  turbo arns-purchase-status --nonce ${result.nonce}`);
 }
@@ -149,6 +167,14 @@ async function arnsPrice(options, turbo) {
 }
 async function arnsFiatQuote(options, turbo) {
     const params = arnsPriceParamsFromOptions(options);
+    // `arnsPriceParamsFromOptions` substitutes PRICING_PLACEHOLDER_PROCESS_ID for
+    // an omitted Buy-Name `processId`, which is fine for a price lookup but NOT
+    // here: a quote records a real purchase, and that placeholder is not a valid
+    // ANT. Send `processId` only when the caller actually supplied one — omitting
+    // it is what tells Turbo to custodially provision the ANT.
+    if (options.processId === undefined) {
+        delete params.processId;
+    }
     const address = options.address;
     if (address === undefined) {
         throw new Error('A destination --address is required for a fiat ArNS quote.');
@@ -190,20 +216,19 @@ 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;
+    // Every buy mints a fresh ANT straight to `--owner-key`; Turbo never holds
+    // it, and there is no bring-your-own-ANT path any more.
+    const owner = ownerFromOptions(options);
     const client = turbo ?? (await (0, utils_js_1.turboFromOptions)(options));
     const result = await withCreditErrorMapping(() => type === 'lease'
         ? client.buyArNSName({
             name,
+            owner,
             type: 'lease',
             years: positiveIntFromOption(options.years, '--years'),
-            processId,
             paidBy,
         })
-        : client.buyArNSName({ name, type: 'permabuy', processId, paidBy }));
+        : client.buyArNSName({ name, owner, type: 'permabuy', paidBy }));
     logPurchaseResult('ArNS name purchase', result);
 }
 async function extendArNSLease(options, turbo) {
@@ -252,6 +277,7 @@ async function transferArNSAnt(options, turbo) {
     const client = turbo ?? (await (0, utils_js_1.turboFromOptions)(options));
     const result = await client.transferArNSAnt({
         antId: options.antId,
+        owner: ownerFromOptions(options),
         target: options.target,
     });
     console.log(JSON.stringify({ message: 'ANT transfer submitted!', ...result }, null, 2));
@@ -267,6 +293,7 @@ async function setArNSRecord(options, turbo) {
     const client = turbo ?? (await (0, utils_js_1.turboFromOptions)(options));
     const result = await client.setArNSRecord({
         antId: options.antId,
+        owner: ownerFromOptions(options),
         undername: options.undername ?? '@',
         transactionId: options.transactionId,
         ttlSeconds,
@@ -283,6 +310,7 @@ async function removeArNSRecord(options, turbo) {
     const client = turbo ?? (await (0, utils_js_1.turboFromOptions)(options));
     const result = await client.removeArNSRecord({
         antId: options.antId,
+        owner: ownerFromOptions(options),
         undername: options.undername,
     });
     console.log(JSON.stringify({ message: 'ArNS record removed!', ...result }, null, 2));

package/lib/cjs/cli/options.js

@@ -206,9 +206,9 @@ exports.optionMap = {
         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',
+    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>',
@@ -302,14 +302,12 @@ exports.arnsPriceOptions = [
     exports.optionMap.arnsType,
     exports.optionMap.arnsYears,
     exports.optionMap.arnsIncreaseQty,
-    exports.optionMap.arnsProcessId,
 ];
 exports.arnsFiatQuoteOptions = [
     exports.optionMap.arnsName,
     exports.optionMap.arnsType,
     exports.optionMap.arnsYears,
     exports.optionMap.arnsIncreaseQty,
-    exports.optionMap.arnsProcessId,
     exports.optionMap.address,
     exports.optionMap.currency,
     {
@@ -326,7 +324,7 @@ exports.buyArNSNameOptions = [
     exports.optionMap.arnsName,
     exports.optionMap.arnsType,
     exports.optionMap.arnsYears,
-    exports.optionMap.arnsProcessId,
+    exports.optionMap.arnsOwnerKey,
     exports.optionMap.paidBy,
 ];
 exports.extendArNSLeaseOptions = [
@@ -349,11 +347,13 @@ exports.upgradeArNSNameOptions = [
 exports.arnsPurchaseStatusOptions = [exports.optionMap.arnsNonce];
 exports.transferArNSAntOptions = [
     ...exports.walletOptions,
+    exports.optionMap.arnsOwnerKey,
     exports.optionMap.arnsAntId,
     exports.optionMap.arnsTarget,
 ];
 exports.setArNSRecordOptions = [
     ...exports.walletOptions,
+    exports.optionMap.arnsOwnerKey,
     exports.optionMap.arnsAntId,
     exports.optionMap.arnsUndername,
     exports.optionMap.arnsTransactionId,
@@ -361,6 +361,7 @@ exports.setArNSRecordOptions = [
 ];
 exports.removeArNSRecordOptions = [
     ...exports.walletOptions,
+    exports.optionMap.arnsOwnerKey,
     exports.optionMap.arnsAntId,
     exports.optionMap.arnsUndername,
 ];

package/lib/cjs/common/arnsActions.js

@@ -0,0 +1,102 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildArNSCustodyMessage = buildArNSCustodyMessage;
+exports.arNSOwnerProofHeaders = arNSOwnerProofHeaders;
+exports.solanaOwnerSigner = solanaOwnerSigner;
+exports.emptySignatureSlots = emptySignatureSlots;
+/**
+ * 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 web3_js_1 = require("@solana/web3.js");
+const bs58_1 = __importDefault(require("bs58"));
+const tweetnacl_1 = __importDefault(require("tweetnacl"));
+const base64_js_1 = require("../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).
+ */
+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.
+ */
+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': (0, base64_js_1.toB64Url)(Buffer.from(bs58_1.default.decode(address))),
+        'x-owner-nonce': nonce,
+        'x-owner-signature': (0, base64_js_1.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.
+ */
+function solanaOwnerSigner(secretKey) {
+    const keypair = web3_js_1.Keypair.fromSecretKey(typeof secretKey === 'string' ? bs58_1.default.decode(secretKey) : secretKey);
+    return {
+        getAddress: () => keypair.publicKey.toBase58(),
+        signTransaction: async (transactionBase64) => {
+            const tx = web3_js_1.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) => tweetnacl_1.default.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.
+ */
+function emptySignatureSlots(transactionBase64) {
+    const tx = web3_js_1.VersionedTransaction.deserialize(Buffer.from(transactionBase64, 'base64'));
+    return tx.signatures.filter((sig) => sig.every((byte) => byte === 0)).length;
+}

package/lib/cjs/common/payment.js

@@ -21,6 +21,7 @@ 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 arnsActions_js_1 = require("./arnsActions.js");
 const http_js_1 = require("./http.js");
 const http_js_2 = require("./http.js");
 const logger_js_1 = require("./logger.js");
@@ -62,6 +63,22 @@ class TurboUnauthenticatedPaymentService {
         // 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',
@@ -110,9 +127,18 @@ class TurboUnauthenticatedPaymentService {
         // `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({
+        const price = await this.httpService.get({
             endpoint: `/arns/price/${params.intent.toLowerCase()}/${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,
+        };
     }
     /**
      * Fail fast (client-side) on malformed ArNS requests so JS callers that bypass
@@ -494,112 +520,221 @@ class TurboAuthenticatedPaymentService extends TurboUnauthenticatedPaymentServic
      * 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`).
+    // ===== 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 = (0, uuid_js_1.uuidV4)();
-        const headers = await this.signer.generateSignedRequestHeaders(nonce);
-        let response;
+        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 (0, arnsActions_js_1.arNSOwnerProofHeaders)(ownerProof.owner, ownerProof.message, (0, uuid_js_1.uuidV4)()));
+        }
         try {
-            response = await this.httpService.post({
-                endpoint: `/arns/purchase/${params.intent.toLowerCase()}/${params.name}${this.buildArNSPurchaseQuery(params)}`,
+            return await this.httpService.post({
+                endpoint: `/arns/actions/${action}`,
                 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.
+                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) {
-            // 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',
+    /**
+     * 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((0, uuid_js_1.uuidV4)())),
+                'content-type': 'application/json',
+            },
+            data: Buffer.from(JSON.stringify({ transaction: signedTransaction })),
+            retry: false,
         });
     }
-    extendArNSLease(params) {
-        return this.purchaseArNSName({ ...params, intent: 'Extend-Lease' });
-    }
-    increaseArNSUndernameLimit(params) {
-        return this.purchaseArNSName({
-            ...params,
-            intent: 'Increase-Undername-Limit',
+    /**
+     * 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}`,
         });
     }
-    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');
+    /**
+     * 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);
     }
     /**
-     * Self-custody exit: move a Turbo-custodied ANT to a Solana pubkey you control.
-     * Authenticated with an action-bound, single-use signature.
+     * 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 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
-        });
+    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 });
     }
-    /** 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', [
+    /**
+     * Point a name (or undername) at an Arweave transaction.
+     *
+     * Free — Turbo sponsors the Solana fee. 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 }, (0, arnsActions_js_1.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
-        });
+    /** Remove a record (an undername). Free; same two-shape rules as setArNSRecord. */
+    async removeArNSRecord({ antId, owner, undername, onNonce, }) {
+        return this.completeArNSAction('remove-record', { antId, ownerAddress: await owner.getAddress(), undername }, owner, { onNonce }, (0, arnsActions_js_1.buildArNSCustodyMessage)('remove-record', [antId, undername]));
+    }
+    /**
+     * 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. Free to the customer — Turbo funds the ACL page growth.
+     */
+    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, always free, and needs nothing from Turbo but the fee.
+     * 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();