@shelby-protocol/sdk 0.0.8 → 0.1.0

package/dist/core/clients/ShelbyBlobClient.d.ts

@@ -1,4 +1,4 @@
-import { Aptos, AccountAddress, AccountAddressInput, Account, InputGenerateTransactionOptions, PendingTransactionResponse, InputGenerateTransactionPayloadData } from '@aptos-labs/ts-sdk';
+import { InputGenerateTransactionOptions, Aptos, AccountAddress, InputTransactionPluginData, AccountAddressInput, Account, PendingTransactionResponse, InputGenerateTransactionPayloadData } from '@aptos-labs/ts-sdk';
 import { BlobName } from '../layout.js';
 import { BlobMetadata, BlobActivity, StorageProviderAck } from '../types/blobs.js';
 import { ShelbyIndexerClient } from '../operations/index.js';
@@ -11,27 +11,62 @@ import 'graphql-request';
 import 'graphql';
 import '../networks.js';
 
+/**
+ * Error thrown when USD sponsorship is configured without a transaction submitter.
+ * USD sponsorship requires a transaction submitter because the sponsored transaction
+ * is a multi-agent transaction that must be co-signed by the sponsor.
+ */
+declare class MissingTransactionSubmitterError extends Error {
+    constructor();
+}
+interface BuildOptions {
+    options?: InputGenerateTransactionOptions;
+    withFeePayer?: boolean;
+}
+interface UsdSponsorOptions {
+    /**
+     * This should be provided by your gas station provider (e.g. Geomi) after you create
+     * a gas station.
+     */
+    feePayerAddress: AccountAddress;
+}
 interface WriteBlobCommitmentsOptions {
-    build?: {
-        options?: InputGenerateTransactionOptions;
-    };
+    build?: BuildOptions;
+    submit?: InputTransactionPluginData;
+    /**
+     * Whereas build.withFeePayer corresponds to regular APT fee sponsorship, this refers
+     * to the Shelby-specific fees in stables. If set, we will use the sponsored variants
+     * of the various entry functions, e.g. register_blob_with_sponsor rather than
+     * register_blob. Aptos right now requires that the payload includes the address of
+     * the second signer when it is initially built, so you must provide the fee payer
+     * address of your gas station.
+     *
+     * These payloads by definition must be signed by the sponsor as well, so you must
+     * also configure a `transactionSubmitter` in your Aptos client's pluginSettings
+     * (via `aptos.pluginSettings.TRANSACTION_SUBMITTER`) that sends the transaction to
+     * an intermediate service (like a gas station) that co-signs the transaction.
+     *
+     * If `usdSponsor` is provided without a transaction submitter configured, an error
+     * will be thrown.
+     */
+    usdSponsor?: UsdSponsorOptions;
     chunksetSizeBytes?: number;
 }
 interface AckTransactionOptions {
-    build?: {
-        options?: InputGenerateTransactionOptions;
-    };
+    build?: BuildOptions;
 }
 declare class ShelbyBlobClient {
     readonly aptos: Aptos;
     readonly deployer: AccountAddress;
     readonly indexer: ShelbyIndexerClient;
+    readonly defaultOptions: WriteBlobCommitmentsOptions;
     /**
      * The ShelbyBlobClient is used to interact with the Shelby contract on the Aptos blockchain. This
      * includes functions for registering blob commitments and retrieving blob metadata.
      *
      * @param config - The client configuration object.
      * @param config.network - The Shelby network to use.
+     * @param defaultOptions - Optional default options for blob operations.
      *
      * @example
      * ```typescript
@@ -44,8 +79,37 @@ declare class ShelbyBlobClient {
      *   },
      * });
      * ```
+     *
+     * @example
+     * ```typescript
+     * // With default options for USD sponsorship
+     * const blobClient = new ShelbyBlobClient(
+     *   {
+     *     network: Network.SHELBYNET,
+     *     aptos: {
+     *       pluginSettings: {
+     *         TRANSACTION_SUBMITTER: myGasStationSubmitter,
+     *       },
+     *     },
+     *   },
+     *   {
+     *     usdSponsor: { feePayerAddress: sponsorAddress },
+     *   }
+     * );
+     * ```
+     */
+    constructor(config: ShelbyClientConfig, defaultOptions?: WriteBlobCommitmentsOptions);
+    /**
+     * Merges method-level options with default options, giving precedence to method-level values.
      */
-    constructor(config: ShelbyClientConfig);
+    private mergeOptions;
+    /**
+     * Validates that if USD sponsorship is requested, a transaction submitter is
+     * configured as well. Checks both the client-level and method-level transaction
+     * submitter configurations. Throws MissingTransactionSubmitterError if usdSponsor is
+     * provided without a transaction submitter.
+     */
+    private validateUsdSponsorConfig;
     /**
      * Retrieves the blob metadata from the blockchain. If it does not exist,
      * returns `undefined`.
@@ -190,6 +254,65 @@ declare class ShelbyBlobClient {
     }): Promise<{
         transaction: PendingTransactionResponse;
     }>;
+    /**
+     * Deletes a blob on the blockchain.
+     *
+     * @param params.account - The account that is signing and paying for the transaction.
+     * @param params.blobName - The name/path of the blob (e.g. "foo/bar.txt").
+     * @param params.options - Optional transaction building options.
+     *
+     * @returns An object containing the pending transaction.
+     *
+     * @example
+     * ```typescript
+     *
+     * const { transaction } = await client.deleteBlob({
+     *   account: signer,
+     *   blobName: "foo/bar.txt",
+     * });
+     * ```
+     */
+    deleteBlob(params: {
+        account: Account;
+        blobName: BlobName;
+        options?: InputGenerateTransactionOptions;
+    }): Promise<{
+        transaction: PendingTransactionResponse;
+    }>;
+    /**
+     * Deletes multiple blobs on the blockchain in a single atomic transaction.
+     *
+     * **Note:** This function requires the `delete_multiple_blobs` entry function
+     * which will be deployed to the smart contract on 2026-02-04. Using this
+     * function before that date will result in a transaction failure.
+     *
+     * This operation is atomic: if any blob deletion fails (e.g., blob not found),
+     * the entire transaction fails and no blobs are deleted.
+     *
+     * @param params.account - The account that is signing and paying for the transaction.
+     * @param params.blobNames - Array of blob name suffixes without the account address prefix
+     *   (e.g. ["foo/bar.txt", "baz.txt"], NOT ["0x1/foo/bar.txt"]). The account address
+     *   prefix is automatically derived from the signer.
+     * @param params.options - Optional transaction building options.
+     *
+     * @returns An object containing the pending transaction.
+     *
+     * @example
+     * ```typescript
+     *
+     * const { transaction } = await client.deleteMultipleBlobs({
+     *   account: signer,
+     *   blobNames: ["foo/bar.txt", "baz.txt"],
+     * });
+     * ```
+     */
+    deleteMultipleBlobs(params: {
+        account: Account;
+        blobNames: BlobName[];
+        options?: InputGenerateTransactionOptions;
+    }): Promise<{
+        transaction: PendingTransactionResponse;
+    }>;
     /**
      * Acks the blob chunksets on-chain. If each chunkset meets the necessary threshold, the entire blob will be marked as written.
      *
@@ -295,6 +418,7 @@ declare class ShelbyBlobClient {
         blobMerkleRoot: string;
         expirationMicros: number;
         numChunksets: number;
+        useSponsoredUsdVariant?: boolean;
     }): InputGenerateTransactionPayloadData;
     /**
      * Creates a transaction payload to register multiple blobs on the blockchain.
@@ -323,13 +447,14 @@ declare class ShelbyBlobClient {
             blobMerkleRoot: string;
             numChunksets: number;
         }[];
+        useSponsoredUsdVariant?: boolean;
     }): InputGenerateTransactionPayloadData;
     /**
      * Creates a transaction payload to delete a blob on the blockchain.
      * This is a static helper method for constructing the Move function call payload.
      *
      * @param params.deployer - Optional deployer account address. Defaults to SHELBY_DEPLOYER.
-     * @param params.blobNameSuffix - The blob name suffix (e.g. "bar.txt").
+     * @param params.blobName - The blob name (e.g. "bar.txt", without the account address prefix).
      *
      * @returns An Aptos transaction payload data object for the delete_blob Move function.
      *
@@ -337,7 +462,31 @@ declare class ShelbyBlobClient {
      */
     static createDeleteBlobPayload(params: {
         deployer?: AccountAddress;
-        blobNameSuffix: string;
+        blobName: string;
+    }): InputGenerateTransactionPayloadData;
+    /**
+     * Creates a transaction payload to delete multiple blobs on the blockchain.
+     * This is a static helper method for constructing the Move function call payload.
+     *
+     * **Note:** This function requires the `delete_multiple_blobs` entry function
+     * which will be deployed to the smart contract on 2026-02-04. Using this
+     * function before that date will result in a transaction failure.
+     *
+     * This operation is atomic: if any blob deletion fails (e.g., blob not found),
+     * the entire transaction fails and no blobs are deleted.
+     *
+     * @param params.deployer - Optional deployer account address. Defaults to SHELBY_DEPLOYER.
+     * @param params.blobNames - Array of blob name suffixes without the account address prefix
+     *   (e.g. ["foo/bar.txt", "baz.txt"], NOT ["0x1/foo/bar.txt"]). The account address
+     *   prefix is automatically derived from the transaction sender.
+     *
+     * @returns An Aptos transaction payload data object for the delete_multiple_blobs Move function.
+     *
+     * @see https://github.com/shelby/shelby/blob/main/move/shelby_contract/sources/blob_metadata.move
+     */
+    static createDeleteMultipleBlobsPayload(params: {
+        deployer?: AccountAddress;
+        blobNames: string[];
     }): InputGenerateTransactionPayloadData;
     static createChunksetAcknowledgementsPayload(params: {
         blobOwner: AccountAddress;
@@ -348,4 +497,4 @@ declare class ShelbyBlobClient {
     }): InputGenerateTransactionPayloadData;
 }
 
-export { type AckTransactionOptions, ShelbyBlobClient, type WriteBlobCommitmentsOptions };
+export { type AckTransactionOptions, type BuildOptions, MissingTransactionSubmitterError, ShelbyBlobClient, type UsdSponsorOptions, type WriteBlobCommitmentsOptions };

package/dist/core/clients/ShelbyBlobClient.mjs

@@ -1,20 +1,22 @@
 import {
+  MissingTransactionSubmitterError,
   ShelbyBlobClient
-} from "../../chunk-BBOG5JSX.mjs";
+} from "../../chunk-AGRRYZWV.mjs";
 import "../../chunk-XNEIWM4O.mjs";
+import "../../chunk-OMZOR2ZF.mjs";
+import "../../chunk-UCDAABAS.mjs";
 import "../../chunk-PZF2VTGP.mjs";
-import "../../chunk-HFGEQP5N.mjs";
-import "../../chunk-WJKSPJSS.mjs";
-import "../../chunk-RBFWGDMY.mjs";
-import "../../chunk-CPNZAQVY.mjs";
-import "../../chunk-NLPIHQ7K.mjs";
+import "../../chunk-3ZL3FSNA.mjs";
+import "../../chunk-KJ24NKPH.mjs";
+import "../../chunk-AABBONAF.mjs";
 import "../../chunk-OTBLZL2S.mjs";
-import "../../chunk-XWAPNLU6.mjs";
+import "../../chunk-RLRI2533.mjs";
 import "../../chunk-4JZO2D7T.mjs";
-import "../../chunk-SEXQTDX6.mjs";
 import "../../chunk-67F5YZ25.mjs";
-import "../../chunk-ZPW742E7.mjs";
+import "../../chunk-LZSIZJYR.mjs";
+import "../../chunk-FLLOQZVD.mjs";
 import "../../chunk-7P6ASYW6.mjs";
 export {
+  MissingTransactionSubmitterError,
   ShelbyBlobClient
 };

package/dist/core/clients/ShelbyClient.d.ts

@@ -1,18 +1,19 @@
-import { WriteBlobCommitmentsOptions, ShelbyBlobClient } from './ShelbyBlobClient.js';
 import { Aptos, Account, AccountAddressInput } from '@aptos-labs/ts-sdk';
 import { ShelbyBlob } from '../blobs.js';
 import { a as ErasureCodingProvider } from '../../clay-codes-pdZFxI_B.js';
 import { BlobName } from '../layout.js';
+import { WriteBlobCommitmentsOptions, ShelbyBlobClient } from './ShelbyBlobClient.js';
 import { ShelbyClientConfig } from './ShelbyClientConfig.js';
 import { ShelbyRPCClient } from './ShelbyRPCClient.js';
-import '../types/blobs.js';
-import '@shelby-protocol/clay-codes';
 import 'zod';
+import '@shelby-protocol/clay-codes';
+import '../types/blobs.js';
 import '../operations/index.js';
 import 'graphql-request';
 import '../operations/generated/sdk.js';
 import 'graphql';
 import '../networks.js';
+import '../types/payments.js';
 
 type UploadOptions = WriteBlobCommitmentsOptions;
 declare class ShelbyClient {
@@ -83,6 +84,11 @@ declare class ShelbyClient {
      * This method handles the complete upload flow including commitment generation,
      * blockchain registration, and storage upload.
      *
+     * Note: This method accepts only `Uint8Array` and buffers the entire blob in memory.
+     * For streaming uploads of large files (e.g. >2 GiB), orchestrate the steps manually
+     * using `generateCommitments()`, `coordination.registerBlob()`, and `rpc.putBlob()`
+     * with a `ReadableStream`.
+     *
      * @param params.blobData - The raw data to upload as a Uint8Array.
      * @param params.signer - The account that signs and pays for the transaction.
      * @param params.blobName - The name/path of the blob (e.g. "folder/file.txt").
@@ -115,6 +121,11 @@ declare class ShelbyClient {
      * This method handles the complete upload flow including commitment generation,
      * blockchain registration, and storage upload.
      *
+     * Note: This method accepts only `Uint8Array` and buffers each blob in memory.
+     * For streaming uploads of large files, orchestrate the steps manually using
+     * `generateCommitments()`, `coordination.registerBlob()`, and `rpc.putBlob()`
+     * with a `ReadableStream`.
+     *
      * @param params.blobs - The blobs to upload.
      * @param params.blobs.blobData - The raw data to upload as a Uint8Array.
      * @param params.blobs.blobName - The name/path of the blob (e.g. "folder/file.txt").

package/dist/core/clients/ShelbyClient.mjs

@@ -1,23 +1,25 @@
 import {
   ShelbyClient
-} from "../../chunk-MGAN2SBA.mjs";
-import "../../chunk-QRGZJBAG.mjs";
-import "../../chunk-I6NG5GNL.mjs";
-import "../../chunk-BBOG5JSX.mjs";
+} from "../../chunk-W6YL46DT.mjs";
+import "../../chunk-AGRRYZWV.mjs";
 import "../../chunk-XNEIWM4O.mjs";
+import "../../chunk-OMZOR2ZF.mjs";
+import "../../chunk-UCDAABAS.mjs";
 import "../../chunk-PZF2VTGP.mjs";
-import "../../chunk-HFGEQP5N.mjs";
-import "../../chunk-WJKSPJSS.mjs";
-import "../../chunk-RBFWGDMY.mjs";
-import "../../chunk-CPNZAQVY.mjs";
-import "../../chunk-NLPIHQ7K.mjs";
+import "../../chunk-ZAM2EUVN.mjs";
+import "../../chunk-4MG4XGY4.mjs";
+import "../../chunk-3ZL3FSNA.mjs";
+import "../../chunk-KJ24NKPH.mjs";
+import "../../chunk-AABBONAF.mjs";
+import "../../chunk-W5NRGZEP.mjs";
+import "../../chunk-I6NG5GNL.mjs";
+import "../../chunk-IE6LYVIA.mjs";
 import "../../chunk-OTBLZL2S.mjs";
-import "../../chunk-XWAPNLU6.mjs";
+import "../../chunk-RLRI2533.mjs";
 import "../../chunk-4JZO2D7T.mjs";
-import "../../chunk-SEXQTDX6.mjs";
-import "../../chunk-GY5DCVVL.mjs";
 import "../../chunk-67F5YZ25.mjs";
-import "../../chunk-ZPW742E7.mjs";
+import "../../chunk-LZSIZJYR.mjs";
+import "../../chunk-FLLOQZVD.mjs";
 import "../../chunk-7P6ASYW6.mjs";
 export {
   ShelbyClient

package/dist/core/clients/ShelbyClientConfig.d.ts

@@ -42,8 +42,13 @@ interface ShelbyClientConfig {
     rpc?: ShelbyRPCConfig;
     /** An optional indexer configuration for GraphQL queries. If not provided, the default indexer will be used. */
     indexer?: ShelbyIndexerConfig;
-    /** An optional faucet URL for funding accounts. If not provided, the default faucet will be used. */
-    faucet?: string;
+    /** An optional faucet configuration. */
+    faucet?: {
+        /** An optional faucet URL for funding accounts. If not provided, the default faucet will be used. */
+        baseUrl?: string;
+        /** Auth token for the faucet endpoint. */
+        authToken?: string;
+    };
 }
 
 export type { ShelbyClientConfig, ShelbyIndexerConfig, ShelbyRPCConfig };