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

package/lib/cjs/common/arnsActions.js

@@ -4,6 +4,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildArNSCustodyMessage = buildArNSCustodyMessage;
+exports.arNSMetadataField = arNSMetadataField;
+exports.arNSKeywordsField = arNSKeywordsField;
 exports.arNSOwnerProofHeaders = arNSOwnerProofHeaders;
 exports.solanaOwnerSigner = solanaOwnerSigner;
 exports.emptySignatureSlots = emptySignatureSlots;
@@ -39,6 +41,27 @@ const base64_js_1 = require("../utils/base64.js");
 function buildArNSCustodyMessage(action, fields) {
     return ['arns', action, ...fields].join('\n');
 }
+/**
+ * A metadata field's ABSENT/EMPTY distinction, as the bundler binds it.
+ *
+ * `null` (clear the field) must not sign the same message as `''` (set it to
+ * empty), or a signature authorizing one would authorize the other. NUL can
+ * never appear in a value that reached here — the route rejects control
+ * characters — so it is a safe sentinel.
+ */
+function arNSMetadataField(value) {
+    return value === null || value === undefined ? '\u0000' : value;
+}
+/**
+ * Keywords joined on a separator the route rejects INSIDE a keyword, so
+ * `['a,b']` and `['a','b']` cannot be re-partitioned into one another with the
+ * same signature.
+ */
+function arNSKeywordsField(keywords) {
+    return keywords === null || keywords === undefined
+        ? '\u0000'
+        : keywords.join('\u0001');
+}
 /** Solana's signature-type discriminator in Turbo's signed-request scheme. */
 const SOLANA_SIGNATURE_TYPE = 4;
 /**

package/lib/cjs/common/chunked.js

@@ -41,7 +41,7 @@ const chunkingHeader = { 'x-chunking-version': '2' };
  * uploading them in parallel, and emitting progress/error events.
  */
 class ChunkedUploader {
-    constructor({ http, token, maxChunkConcurrency = exports.defaultMaxChunkConcurrency, maxFinalizeMs, chunkByteCount = exports.defaultChunkByteCount, logger = logger_js_1.Logger.default, chunkingMode = 'auto', dataItemByteCount, }) {
+    constructor({ http, token, maxChunkConcurrency = exports.defaultMaxChunkConcurrency, maxFinalizeMs, chunkByteCount = exports.defaultChunkByteCount, logger = logger_js_1.Logger.default, chunkingMode = 'auto', dataItemByteCount, x402, x402RefundIdentity, }) {
         this.assertChunkParams({
             chunkByteCount,
             chunkingMode,
@@ -60,6 +60,9 @@ class ChunkedUploader {
             dataItemByteCount,
         });
         this.maxBacklogQueue = this.maxChunkConcurrency * backlogQueueFactor;
+        this.x402 = x402;
+        this.x402RefundIdentity = x402RefundIdentity;
+        this.dataItemByteCount = dataItemByteCount;
     }
     shouldChunkUpload({ chunkByteCount, chunkingMode, dataItemByteCount, }) {
         if (chunkingMode === 'disabled') {
@@ -98,7 +101,54 @@ class ChunkedUploader {
     /**
      * Initialize or resume an upload session, returning the upload ID.
      */
+    /**
+     * Open a multipart upload paid for with x402.
+     *
+     * The bundler settles the payment at CREATE, before accepting a single chunk
+     * — so an unpaid upload never consumes storage. That is why the size is
+     * declared here and the money moves here, not at finalize.
+     *
+     * The 402 handshake is delegated to `wrapFetchWithPayment`, the same
+     * mechanism the single-shot x402 POST already uses, so the signer and the
+     * spend cap behave identically on both paths.
+     */
+    async initPaidUpload(x402) {
+        if (this.paidUploadId !== undefined) {
+            this.logger.debug('Resuming the already-paid chunked upload', {
+                uploadId: this.paidUploadId,
+            });
+            return this.paidUploadId;
+        }
+        if (this.x402RefundIdentity === undefined) {
+            throw new Error('An x402-paid chunked upload needs a refund identity — it is the Turbo wallet credited if the upload delivers fewer bytes than were paid for.');
+        }
+        const { address, signatureType } = this.x402RefundIdentity;
+        const endpoint = `/chunks/${this.token}/-1/-1?chunkSize=${this.chunkByteCount}` +
+            `&totalBytes=${this.dataItemByteCount}` +
+            `&address=${encodeURIComponent(address)}` +
+            `&signatureType=${signatureType}`;
+        this.logger.debug('Opening an x402-paid chunked upload', {
+            totalBytes: this.dataItemByteCount,
+        });
+        const res = await this.http.get({
+            endpoint: endpoint,
+            headers: chunkingHeader,
+            x402Options: x402,
+        });
+        if (res.chunkSize !== undefined && res.chunkSize !== this.chunkByteCount) {
+            this.logger.warn('Chunk size mismatch! Overriding with server value.', {
+                clientExpected: this.chunkByteCount,
+                serverReturned: res.chunkSize,
+            });
+            this.chunkByteCount = res.chunkSize;
+        }
+        this.paidUploadId = res.id;
+        return res.id;
+    }
     async initUpload() {
+        if (this.x402 !== undefined) {
+            return this.initPaidUpload(this.x402);
+        }
         const res = await this.http.get({
             endpoint: `/chunks/${this.token}/-1/-1?chunkSize=${this.chunkByteCount}`,
             headers: chunkingHeader,

package/lib/cjs/common/http.js

@@ -52,7 +52,18 @@ class TurboHTTPService {
         this.baseURL = url;
         this.retryConfig = retryConfig;
     }
-    async get({ endpoint, signal, allowedStatuses = [200, 202], headers, }) {
+    async get({ endpoint, signal, allowedStatuses = [200, 202], headers, x402Options, }) {
+        if (x402Options !== undefined) {
+            const maxMUSDCAmount = x402Options.maxMUSDCAmount !== undefined
+                ? BigInt(x402Options.maxMUSDCAmount.toString())
+                : undefined;
+            const fetchWithPay = (0, x402_fetch_1.wrapFetchWithPayment)(fetch, x402Options.signer, maxMUSDCAmount);
+            return this.tryRequest(async () => fetchWithPay(this.baseURL + endpoint, {
+                method: 'GET',
+                headers: { ...defaultHeaders, ...headers },
+                signal,
+            }), allowedStatuses);
+        }
         return this.withRetry(() => fetch(this.baseURL + endpoint, {
             method: 'GET',
             headers: { ...defaultHeaders, ...headers },

package/lib/cjs/common/payment.js

@@ -663,7 +663,7 @@ class TurboAuthenticatedPaymentService extends TurboUnauthenticatedPaymentServic
     /**
      * Point a name (or undername) at an Arweave transaction.
      *
-     * Free — Turbo sponsors the Solana fee. Completes in one call while Turbo is
+     * 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.
@@ -687,16 +687,66 @@ class TurboAuthenticatedPaymentService extends TurboUnauthenticatedPaymentServic
             String(ttlSeconds),
         ]));
     }
-    /** Remove a record (an undername). Free; same two-shape rules as setArNSRecord. */
+    /** 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 }, (0, arnsActions_js_1.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 }, (0, arnsActions_js_1.buildArNSCustodyMessage)('set-record-metadata', [
+            antId,
+            undername,
+            (0, arnsActions_js_1.arNSMetadataField)(displayName),
+            (0, arnsActions_js_1.arNSMetadataField)(recordLogo),
+            (0, arnsActions_js_1.arNSMetadataField)(recordDescription),
+            (0, arnsActions_js_1.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 }, (0, arnsActions_js_1.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 }, (0, arnsActions_js_1.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. Free to the customer — Turbo funds the ACL page growth.
+     * 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', {
@@ -709,7 +759,8 @@ class TurboAuthenticatedPaymentService extends TurboUnauthenticatedPaymentServic
      * 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.
+     * 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.
      */

package/lib/cjs/common/turbo.js

@@ -270,15 +270,31 @@ class TurboAuthenticatedClient extends TurboUnauthenticatedClient {
     removeArNSRecord(params) {
         return this.paymentService.removeArNSRecord(params);
     }
-    /** Grant controller rights — omit `target` for Turbo itself. Free. */
+    /** Grant controller rights — omit `target` for Turbo itself. Costs credits. */
     addArNSController(params) {
         return this.paymentService.addArNSController(params);
     }
-    /** Revoke controller rights. Always available, always free. */
+    /** Revoke controller rights. Always available; costs credits, never SOL. */
     removeArNSController(params) {
         return this.paymentService.removeArNSController(params);
     }
-    /** Hand the ANT to a new owner. Irreversible. Free. */
+    /**
+     * Edit a RECORD's metadata (display name, logo, description, keywords).
+     * Free; handles both shapes. Fields are tri-state — omit to leave unchanged,
+     * pass `null` to clear.
+     */
+    setArNSRecordMetadata(params) {
+        return this.paymentService.setArNSRecordMetadata(params);
+    }
+    /** Clear a record's metadata. Costs credits, never SOL; handles both shapes. */
+    removeArNSRecordMetadata(params) {
+        return this.paymentService.removeArNSRecordMetadata(params);
+    }
+    /** Hand ONE record over — not the whole ANT. Costs credits, never SOL. */
+    transferArNSRecord(params) {
+        return this.paymentService.transferArNSRecord(params);
+    }
+    /** Hand the ANT to a new owner. Irreversible. Costs credits, never SOL. */
     transferArNSAnt(params) {
         return this.paymentService.transferArNSAnt(params);
     }

package/lib/cjs/common/upload.js

@@ -225,9 +225,6 @@ class TurboAuthenticatedBaseUploadService extends TurboUnauthenticatedUploadServ
             !this.x402EnabledTokens.includes(this.token)) {
             throw new Error('x402 uploads are not supported for token: ' + this.token);
         }
-        if (params.chunkingMode === 'force' && fundingMode instanceof types_js_1.X402Funding) {
-            throw new Error("Chunking mode 'force' is not supported when x402 is enabled");
-        }
         this.logger.debug('Starting file upload', { params });
         let retries = 0;
         const maxRetries = this.retryConfig.retries ?? 3;
@@ -263,6 +260,19 @@ class TurboAuthenticatedBaseUploadService extends TurboUnauthenticatedUploadServ
             // this result due to the wrapped retry logic of this method.
             try {
                 const { chunkByteCount, maxChunkConcurrency } = params;
+                // Built here rather than after the chunked branch so BOTH paths can
+                // pay with it. Chunked x402 uploads used to be impossible — the
+                // bundler had no way to charge for a multipart upload — so this branch
+                // deliberately fell back to a single request, which capped x402 at the
+                // single-item limit no matter how the client chunked. The bundler now
+                // settles at create, so the fallback is no longer needed.
+                const x402Options = fundingMode instanceof types_js_1.X402Funding
+                    ? {
+                        signer: fundingMode.signer ??
+                            (await (0, signer_js_1.makeX402Signer)(this.signer.signer)),
+                        maxMUSDCAmount: fundingMode.maxMUSDCAmount,
+                    }
+                    : undefined;
                 const chunkedUploader = new chunked_js_1.ChunkedUploader({
                     http: this.httpService,
                     token: this.token,
@@ -272,9 +282,17 @@ class TurboAuthenticatedBaseUploadService extends TurboUnauthenticatedUploadServ
                     dataItemByteCount: dataItemSizeFactory(),
                     chunkingMode: params.chunkingMode,
                     maxFinalizeMs: params.maxFinalizeMs,
+                    ...(x402Options ? { x402: x402Options } : {}),
+                    ...(x402Options
+                        ? {
+                            x402RefundIdentity: {
+                                address: await this.signer.getNativeAddress(),
+                                signatureType: this.signer.signer.signatureType,
+                            },
+                        }
+                        : {}),
                 });
-                if (chunkedUploader.shouldUseChunkUploader &&
-                    !(fundingMode instanceof types_js_1.X402Funding)) {
+                if (chunkedUploader.shouldUseChunkUploader) {
                     const response = await chunkedUploader.upload({
                         dataItemStreamFactory,
                         dataItemSizeFactory,
@@ -284,13 +302,6 @@ class TurboAuthenticatedBaseUploadService extends TurboUnauthenticatedUploadServ
                     });
                     return { ...response, cryptoFundResult };
                 }
-                const x402Options = fundingMode instanceof types_js_1.X402Funding
-                    ? {
-                        signer: fundingMode.signer ??
-                            (await (0, signer_js_1.makeX402Signer)(this.signer.signer)),
-                        maxMUSDCAmount: fundingMode.maxMUSDCAmount,
-                    }
-                    : undefined;
                 const response = await this.uploadSignedDataItem({
                     dataItemStreamFactory,
                     dataItemSizeFactory,

package/lib/cjs/types.js

@@ -117,9 +117,13 @@ exports.arNSPurchaseIntents = [
 /**
  * The nine sponsored ArNS actions.
  *
- * NOT included, because the bundler does not sponsor them: `primary-name`,
- * `release-name`, `reassign`, and ANT metadata (name/description/keywords/logo).
- * Those stay on the direct-signer path and cost the user SOL.
+ * Sponsorship covers these twelve and NOTHING else. Everything else in the
+ * ArNS, ANT and core programs stays on the direct-signer path and costs the
+ * user SOL — notably `BuyReturnedName` (auctions, deliberately excluded: the
+ * premium is unbounded), `ClaimReservedName`, the primary-name flow (which
+ * lives in the ario core program), release/reassign, and ANT-LEVEL metadata.
+ * Note ANT-level metadata is distinct from RECORD-level metadata, which
+ * `set-record-metadata` does sponsor.
  */
 exports.arNSActions = [
     'buy-name',
@@ -131,6 +135,11 @@ exports.arNSActions = [
     'add-controller',
     'remove-controller',
     'transfer',
+    // Record-scoped. Owner-or-controller on chain, so these follow set-record's
+    // degrade-on-revoke shape rather than needing a signature every time.
+    'set-record-metadata',
+    'remove-record-metadata',
+    'transfer-record',
 ];
 // ===== ArNS purchases paid with fiat (Stripe) — no Turbo Credits in between ====
 /**

package/lib/esm/common/arnsActions.js

@@ -30,6 +30,27 @@ import { toB64Url } from '../utils/base64.js';
 export function buildArNSCustodyMessage(action, fields) {
     return ['arns', action, ...fields].join('\n');
 }
+/**
+ * A metadata field's ABSENT/EMPTY distinction, as the bundler binds it.
+ *
+ * `null` (clear the field) must not sign the same message as `''` (set it to
+ * empty), or a signature authorizing one would authorize the other. NUL can
+ * never appear in a value that reached here — the route rejects control
+ * characters — so it is a safe sentinel.
+ */
+export function arNSMetadataField(value) {
+    return value === null || value === undefined ? '\u0000' : value;
+}
+/**
+ * Keywords joined on a separator the route rejects INSIDE a keyword, so
+ * `['a,b']` and `['a','b']` cannot be re-partitioned into one another with the
+ * same signature.
+ */
+export function arNSKeywordsField(keywords) {
+    return keywords === null || keywords === undefined
+        ? '\u0000'
+        : keywords.join('\u0001');
+}
 /** Solana's signature-type discriminator in Turbo's signed-request scheme. */
 const SOLANA_SIGNATURE_TYPE = 4;
 /**

package/lib/esm/common/chunked.js

@@ -35,7 +35,7 @@ const chunkingHeader = { 'x-chunking-version': '2' };
  * uploading them in parallel, and emitting progress/error events.
  */
 export class ChunkedUploader {
-    constructor({ http, token, maxChunkConcurrency = defaultMaxChunkConcurrency, maxFinalizeMs, chunkByteCount = defaultChunkByteCount, logger = Logger.default, chunkingMode = 'auto', dataItemByteCount, }) {
+    constructor({ http, token, maxChunkConcurrency = defaultMaxChunkConcurrency, maxFinalizeMs, chunkByteCount = defaultChunkByteCount, logger = Logger.default, chunkingMode = 'auto', dataItemByteCount, x402, x402RefundIdentity, }) {
         this.assertChunkParams({
             chunkByteCount,
             chunkingMode,
@@ -54,6 +54,9 @@ export class ChunkedUploader {
             dataItemByteCount,
         });
         this.maxBacklogQueue = this.maxChunkConcurrency * backlogQueueFactor;
+        this.x402 = x402;
+        this.x402RefundIdentity = x402RefundIdentity;
+        this.dataItemByteCount = dataItemByteCount;
     }
     shouldChunkUpload({ chunkByteCount, chunkingMode, dataItemByteCount, }) {
         if (chunkingMode === 'disabled') {
@@ -92,7 +95,54 @@ export class ChunkedUploader {
     /**
      * Initialize or resume an upload session, returning the upload ID.
      */
+    /**
+     * Open a multipart upload paid for with x402.
+     *
+     * The bundler settles the payment at CREATE, before accepting a single chunk
+     * — so an unpaid upload never consumes storage. That is why the size is
+     * declared here and the money moves here, not at finalize.
+     *
+     * The 402 handshake is delegated to `wrapFetchWithPayment`, the same
+     * mechanism the single-shot x402 POST already uses, so the signer and the
+     * spend cap behave identically on both paths.
+     */
+    async initPaidUpload(x402) {
+        if (this.paidUploadId !== undefined) {
+            this.logger.debug('Resuming the already-paid chunked upload', {
+                uploadId: this.paidUploadId,
+            });
+            return this.paidUploadId;
+        }
+        if (this.x402RefundIdentity === undefined) {
+            throw new Error('An x402-paid chunked upload needs a refund identity — it is the Turbo wallet credited if the upload delivers fewer bytes than were paid for.');
+        }
+        const { address, signatureType } = this.x402RefundIdentity;
+        const endpoint = `/chunks/${this.token}/-1/-1?chunkSize=${this.chunkByteCount}` +
+            `&totalBytes=${this.dataItemByteCount}` +
+            `&address=${encodeURIComponent(address)}` +
+            `&signatureType=${signatureType}`;
+        this.logger.debug('Opening an x402-paid chunked upload', {
+            totalBytes: this.dataItemByteCount,
+        });
+        const res = await this.http.get({
+            endpoint: endpoint,
+            headers: chunkingHeader,
+            x402Options: x402,
+        });
+        if (res.chunkSize !== undefined && res.chunkSize !== this.chunkByteCount) {
+            this.logger.warn('Chunk size mismatch! Overriding with server value.', {
+                clientExpected: this.chunkByteCount,
+                serverReturned: res.chunkSize,
+            });
+            this.chunkByteCount = res.chunkSize;
+        }
+        this.paidUploadId = res.id;
+        return res.id;
+    }
     async initUpload() {
+        if (this.x402 !== undefined) {
+            return this.initPaidUpload(this.x402);
+        }
         const res = await this.http.get({
             endpoint: `/chunks/${this.token}/-1/-1?chunkSize=${this.chunkByteCount}`,
             headers: chunkingHeader,

package/lib/esm/common/http.js

@@ -48,7 +48,18 @@ export class TurboHTTPService {
         this.baseURL = url;
         this.retryConfig = retryConfig;
     }
-    async get({ endpoint, signal, allowedStatuses = [200, 202], headers, }) {
+    async get({ endpoint, signal, allowedStatuses = [200, 202], headers, x402Options, }) {
+        if (x402Options !== undefined) {
+            const maxMUSDCAmount = x402Options.maxMUSDCAmount !== undefined
+                ? BigInt(x402Options.maxMUSDCAmount.toString())
+                : undefined;
+            const fetchWithPay = wrapFetchWithPayment(fetch, x402Options.signer, maxMUSDCAmount);
+            return this.tryRequest(async () => fetchWithPay(this.baseURL + endpoint, {
+                method: 'GET',
+                headers: { ...defaultHeaders, ...headers },
+                signal,
+            }), allowedStatuses);
+        }
         return this.withRetry(() => fetch(this.baseURL + endpoint, {
             method: 'GET',
             headers: { ...defaultHeaders, ...headers },

package/lib/esm/common/payment.js

@@ -18,7 +18,7 @@ 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 { arNSOwnerProofHeaders, buildArNSCustodyMessage, } from './arnsActions.js';
+import { arNSKeywordsField, arNSMetadataField, arNSOwnerProofHeaders, buildArNSCustodyMessage, } from './arnsActions.js';
 import { defaultRetryConfig } from './http.js';
 import { TurboHTTPService } from './http.js';
 import { Logger } from './logger.js';
@@ -659,7 +659,7 @@ export class TurboAuthenticatedPaymentService extends TurboUnauthenticatedPaymen
     /**
      * Point a name (or undername) at an Arweave transaction.
      *
-     * Free — Turbo sponsors the Solana fee. Completes in one call while Turbo is
+     * 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.
@@ -683,16 +683,66 @@ export class TurboAuthenticatedPaymentService extends TurboUnauthenticatedPaymen
             String(ttlSeconds),
         ]));
     }
-    /** Remove a record (an undername). Free; same two-shape rules as setArNSRecord. */
+    /** 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. Free to the customer — Turbo funds the ACL page growth.
+     * 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', {
@@ -705,7 +755,8 @@ export class TurboAuthenticatedPaymentService extends TurboUnauthenticatedPaymen
      * 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.
+     * 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.
      */

package/lib/esm/common/turbo.js

@@ -266,15 +266,31 @@ export class TurboAuthenticatedClient extends TurboUnauthenticatedClient {
     removeArNSRecord(params) {
         return this.paymentService.removeArNSRecord(params);
     }
-    /** Grant controller rights — omit `target` for Turbo itself. Free. */
+    /** Grant controller rights — omit `target` for Turbo itself. Costs credits. */
     addArNSController(params) {
         return this.paymentService.addArNSController(params);
     }
-    /** Revoke controller rights. Always available, always free. */
+    /** Revoke controller rights. Always available; costs credits, never SOL. */
     removeArNSController(params) {
         return this.paymentService.removeArNSController(params);
     }
-    /** Hand the ANT to a new owner. Irreversible. Free. */
+    /**
+     * Edit a RECORD's metadata (display name, logo, description, keywords).
+     * Free; handles both shapes. Fields are tri-state — omit to leave unchanged,
+     * pass `null` to clear.
+     */
+    setArNSRecordMetadata(params) {
+        return this.paymentService.setArNSRecordMetadata(params);
+    }
+    /** Clear a record's metadata. Costs credits, never SOL; handles both shapes. */
+    removeArNSRecordMetadata(params) {
+        return this.paymentService.removeArNSRecordMetadata(params);
+    }
+    /** Hand ONE record over — not the whole ANT. Costs credits, never SOL. */
+    transferArNSRecord(params) {
+        return this.paymentService.transferArNSRecord(params);
+    }
+    /** Hand the ANT to a new owner. Irreversible. Costs credits, never SOL. */
     transferArNSAnt(params) {
         return this.paymentService.transferArNSAnt(params);
     }