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

package/lib/cjs/common/chunked.js

@@ -41,13 +41,14 @@ 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, x402, x402RefundIdentity, }) {
+    constructor({ http, token, maxChunkConcurrency = exports.defaultMaxChunkConcurrency, maxFinalizeMs, chunkByteCount = exports.defaultChunkByteCount, logger = logger_js_1.Logger.default, chunkingMode = 'auto', dataItemByteCount, x402, x402RefundIdentity, paidUploadId, }) {
         this.assertChunkParams({
             chunkByteCount,
             chunkingMode,
             maxChunkConcurrency,
             maxFinalizeMs,
         });
+        this.paidUploadId = paidUploadId;
         this.chunkByteCount = chunkByteCount;
         this.maxChunkConcurrency = maxChunkConcurrency;
         this.maxFinalizeMs = maxFinalizeMs;
@@ -145,6 +146,14 @@ class ChunkedUploader {
         this.paidUploadId = res.id;
         return res.id;
     }
+    /**
+     * The paid upload id, once one has been bought. `uploadFile` reads this after
+     * a failed attempt so the next attempt resumes the upload already paid for
+     * rather than buying a second one.
+     */
+    get currentPaidUploadId() {
+        return this.paidUploadId;
+    }
     async initUpload() {
         if (this.x402 !== undefined) {
             return this.initPaidUpload(this.x402);

package/lib/cjs/common/http.js

@@ -52,8 +52,21 @@ class TurboHTTPService {
         this.baseURL = url;
         this.retryConfig = retryConfig;
     }
+    /**
+     * Refuse to pay over cleartext.
+     *
+     * An x402 payment authorization is a bearer credential: anyone who observes
+     * it can submit it. Sending one over `http:` hands it to the network, so a
+     * misconfigured service URL must fail loudly rather than quietly leak.
+     */
+    assertSecureForPayment() {
+        if (!this.baseURL.startsWith('https:') && !isLoopback(this.baseURL)) {
+            throw new Error(`Refusing to send an x402 payment over a non-HTTPS URL: ${this.baseURL}`);
+        }
+    }
     async get({ endpoint, signal, allowedStatuses = [200, 202], headers, x402Options, }) {
         if (x402Options !== undefined) {
+            this.assertSecureForPayment();
             const maxMUSDCAmount = x402Options.maxMUSDCAmount !== undefined
                 ? BigInt(x402Options.maxMUSDCAmount.toString())
                 : undefined;
@@ -162,6 +175,7 @@ class TurboHTTPService {
             endpoint,
             x402Options,
         });
+        this.assertSecureForPayment();
         const { body, duplex } = await toFetchBody(data);
         return this.tryRequest(async () => {
             const maxMUSDCAmount = x402Options.maxMUSDCAmount !== undefined
@@ -213,3 +227,13 @@ function isFirefoxOrSafari() {
             !ua.includes('Chrome') &&
             !ua.includes('Chromium')));
 }
+/** Loopback is exempt: local development never leaves the machine. */
+function isLoopback(url) {
+    try {
+        const { hostname } = new URL(url);
+        return (hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1');
+    }
+    catch {
+        return false;
+    }
+}

package/lib/cjs/common/payment.js

@@ -657,13 +657,20 @@ class TurboAuthenticatedPaymentService extends TurboUnauthenticatedPaymentServic
      * The owner needs a Solana key to sign with, NOT a funded one — Turbo pays
      * every lamport of fee and rent.
      */
-    async buyArNSName({ name, owner, type = 'lease', years, paidBy, onNonce, }) {
+    async buyArNSName({ name, owner, type = 'lease', years, paidBy, onNonce, antState, }) {
         return this.completeArNSAction('buy-name', {
             name,
             ownerAddress: await owner.getAddress(),
             type,
             ...(years !== undefined ? { years } : {}),
             ...(paidBy !== undefined ? { paidBy } : {}),
+            /*
+              Spread conditionally, like `paidBy` — an `antState: undefined` key
+              would serialize into the body and is not the same request as omitting
+              it. Sent whole in the BODY rather than the query string: it is an
+              object, and `createArNSAction` already posts every param as JSON.
+            */
+            ...(antState !== undefined ? { antState } : {}),
         }, owner, { onNonce });
     }
     /** Extend a lease. Permissionless on chain — no owner signature needed. */

package/lib/cjs/common/turbo.js

@@ -193,6 +193,20 @@ class TurboUnauthenticatedClient {
             maxMUSDCAmount,
         });
     }
+    /**
+     * Price a signed data item for an x402 upload without sending it. See
+     * `TurboUnauthenticatedUploadService.getX402PriceForDataItem`.
+     */
+    getX402PriceForDataItem(p) {
+        return this.uploadService.getX402PriceForDataItem(p);
+    }
+    /**
+     * Price raw data for an x402 upload, including the data-item wrapping
+     * overhead. See `TurboUnauthenticatedUploadService.getX402PriceForRawData`.
+     */
+    getX402PriceForRawData(p) {
+        return this.uploadService.getX402PriceForRawData(p);
+    }
 }
 exports.TurboUnauthenticatedClient = TurboUnauthenticatedClient;
 class TurboAuthenticatedClient extends TurboUnauthenticatedClient {
@@ -381,5 +395,19 @@ class TurboAuthenticatedClient extends TurboUnauthenticatedClient {
             maxMUSDCAmount,
         });
     }
+    /**
+     * Price a signed data item for an x402 upload without sending it. See
+     * `TurboUnauthenticatedUploadService.getX402PriceForDataItem`.
+     */
+    getX402PriceForDataItem(p) {
+        return this.uploadService.getX402PriceForDataItem(p);
+    }
+    /**
+     * Price raw data for an x402 upload, including the data-item wrapping
+     * overhead. See `TurboUnauthenticatedUploadService.getX402PriceForRawData`.
+     */
+    getX402PriceForRawData(p) {
+        return this.uploadService.getX402PriceForRawData(p);
+    }
 }
 exports.TurboAuthenticatedClient = TurboAuthenticatedClient;

package/lib/cjs/common/upload.js

@@ -17,6 +17,7 @@ exports.TurboAuthenticatedBaseUploadService = exports.TurboUnauthenticatedUpload
  * limitations under the License.
  */
 const bignumber_js_1 = require("bignumber.js");
+const node_stream_1 = require("node:stream");
 const plimit_lit_1 = require("plimit-lit");
 const types_js_1 = require("../types.js");
 const common_js_1 = require("../utils/common.js");
@@ -80,6 +81,29 @@ class TurboUnauthenticatedUploadService {
                 headers['x-paid-by'] = paidBy;
             }
         }
+        if (x402Options !== undefined) {
+            /*
+              x402 needs a body fetch can measure, and one it can send twice.
+      
+              `content-length` is a forbidden header, so setting it above does
+              nothing: a streamed body goes out chunked with no length. The service
+              prices from that header, so without it there is no 402 challenge — and
+              the protocol's paid retry has a spent stream to replay, which fails
+              outright. Buffering fixes both: the length is declared honestly and the
+              body can be re-sent.
+      
+              Bounded by the chunking decision above — anything over two chunks took
+              the chunked path, which pays at create and never reaches here.
+            */
+            const body = await streamToBuffer(streamWithUploadEvents, dataItemSize, resume, signal);
+            return this.httpService.post({
+                endpoint: `/tx/${this.token}`,
+                signal,
+                data: body,
+                headers,
+                x402Options,
+            });
+        }
         // setup the post request using the stream with upload events
         const postPromise = this.httpService.post({
             endpoint: `/tx/${this.token}`,
@@ -92,6 +116,46 @@ class TurboUnauthenticatedUploadService {
         resume();
         return postPromise;
     }
+    /**
+     * Price a SIGNED data item for an x402 upload, without sending it.
+     *
+     * The only other way to learn an x402 price is to POST the payload and read
+     * the 402 challenge, which means transmitting it to find out what it costs.
+     *
+     * `byteCount` is the size of the signed data item — what
+     * `dataItemSizeFactory()` returns — not the payload inside it. Use
+     * `getX402PriceForRawData` when the service does the wrapping.
+     *
+     * `network` names the x402 network, not the SDK token: the route builds its
+     * token as `usdc-{network}`. `base-usdc` is accepted on mainnet only because
+     * the network there is literally `base`, so a testnet caller must pass
+     * `base-sepolia` explicitly.
+     */
+    async getX402PriceForDataItem({ byteCount, network = 'base', }) {
+        return this.httpService.get({
+            endpoint: `/price/x402/data-item/usdc-${network}/${byteCount}`,
+        });
+    }
+    /**
+     * Price RAW data for an x402 upload, where the service wraps it into a data
+     * item itself.
+     *
+     * Also reports the wrapping overhead — a data item is larger than its
+     * payload by its header, signature and tags — which the caller has no way to
+     * compute. `tagCount` and `contentType` feed that estimate, so pass what the
+     * upload will actually carry or the quote will read low.
+     */
+    async getX402PriceForRawData({ byteCount, network = 'base', tagCount, contentType, }) {
+        const query = new URLSearchParams();
+        if (tagCount !== undefined)
+            query.set('tags', `${tagCount}`);
+        if (contentType !== undefined)
+            query.set('contentType', contentType);
+        const qs = query.toString();
+        return this.httpService.get({
+            endpoint: `/price/x402/data/usdc-${network}/${byteCount}${qs ? `?${qs}` : ''}`,
+        });
+    }
     async uploadRawX402Data({ data, tags, signal, maxMUSDCAmount, signer, }) {
         if (!this.x402EnabledTokens.includes(this.token)) {
             throw new Error('x402 uploads are not supported for token: ' + this.token);
@@ -226,8 +290,30 @@ class TurboAuthenticatedBaseUploadService extends TurboUnauthenticatedUploadServ
             !this.x402EnabledTokens.includes(this.token)) {
             throw new Error('x402 uploads are not supported for token: ' + this.token);
         }
+        /*
+          Buffering the single request is only safe because anything larger chunks.
+          `chunkingMode: 'disabled'` removes that guarantee, so an arbitrarily large
+          item would be pulled into memory — and the service caps single-request
+          items anyway, so it would be refused after the fact. Check before signing:
+          signing a large item only to reject it wastes the expensive part.
+        */
+        if (fundingMode instanceof types_js_1.X402Funding &&
+            params.chunkingMode === 'disabled' &&
+            fileSizeFactory() + x402SignedItemOverheadByteCount >
+                maxX402SingleRequestByteCount) {
+            throw new Error(`An x402 upload of ${fileSizeFactory()} bytes must be chunked: the ` +
+                `single-request path buffers the SIGNED item in memory and is ` +
+                `limited to ${maxX402SingleRequestByteCount} bytes, of which ` +
+                `signing claims about ${x402SignedItemOverheadByteCount}. Remove ` +
+                `chunkingMode: 'disabled' to upload this item.`);
+        }
         this.logger.debug('Starting file upload', { params });
         let retries = 0;
+        // Carried ACROSS retry attempts. A paid chunked upload is bought before any
+        // chunk is accepted, so an attempt that fails after paying must hand its
+        // upload id to the next attempt. Rebuilding the uploader with no id is how
+        // a single upload gets billed once per retry.
+        let paidUploadId;
         const maxRetries = this.retryConfig.retries ?? 3;
         const retryDelay = this.retryConfig.retryDelay ??
             ((retryNumber) => retryNumber * 1000);
@@ -250,9 +336,8 @@ class TurboAuthenticatedBaseUploadService extends TurboUnauthenticatedUploadServ
             });
             if (fundingMode instanceof types_js_1.OnDemandFunding &&
                 cryptoFundResult === undefined) {
-                const totalByteCount = dataItemSizeFactory();
                 cryptoFundResult = await this.onDemand({
-                    totalByteCount,
+                    itemByteCounts: [dataItemSizeFactory()],
                     onDemandFunding: fundingMode,
                 });
             }
@@ -283,6 +368,7 @@ class TurboAuthenticatedBaseUploadService extends TurboUnauthenticatedUploadServ
                     dataItemByteCount: dataItemSizeFactory(),
                     chunkingMode: params.chunkingMode,
                     maxFinalizeMs: params.maxFinalizeMs,
+                    paidUploadId,
                     ...(x402Options ? { x402: x402Options } : {}),
                     ...(x402Options
                         ? {
@@ -294,14 +380,21 @@ class TurboAuthenticatedBaseUploadService extends TurboUnauthenticatedUploadServ
                         : {}),
                 });
                 if (chunkedUploader.shouldUseChunkUploader) {
-                    const response = await chunkedUploader.upload({
-                        dataItemStreamFactory,
-                        dataItemSizeFactory,
-                        dataItemOpts,
-                        signal,
-                        events,
-                    });
-                    return { ...response, cryptoFundResult };
+                    try {
+                        const response = await chunkedUploader.upload({
+                            dataItemStreamFactory,
+                            dataItemSizeFactory,
+                            dataItemOpts,
+                            signal,
+                            events,
+                        });
+                        return { ...response, cryptoFundResult };
+                    }
+                    finally {
+                        // Read on the way out, success or failure. On failure this is the
+                        // whole point: the next attempt resumes what this one paid for.
+                        paidUploadId = chunkedUploader.currentPaidUploadId ?? paidUploadId;
+                    }
                 }
                 const response = await this.uploadSignedDataItem({
                     dataItemStreamFactory,
@@ -346,6 +439,28 @@ class TurboAuthenticatedBaseUploadService extends TurboUnauthenticatedUploadServ
         }
         throw new errors_js_2.FailedRequestError(msg, lastStatusCode);
     }
+    /**
+     * Returns an upper bound on the bytes in a folder's manifest, if every file
+     * lands. Data item ids are always 43 characters, so placeholder ids give the
+     * real length, except for the index path: without an index file, the
+     * manifest indexes whichever file finished first, so the estimate allows for
+     * the longest path there.
+     */
+    async plannedManifestByteCount({ relativePaths, indexFile, fallbackFile, }) {
+        const placeholder = { id: 'x'.repeat(43) };
+        const paths = {};
+        let longestPathByteCount = 0;
+        for (const path of relativePaths) {
+            paths[path] = placeholder;
+            longestPathByteCount = Math.max(longestPathByteCount, Buffer.byteLength(JSON.stringify(path)));
+        }
+        const manifest = await this.generateManifest({
+            paths,
+            indexFile,
+            fallbackFile,
+        });
+        return Buffer.byteLength(JSON.stringify(manifest)) + longestPathByteCount;
+    }
     async generateManifest({ paths, indexFile, fallbackFile, }) {
         const indexPath = 
         // Use the user provided index file if it exists,
@@ -750,11 +865,20 @@ class TurboAuthenticatedBaseUploadService extends TurboUnauthenticatedUploadServ
         };
         let cryptoFundResult;
         if (fundingMode instanceof types_js_1.OnDemandFunding) {
-            const totalByteCount = filesToUpload.reduce((acc, file) => {
-                return acc + this.getFileSize(file) + 1200; // allow extra per file for ANS-104 headers
-            }, 0);
+            // allow extra per item for ANS-104 headers
+            const headerByteCount = 1200;
+            const itemByteCounts = filesToUpload.map((file) => this.getFileSize(file) + headerByteCount);
+            // The manifest spends the same balance. Left out of the estimate, it
+            // needed a second top-up of its own.
+            if (!disableManifest && files.length > 0) {
+                itemByteCounts.push((await this.plannedManifestByteCount({
+                    relativePaths: files.map((file) => this.getRelativePath(file, params)),
+                    indexFile,
+                    fallbackFile,
+                })) + headerByteCount);
+            }
             cryptoFundResult = await this.onDemand({
-                totalByteCount,
+                itemByteCounts,
                 onDemandFunding: fundingMode,
             });
         }
@@ -886,6 +1010,54 @@ class TurboAuthenticatedBaseUploadService extends TurboUnauthenticatedUploadServ
         }
         return revokedApprovals;
     }
+    /**
+     * The winc the service will charge for the given items. Never less.
+     *
+     * The service prices an item as a per-byte rate plus a fixed per-item
+     * charge, rounded up per item: a zero-byte item costs about 8M winc. Scaling
+     * the 1 GiB price down to the item size dropped that fixed part, so a small
+     * upload was under funded by up to ~38%, a folder by roughly the fixed charge
+     * per file, and `topUpBufferMultiplier: 1` could never succeed.
+     *
+     * Items from 1 byte to 1 GiB are priced from two quotes, at 1 byte and 1 GiB.
+     * The line through those two (already rounded up) prices never falls below
+     * the service's unrounded price anywhere between them, so rounding each item
+     * up keeps every estimate, and their sum, at or above what the service
+     * charges. Rounding only the total could not promise that. Anything the line
+     * would have to extrapolate to, and a lone item, is quoted exactly.
+     *
+     * The two quotes are made once per estimate. Each file of a folder still
+     * checks its own price when it uploads.
+     */
+    async estimateUploadWinc(itemByteCounts) {
+        const oneGiB = 2 ** 30;
+        const inModelRange = (bytes) => bytes >= 1 && bytes <= oneGiB;
+        const useModel = itemByteCounts.filter(inModelRange).length > 1;
+        const modelled = useModel ? itemByteCounts.filter(inModelRange) : [];
+        const quoted = useModel
+            ? itemByteCounts.filter((bytes) => !inModelRange(bytes))
+            : itemByteCounts;
+        const bytes = useModel ? [1, oneGiB, ...quoted] : quoted;
+        if (bytes.length === 0) {
+            return '0';
+        }
+        const quotes = await this.paymentService.getUploadCosts({ bytes });
+        let total = (useModel ? quotes.slice(2) : quotes).reduce((sum, { winc }) => sum.plus(winc), new bignumber_js_1.BigNumber(0));
+        if (useModel) {
+            const [oneByte, gibibyte] = quotes;
+            const perByte = new bignumber_js_1.BigNumber(gibibyte.winc)
+                .minus(oneByte.winc)
+                .dividedBy(oneGiB - 1);
+            const perItem = new bignumber_js_1.BigNumber(oneByte.winc).minus(perByte);
+            for (const itemBytes of modelled) {
+                total = total.plus(perByte
+                    .multipliedBy(itemBytes)
+                    .plus(perItem)
+                    .integerValue(bignumber_js_1.BigNumber.ROUND_UP));
+            }
+        }
+        return total.toFixed(0);
+    }
     /**
      * Triggers an upload that will top-up the wallet with Credits for the amount before uploading.
      * First, it calculates the expected cost of the upload. Next, it checks the wallet for existing
@@ -893,16 +1065,10 @@ class TurboAuthenticatedBaseUploadService extends TurboUnauthenticatedUploadServ
      * and await for the balance to be credited.
      * Note: Only `ario`, `solana`, and `base-eth` tokens are currently supported for on-demand uploads.
      */
-    async onDemand({ totalByteCount, onDemandFunding, }) {
+    async onDemand({ itemByteCounts, onDemandFunding, }) {
         const { maxTokenAmount, topUpBufferMultiplier } = onDemandFunding;
         const currentBalance = await this.paymentService.getBalance();
-        const wincPriceForOneGiB = (await this.paymentService.getUploadCosts({
-            bytes: [2 ** 30],
-        }))[0].winc;
-        const expectedWincPrice = new bignumber_js_1.BigNumber(wincPriceForOneGiB)
-            .multipliedBy(totalByteCount)
-            .dividedBy(2 ** 30)
-            .toFixed(0, bignumber_js_1.BigNumber.ROUND_UP);
+        const expectedWincPrice = await this.estimateUploadWinc(itemByteCounts);
         if ((0, bignumber_js_1.BigNumber)(currentBalance.effectiveBalance).isGreaterThanOrEqualTo(expectedWincPrice)) {
             this.logger.debug('Sufficient balance for on demand upload', {
                 currentBalance,
@@ -930,7 +1096,15 @@ class TurboAuthenticatedBaseUploadService extends TurboUnauthenticatedUploadServ
             .toFixed(0, bignumber_js_1.BigNumber.ROUND_UP);
         if (maxTokenAmount !== undefined) {
             if (new bignumber_js_1.BigNumber(topUpTokenAmount).isGreaterThan(maxTokenAmount)) {
-                throw new Error(`Top up token amount ${new bignumber_js_1.BigNumber(topUpTokenAmount).div(index_js_1.exponentMap[this.token])} is greater than the maximum allowed amount of ${maxTokenAmount}`);
+                // Both amounts are in base units. Report them in whole tokens: the
+                // exponent is the number of decimals, so divide by 10 to that power.
+                const baseUnitsPerToken = new bignumber_js_1.BigNumber(10).pow(index_js_1.exponentMap[this.token]);
+                throw new Error(`Top up token amount ${new bignumber_js_1.BigNumber(topUpTokenAmount)
+                    .div(baseUnitsPerToken)
+                    .toFixed()} ${this.token} is greater than the maximum allowed ` +
+                    `amount of ${new bignumber_js_1.BigNumber(maxTokenAmount)
+                        .div(baseUnitsPerToken)
+                        .toFixed()} ${this.token}`);
             }
         }
         this.logger.debug(`Topping up wallet with ${topUpTokenAmount} ${this.token} for ${topUpWincAmount} winc`);
@@ -983,3 +1157,101 @@ class TurboAuthenticatedBaseUploadService extends TurboUnauthenticatedUploadServ
     }
 }
 exports.TurboAuthenticatedBaseUploadService = TurboAuthenticatedBaseUploadService;
+/**
+ * The largest data item the x402 single-request path will buffer.
+ *
+ * Normally unreachable: anything over two chunks takes the chunked path, which
+ * pays at create and streams. It bites only when chunking is explicitly
+ * disabled, and it exists so that case fails with an explanation rather than
+ * by exhausting memory.
+ */
+const maxX402SingleRequestByteCount = 100 * 1024 * 1024;
+/**
+ * Headroom for what signing ADDS, so the guard measures the thing that is
+ * actually buffered.
+ *
+ * The limit applies to the signed data item, not the file: ANS-104 headers,
+ * the signature and the caller's tags all ride along. Checking the raw size
+ * let a file in the top of the range through, to be signed, buffered, and then
+ * refused by the service — wasting precisely the expensive step the guard
+ * exists to skip.
+ *
+ * Same allowance folder uploads already use for the same overhead.
+ */
+const x402SignedItemOverheadByteCount = 1200;
+/**
+ * Drain a data-item stream into a Buffer, resuming it once the reader is
+ * attached so upload-progress events still fire.
+ *
+ * Checks the running total as it fills rather than at the end: a stream that
+ * overruns its declared size would otherwise be held in memory in full before
+ * anything objected.
+ */
+async function streamToBuffer(stream, byteCount, resume, signal) {
+    // A closure, so TypeScript does not narrow `aborted` away for the whole
+    // function — it genuinely can flip while the stream is draining.
+    const isAborted = () => signal?.aborted === true;
+    if (isAborted()) {
+        throw new errors_js_1.AbortError();
+    }
+    const chunks = [];
+    let received = 0;
+    const take = (chunk) => {
+        received += chunk.byteLength;
+        if (received > byteCount) {
+            throw new Error(`Data item stream exceeded its declared size of ${byteCount} bytes`);
+        }
+        chunks.push(chunk);
+    };
+    if (stream instanceof node_stream_1.Readable) {
+        const done = new Promise((resolve, reject) => {
+            const onAbort = () => {
+                stream.destroy();
+                reject(new errors_js_1.AbortError());
+            };
+            signal?.addEventListener('abort', onAbort, { once: true });
+            stream.on('data', (c) => {
+                try {
+                    take(Buffer.from(c));
+                }
+                catch (error) {
+                    stream.destroy();
+                    reject(error);
+                }
+            });
+            stream.on('end', () => {
+                signal?.removeEventListener('abort', onAbort);
+                resolve();
+            });
+            stream.on('error', reject);
+        });
+        resume();
+        await done;
+    }
+    else {
+        const reader = stream.getReader();
+        resume();
+        try {
+            for (;;) {
+                if (isAborted()) {
+                    await reader.cancel();
+                    throw new errors_js_1.AbortError();
+                }
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                if (value !== undefined)
+                    take(Buffer.from(value));
+            }
+        }
+        catch (error) {
+            await reader.cancel().catch(() => undefined);
+            throw error;
+        }
+    }
+    const buf = Buffer.concat(chunks);
+    if (buf.byteLength !== byteCount) {
+        throw new Error(`Data item stream produced ${buf.byteLength} bytes, expected ${byteCount}`);
+    }
+    return buf;
+}

package/lib/esm/common/chunked.js

@@ -35,13 +35,14 @@ 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, x402, x402RefundIdentity, }) {
+    constructor({ http, token, maxChunkConcurrency = defaultMaxChunkConcurrency, maxFinalizeMs, chunkByteCount = defaultChunkByteCount, logger = Logger.default, chunkingMode = 'auto', dataItemByteCount, x402, x402RefundIdentity, paidUploadId, }) {
         this.assertChunkParams({
             chunkByteCount,
             chunkingMode,
             maxChunkConcurrency,
             maxFinalizeMs,
         });
+        this.paidUploadId = paidUploadId;
         this.chunkByteCount = chunkByteCount;
         this.maxChunkConcurrency = maxChunkConcurrency;
         this.maxFinalizeMs = maxFinalizeMs;
@@ -139,6 +140,14 @@ export class ChunkedUploader {
         this.paidUploadId = res.id;
         return res.id;
     }
+    /**
+     * The paid upload id, once one has been bought. `uploadFile` reads this after
+     * a failed attempt so the next attempt resumes the upload already paid for
+     * rather than buying a second one.
+     */
+    get currentPaidUploadId() {
+        return this.paidUploadId;
+    }
     async initUpload() {
         if (this.x402 !== undefined) {
             return this.initPaidUpload(this.x402);

package/lib/esm/common/http.js

@@ -48,8 +48,21 @@ export class TurboHTTPService {
         this.baseURL = url;
         this.retryConfig = retryConfig;
     }
+    /**
+     * Refuse to pay over cleartext.
+     *
+     * An x402 payment authorization is a bearer credential: anyone who observes
+     * it can submit it. Sending one over `http:` hands it to the network, so a
+     * misconfigured service URL must fail loudly rather than quietly leak.
+     */
+    assertSecureForPayment() {
+        if (!this.baseURL.startsWith('https:') && !isLoopback(this.baseURL)) {
+            throw new Error(`Refusing to send an x402 payment over a non-HTTPS URL: ${this.baseURL}`);
+        }
+    }
     async get({ endpoint, signal, allowedStatuses = [200, 202], headers, x402Options, }) {
         if (x402Options !== undefined) {
+            this.assertSecureForPayment();
             const maxMUSDCAmount = x402Options.maxMUSDCAmount !== undefined
                 ? BigInt(x402Options.maxMUSDCAmount.toString())
                 : undefined;
@@ -158,6 +171,7 @@ export class TurboHTTPService {
             endpoint,
             x402Options,
         });
+        this.assertSecureForPayment();
         const { body, duplex } = await toFetchBody(data);
         return this.tryRequest(async () => {
             const maxMUSDCAmount = x402Options.maxMUSDCAmount !== undefined
@@ -208,3 +222,13 @@ function isFirefoxOrSafari() {
             !ua.includes('Chrome') &&
             !ua.includes('Chromium')));
 }
+/** Loopback is exempt: local development never leaves the machine. */
+function isLoopback(url) {
+    try {
+        const { hostname } = new URL(url);
+        return (hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1');
+    }
+    catch {
+        return false;
+    }
+}

package/lib/esm/common/payment.js

@@ -653,13 +653,20 @@ export class TurboAuthenticatedPaymentService extends TurboUnauthenticatedPaymen
      * The owner needs a Solana key to sign with, NOT a funded one — Turbo pays
      * every lamport of fee and rent.
      */
-    async buyArNSName({ name, owner, type = 'lease', years, paidBy, onNonce, }) {
+    async buyArNSName({ name, owner, type = 'lease', years, paidBy, onNonce, antState, }) {
         return this.completeArNSAction('buy-name', {
             name,
             ownerAddress: await owner.getAddress(),
             type,
             ...(years !== undefined ? { years } : {}),
             ...(paidBy !== undefined ? { paidBy } : {}),
+            /*
+              Spread conditionally, like `paidBy` — an `antState: undefined` key
+              would serialize into the body and is not the same request as omitting
+              it. Sent whole in the BODY rather than the query string: it is an
+              object, and `createArNSAction` already posts every param as JSON.
+            */
+            ...(antState !== undefined ? { antState } : {}),
         }, owner, { onNonce });
     }
     /** Extend a lease. Permissionless on chain — no owner signature needed. */