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

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

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.paymentHistory = paymentHistory;
+const utils_js_1 = require("../utils.js");
+async function paymentHistory(options) {
+    // Signature-required and self-scoped: a wallet is mandatory (there is no
+    // --address form), and the service returns only this signer's own top-ups.
+    const turbo = await (0, utils_js_1.turboFromOptions)(options);
+    const limit = options.limit !== undefined ? +options.limit : undefined;
+    if (limit !== undefined &&
+        (!Number.isInteger(limit) || limit < 1 || limit > 100)) {
+        throw new Error('--limit must be an integer between 1 and 100');
+    }
+    const { payments, hasMore, cursor } = await turbo.getPaymentHistory({
+        limit,
+        cursor: options.cursor,
+    });
+    // stdout carries only the JSON page and the next-page hint goes to stderr, so
+    // `... | jq` works at the default log level. (--debug intentionally routes SDK
+    // logs to stdout and will interleave — expected when you ask for debug output.)
+    console.log(JSON.stringify({ payments, hasMore, cursor }, null, 2));
+    if (hasMore) {
+        console.error(`\nMore results available — fetch the next page with --cursor ${cursor}`);
+    }
+}

package/lib/cjs/cli/options.js

@@ -15,7 +15,7 @@
  * limitations under the License.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.listSharesOptions = exports.revokeCreditsOptions = exports.shareCreditsOptions = exports.uploadFileOptions = exports.uploadFolderOptions = exports.uploadOptions = exports.globalOptions = exports.walletOptions = exports.optionMap = void 0;
+exports.arnsActionPriceOptions = exports.removeArNSRecordMetadataOptions = exports.setArNSRecordMetadataOptions = exports.transferArNSRecordOptions = exports.removeArNSControllerOptions = exports.addArNSControllerOptions = exports.removeArNSRecordOptions = exports.setArNSRecordOptions = exports.transferArNSAntOptions = exports.arnsActionStatusOptions = exports.arnsPurchaseStatusOptions = exports.upgradeArNSNameOptions = exports.increaseArNSUndernamesOptions = exports.extendArNSLeaseOptions = exports.buyArNSNameOptions = exports.arnsFiatQuoteOptions = exports.arnsPriceOptions = exports.listSharesOptions = exports.revokeCreditsOptions = exports.shareCreditsOptions = exports.uploadFileOptions = exports.uploadFolderOptions = exports.uploadOptions = exports.globalOptions = exports.walletOptions = exports.optionMap = void 0;
 exports.optionMap = {
     token: {
         alias: '-t, --token <type>',
@@ -189,6 +189,102 @@ exports.optionMap = {
         alias: '--max-crypto-top-up-value <maxCryptoTopUpValue>',
         description: 'Maximum crypto top-up value to use for the upload. Defaults to no limit.',
     },
+    // ---- ArNS (paid with Turbo Credits) ----
+    arnsName: {
+        alias: '--name <name>',
+        description: 'ArNS name to price, buy, or manage',
+    },
+    arnsType: {
+        alias: '--type <type>',
+        description: "ArNS purchase type for Buy-Name: 'lease' or 'permabuy'",
+    },
+    arnsYears: {
+        alias: '--years <years>',
+        description: 'Lease duration in years (Buy-Name lease / Extend-Lease)',
+    },
+    arnsIncreaseQty: {
+        alias: '--increase-qty <qty>',
+        description: 'Number of additional undernames (Increase-Undername-Limit)',
+    },
+    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>',
+        description: 'ArNS purchase nonce to look up the status for',
+    },
+    arnsAntId: {
+        alias: '--ant-id <antId>',
+        description: 'ANT (Metaplex Core asset) ID to transfer or manage',
+    },
+    arnsTarget: {
+        alias: '--target <address>',
+        description: 'Target Solana pubkey to transfer the ANT to',
+    },
+    arnsUndername: {
+        alias: '--undername <undername>',
+        description: "ArNS undername record to set or remove (defaults to '@')",
+    },
+    arnsTransactionId: {
+        alias: '--transaction-id <transactionId>',
+        description: 'Arweave transaction ID the ArNS record resolves to',
+    },
+    arnsTtlSeconds: {
+        alias: '--ttl-seconds <ttlSeconds>',
+        description: 'TTL in seconds for the ArNS record',
+    },
+    arnsDisplayName: {
+        alias: '--display-name <displayName>',
+        description: 'Display name for the record (Set-Record-Metadata)',
+    },
+    arnsClearDisplayName: {
+        alias: '--clear-display-name',
+        description: 'Clear the record display name (Set-Record-Metadata)',
+        default: false,
+    },
+    arnsRecordLogo: {
+        alias: '--record-logo <transactionId>',
+        description: 'Arweave transaction ID for the record logo (Set-Record-Metadata)',
+    },
+    arnsClearRecordLogo: {
+        alias: '--clear-record-logo',
+        description: 'Clear the record logo (Set-Record-Metadata)',
+        default: false,
+    },
+    arnsRecordDescription: {
+        alias: '--record-description <description>',
+        description: 'Description for the record (Set-Record-Metadata)',
+    },
+    arnsClearRecordDescription: {
+        alias: '--clear-record-description',
+        description: 'Clear the record description (Set-Record-Metadata)',
+        default: false,
+    },
+    arnsRecordKeywords: {
+        alias: '--record-keywords <keywords...>',
+        description: 'Keywords for the record (Set-Record-Metadata)',
+        type: 'array',
+    },
+    arnsClearRecordKeywords: {
+        alias: '--clear-record-keywords',
+        description: 'Clear the record keywords (Set-Record-Metadata)',
+        default: false,
+    },
+    arnsAction: {
+        alias: '--action <action>',
+        description: 'ArNS action to price: set-record, remove-record, set-record-metadata, ' +
+            'remove-record-metadata, transfer-record, add-controller, remove-controller, or transfer',
+    },
+    // ---- Payment history ----
+    limit: {
+        alias: '--limit <limit>',
+        description: 'Max number of payment-history rows to return (1-100, default 50)',
+    },
+    cursor: {
+        alias: '--cursor <cursor>',
+        description: 'Opaque pagination cursor from a prior payment-history response',
+    },
 };
 exports.walletOptions = [
     exports.optionMap.walletFile,
@@ -242,3 +338,108 @@ exports.shareCreditsOptions = [
 ];
 exports.revokeCreditsOptions = [...exports.walletOptions, exports.optionMap.address];
 exports.listSharesOptions = exports.revokeCreditsOptions;
+// ---- ArNS command option sets (token + --payment-url come from globalOptions) ----
+exports.arnsPriceOptions = [
+    exports.optionMap.arnsName,
+    exports.optionMap.arnsType,
+    exports.optionMap.arnsYears,
+    exports.optionMap.arnsIncreaseQty,
+];
+exports.arnsFiatQuoteOptions = [
+    exports.optionMap.arnsName,
+    exports.optionMap.arnsType,
+    exports.optionMap.arnsYears,
+    exports.optionMap.arnsIncreaseQty,
+    exports.optionMap.address,
+    exports.optionMap.currency,
+    {
+        alias: '--method <method>',
+        description: 'Stripe integration mode: payment-intent (default) or checkout-session',
+    },
+    {
+        alias: '--promo-code <promoCode...>',
+        description: 'Promo code(s) to apply to the fiat price',
+    },
+];
+exports.buyArNSNameOptions = [
+    ...exports.walletOptions,
+    exports.optionMap.arnsName,
+    exports.optionMap.arnsType,
+    exports.optionMap.arnsYears,
+    exports.optionMap.arnsOwnerKey,
+    exports.optionMap.paidBy,
+];
+exports.extendArNSLeaseOptions = [
+    ...exports.walletOptions,
+    exports.optionMap.arnsName,
+    exports.optionMap.arnsYears,
+    exports.optionMap.paidBy,
+];
+exports.increaseArNSUndernamesOptions = [
+    ...exports.walletOptions,
+    exports.optionMap.arnsName,
+    exports.optionMap.arnsIncreaseQty,
+    exports.optionMap.paidBy,
+];
+exports.upgradeArNSNameOptions = [
+    ...exports.walletOptions,
+    exports.optionMap.arnsName,
+    exports.optionMap.paidBy,
+];
+exports.arnsPurchaseStatusOptions = [exports.optionMap.arnsNonce];
+exports.arnsActionStatusOptions = [...exports.walletOptions, 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,
+    exports.optionMap.arnsTtlSeconds,
+];
+exports.removeArNSRecordOptions = [
+    ...exports.walletOptions,
+    exports.optionMap.arnsOwnerKey,
+    exports.optionMap.arnsAntId,
+    exports.optionMap.arnsUndername,
+];
+exports.addArNSControllerOptions = [
+    ...exports.walletOptions,
+    exports.optionMap.arnsOwnerKey,
+    exports.optionMap.arnsAntId,
+    exports.optionMap.arnsTarget,
+];
+exports.removeArNSControllerOptions = exports.addArNSControllerOptions;
+exports.transferArNSRecordOptions = [
+    ...exports.walletOptions,
+    exports.optionMap.arnsOwnerKey,
+    exports.optionMap.arnsAntId,
+    exports.optionMap.arnsUndername,
+    exports.optionMap.arnsTarget,
+];
+exports.setArNSRecordMetadataOptions = [
+    ...exports.walletOptions,
+    exports.optionMap.arnsOwnerKey,
+    exports.optionMap.arnsAntId,
+    exports.optionMap.arnsUndername,
+    exports.optionMap.arnsDisplayName,
+    exports.optionMap.arnsClearDisplayName,
+    exports.optionMap.arnsRecordLogo,
+    exports.optionMap.arnsClearRecordLogo,
+    exports.optionMap.arnsRecordDescription,
+    exports.optionMap.arnsClearRecordDescription,
+    exports.optionMap.arnsRecordKeywords,
+    exports.optionMap.arnsClearRecordKeywords,
+];
+exports.removeArNSRecordMetadataOptions = [
+    ...exports.walletOptions,
+    exports.optionMap.arnsOwnerKey,
+    exports.optionMap.arnsAntId,
+    exports.optionMap.arnsUndername,
+];
+exports.arnsActionPriceOptions = [exports.optionMap.arnsAction];

package/lib/cjs/common/arnsActions.js

@@ -0,0 +1,125 @@
+"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.arNSMetadataField = arNSMetadataField;
+exports.arNSKeywordsField = arNSKeywordsField;
+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');
+}
+/**
+ * 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;
+/**
+ * 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/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,