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

package/lib/cjs/common/turbo.js

@@ -69,6 +69,19 @@ class TurboUnauthenticatedClient {
     getArNSPurchaseStatus(p) {
         return this.paymentService.getArNSPurchaseStatus(p);
     }
+    /**
+     * Returns the ArNS names a wallet owns or controls via Turbo's custodial
+     * ArNS-with-credits feature. `custodial: true` on a returned name means
+     * Turbo still holds/manages its ANT (transfer/manage routes apply);
+     * `custodial: false` means self-custody (or an already-completed exit) and
+     * is informational only.
+     *
+     * To read a name's current records or lease/expiration state, use
+     * `@ar.io/sdk` directly against the returned `antId`.
+     */
+    getArNSNames(address) {
+        return this.paymentService.getArNSNames(address);
+    }
     /**
      * Quote a fiat (Stripe) ArNS purchase — buy a name with a credit card in one
      * step, no Turbo Credits top-up in between. Complete the returned
@@ -201,16 +214,22 @@ class TurboAuthenticatedClient extends TurboUnauthenticatedClient {
     getPaymentHistory(params) {
         return this.paymentService.getPaymentHistory(params);
     }
-    /**
-     * Buys, extends, or upgrades an ArNS name, paying with the signer's Turbo
-     * credit balance. Poll {@link getArNSPurchaseStatus} with the returned nonce.
-     */
-    purchaseArNSName(params) {
-        return this.paymentService.purchaseArNSName(params);
+    // ===== ArNS actions (sponsored) =====
+    //
+    // Thin delegations. The two-shape branch and the owner-proof construction
+    // live in the payment service; see its comments for why callers must branch
+    // on `status` rather than on which action they asked for.
+    /** Create an action. Debits credits HERE — capture the nonce before signing. */
+    createArNSAction(action, params, ownerProof) {
+        return this.paymentService.createArNSAction(action, params, ownerProof);
     }
-    /** Buys a new ArNS name (lease or permabuy). */
-    buyArNSName(params) {
-        return this.paymentService.buyArNSName(params);
+    /** Submit the owner-signed transaction (FULL serialized tx, base64). */
+    signArNSAction(nonce, signedTransaction) {
+        return this.paymentService.signArNSAction(nonce, signedTransaction);
+    }
+    /** Status by nonce — open, needs no signature. Use it to resume. */
+    getArNSActionStatus(nonce) {
+        return this.paymentService.getArNSActionStatus(nonce);
     }
     /**
      * Quote a fiat (Stripe) ArNS purchase for this signer's wallet — a credit-card
@@ -224,27 +243,53 @@ class TurboAuthenticatedClient extends TurboUnauthenticatedClient {
     getArNSFiatPurchaseQuote(params) {
         return this.paymentService.getArNSFiatPurchaseQuote(params);
     }
-    /** Extends the lease on an existing ArNS name. */
+    /**
+     * Buy a name. The ANT is minted straight to `owner`; Turbo never holds it.
+     * The only action that always needs the owner's signature — once, ever.
+     */
+    buyArNSName(params) {
+        return this.paymentService.buyArNSName(params);
+    }
+    /** Extend a lease. No owner signature needed. */
     extendArNSLease(params) {
         return this.paymentService.extendArNSLease(params);
     }
-    /** Increases the undername limit on an existing ArNS name. */
+    /** Raise the undername limit. No owner signature needed. */
     increaseArNSUndernameLimit(params) {
         return this.paymentService.increaseArNSUndernameLimit(params);
     }
-    /** Upgrades an ArNS lease to a permabuy. */
+    /** Upgrade a lease to a permanent name. No owner signature needed. */
     upgradeArNSName(params) {
         return this.paymentService.upgradeArNSName(params);
     }
-    transferArNSAnt(params) {
-        return this.paymentService.transferArNSAnt(params);
-    }
+    /** Point a name (or undername) at data. Free; handles both shapes. */
     setArNSRecord(params) {
         return this.paymentService.setArNSRecord(params);
     }
+    /** Remove a record. Free; handles both shapes. */
     removeArNSRecord(params) {
         return this.paymentService.removeArNSRecord(params);
     }
+    /** Grant controller rights — omit `target` for Turbo itself. Free. */
+    addArNSController(params) {
+        return this.paymentService.addArNSController(params);
+    }
+    /** Revoke controller rights. Always available, always free. */
+    removeArNSController(params) {
+        return this.paymentService.removeArNSController(params);
+    }
+    /** Hand the ANT to a new owner. Irreversible. Free. */
+    transferArNSAnt(params) {
+        return this.paymentService.transferArNSAnt(params);
+    }
+    /**
+     * Returns the ArNS names owned or controlled by the connected signer's
+     * wallet (or the given `userAddress`) via Turbo's custodial
+     * ArNS-with-credits feature.
+     */
+    getArNSNames(userAddress) {
+        return this.paymentService.getArNSNames(userAddress);
+    }
     /**
      * Returns a list of all credit share approvals for the user.
      */

package/lib/cjs/types.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.arNSFiatPurchaseMethods = exports.arNSPurchaseIntents = exports.validChunkingModes = exports.isJWK = exports.isWebUploadFolderParams = exports.isNodeUploadFolderParams = exports.multipartFinalizedStatus = exports.multipartFailedStatus = exports.multipartPendingStatus = exports.X402Funding = exports.OnDemandFunding = exports.ExistingBalanceFunding = exports.supportedEvmSignerTokens = exports.tokenTypes = exports.fiatCurrencyTypes = void 0;
+exports.arNSFiatPurchaseMethods = exports.arNSActions = exports.arNSPurchaseIntents = exports.validChunkingModes = exports.isJWK = exports.isWebUploadFolderParams = exports.isNodeUploadFolderParams = exports.multipartFinalizedStatus = exports.multipartFailedStatus = exports.multipartPendingStatus = exports.X402Funding = exports.OnDemandFunding = exports.ExistingBalanceFunding = exports.supportedEvmSignerTokens = exports.tokenTypes = exports.fiatCurrencyTypes = void 0;
 exports.isCurrency = isCurrency;
 exports.isKyvePrivateKey = isKyvePrivateKey;
 exports.isEthPrivateKey = isEthPrivateKey;
@@ -113,6 +113,25 @@ exports.arNSPurchaseIntents = [
     'Increase-Undername-Limit',
     'Upgrade-Name',
 ];
+// ===== ArNS actions (sponsored — the current bundler surface) =====
+/**
+ * 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.
+ */
+exports.arNSActions = [
+    'buy-name',
+    'extend-lease',
+    'upgrade-name',
+    'increase-undername-limit',
+    'set-record',
+    'remove-record',
+    'add-controller',
+    'remove-controller',
+    'transfer',
+];
 // ===== ArNS purchases paid with fiat (Stripe) — no Turbo Credits in between ====
 /**
  * Stripe integration mode for a fiat ArNS purchase quote.

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

@@ -14,10 +14,26 @@
  * limitations under the License.
  */
 import { BigNumber } from 'bignumber.js';
+import { solanaOwnerSigner } from '../../common/arnsActions.js';
 import { TurboFactory } from '../../node/factory.js';
 import { FiatPaymentsDisabledError, InsufficientCreditsError, } from '../../utils/errors.js';
 import { wincPerCredit } from '../constants.js';
 import { configFromOptions, turboFromOptions } from '../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 solanaOwnerSigner(options.ownerKey);
+}
 export function requiredNameFromOptions(options) {
     if (options.name === undefined || options.name.length === 0) {
         throw new Error('Must provide an ArNS --name');
@@ -111,10 +127,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}`);
 }
@@ -132,6 +150,14 @@ export async function arnsPrice(options, turbo) {
 }
 export 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.');
@@ -173,20 +199,19 @@ export async function buyArNSName(options, turbo) {
     const name = requiredNameFromOptions(options);
     const type = typeFromOptions(options.type);
     const paidBy = paidByFromArNSOptions(options.paidBy);
-    // `--process-id` is OPTIONAL: omit it to have Turbo custodially provision the
-    // ANT (Turbo spawns + owns it — Model A); supply it to point the name at a
-    // user-owned ANT (Model B). When omitted, no `processId` is sent.
-    const processId = options.processId;
+    // 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 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);
 }
 export async function extendArNSLease(options, turbo) {
@@ -235,6 +260,7 @@ export async function transferArNSAnt(options, turbo) {
     const client = turbo ?? (await 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));
@@ -250,6 +276,7 @@ export async function setArNSRecord(options, turbo) {
     const client = turbo ?? (await turboFromOptions(options));
     const result = await client.setArNSRecord({
         antId: options.antId,
+        owner: ownerFromOptions(options),
         undername: options.undername ?? '@',
         transactionId: options.transactionId,
         ttlSeconds,
@@ -266,6 +293,7 @@ export async function removeArNSRecord(options, turbo) {
     const client = turbo ?? (await 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/esm/cli/options.js

@@ -203,9 +203,9 @@ export const 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>',
@@ -299,14 +299,12 @@ export const arnsPriceOptions = [
     optionMap.arnsType,
     optionMap.arnsYears,
     optionMap.arnsIncreaseQty,
-    optionMap.arnsProcessId,
 ];
 export const arnsFiatQuoteOptions = [
     optionMap.arnsName,
     optionMap.arnsType,
     optionMap.arnsYears,
     optionMap.arnsIncreaseQty,
-    optionMap.arnsProcessId,
     optionMap.address,
     optionMap.currency,
     {
@@ -323,7 +321,7 @@ export const buyArNSNameOptions = [
     optionMap.arnsName,
     optionMap.arnsType,
     optionMap.arnsYears,
-    optionMap.arnsProcessId,
+    optionMap.arnsOwnerKey,
     optionMap.paidBy,
 ];
 export const extendArNSLeaseOptions = [
@@ -346,11 +344,13 @@ export const upgradeArNSNameOptions = [
 export const arnsPurchaseStatusOptions = [optionMap.arnsNonce];
 export const transferArNSAntOptions = [
     ...walletOptions,
+    optionMap.arnsOwnerKey,
     optionMap.arnsAntId,
     optionMap.arnsTarget,
 ];
 export const setArNSRecordOptions = [
     ...walletOptions,
+    optionMap.arnsOwnerKey,
     optionMap.arnsAntId,
     optionMap.arnsUndername,
     optionMap.arnsTransactionId,
@@ -358,6 +358,7 @@ export const setArNSRecordOptions = [
 ];
 export const removeArNSRecordOptions = [
     ...walletOptions,
+    optionMap.arnsOwnerKey,
     optionMap.arnsAntId,
     optionMap.arnsUndername,
 ];

package/lib/esm/common/arnsActions.js

@@ -0,0 +1,93 @@
+/**
+ * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Keypair, VersionedTransaction } from '@solana/web3.js';
+import bs58 from 'bs58';
+import nacl from 'tweetnacl';
+import { toB64Url } from '../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).
+ */
+export 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.
+ */
+export 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': toB64Url(Buffer.from(bs58.decode(address))),
+        'x-owner-nonce': nonce,
+        'x-owner-signature': 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.
+ */
+export function solanaOwnerSigner(secretKey) {
+    const keypair = Keypair.fromSecretKey(typeof secretKey === 'string' ? bs58.decode(secretKey) : secretKey);
+    return {
+        getAddress: () => keypair.publicKey.toBase58(),
+        signTransaction: async (transactionBase64) => {
+            const tx = 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) => nacl.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.
+ */
+export function emptySignatureSlots(transactionBase64) {
+    const tx = VersionedTransaction.deserialize(Buffer.from(transactionBase64, 'base64'));
+    return tx.signatures.filter((sig) => sig.every((byte) => byte === 0)).length;
+}