@shelby-protocol/sdk 0.3.1 → 0.4.1

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

@@ -1,6 +1,6 @@
 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 { FullObjectMetadata, BlobActivity, BlobEncryption, StorageProviderAck } from '../types/blobs.js';
 import { E as ErasureCodingConfig } from '../../clay-codes-DdXABBDx.js';
 import { ShelbyIndexerClient } from '../operations/index.js';
 import { Blobs_Order_By, Blobs_Bool_Exp, Blob_Activities_Bool_Exp, Blob_Activities_Order_By } from '../operations/generated/sdk.js';
@@ -19,6 +19,22 @@ import '../networks.js';
 declare class MissingTransactionSubmitterError extends Error {
     constructor();
 }
+/**
+ * Why `commit_object` rejected a write, mirroring the contract's
+ * `CommitRejectionReason` variants (blob_metadata.move).
+ */
+type CommitRejectionReason = "AlreadyExists" | "NoPriorVersion" | "EtagMismatch";
+/**
+ * Thrown when `commit_object` rejected a write instead of applying it. The
+ * transaction itself succeeded; the contract tore down the pending blob and
+ * emitted `ObjectCommitRejectedEvent` rather than aborting.
+ */
+declare class ObjectCommitRejectedError extends Error {
+    readonly blobName: BlobName;
+    readonly uid: bigint;
+    readonly reason: CommitRejectionReason;
+    constructor(blobName: BlobName, uid: bigint, reason: CommitRejectionReason);
+}
 interface BuildOptions {
     options?: InputGenerateTransactionOptions;
     withFeePayer?: boolean;
@@ -51,6 +67,18 @@ interface WriteBlobCommitmentsOptions {
      */
     usdSponsor?: UsdSponsorOptions;
     chunksetSizeBytes?: number;
+    /**
+     * The location (region) to write the blob to. Authoritative: the write lands there
+     * or aborts on chain (e.g. if the account's location preference is locked to a
+     * different location).
+     */
+    selectedLocation?: string;
+    /**
+     * Best-effort location hint, typically derived from where the client runs. Honored
+     * only for accounts in the default `FollowHint` preference mode, and overridden by
+     * `selectedLocation`. Defaults to `ShelbyClientConfig.locationHint`.
+     */
+    locationHint?: string;
 }
 interface AckTransactionOptions {
     build?: BuildOptions;
@@ -128,16 +156,33 @@ declare class ShelbyBlobClient {
      *
      * @example
      * ```typescript
-     * const metadata = await client.getBlobMetadata({
+     * const metadata = await client.getFullObjectMetadata({
      *   account: AccountAddress.fromString("0x1"),
      *   name: "foo/bar.txt",
      * });
      * ```
      */
-    getBlobMetadata(params: {
+    getFullObjectMetadata(params: {
         account: AccountAddressInput;
         name: BlobName;
-    }): Promise<BlobMetadata | undefined>;
+    }): Promise<FullObjectMetadata | undefined>;
+    /**
+     * Retrieves blob metadata directly by its on-chain UID, including blobs in
+     * the pending (registered-but-not-yet-committed) state that
+     * {@link getFullObjectMetadata} cannot resolve by object name. Returns `undefined`
+     * if no blob has that UID.
+     *
+     * The returned `name`/`blobNameSuffix` are empty: the blob layer is keyed by
+     * UID and carries no object name (a name binding is established only at
+     * commit). `isWritten` reflects whether the blob has been committed.
+     */
+    getFullObjectMetadataByUid(uid: bigint): Promise<FullObjectMetadata | undefined>;
+    /**
+     * Parse the on-chain `BlobMetadata::V1` view shape into the SDK
+     * {@link FullObjectMetadata}. `uid` / `name` / `isWritten` are supplied by the
+     * caller since they depend on the lookup path (by object name vs by UID).
+     */
+    private parseBlobMetadata;
     /**
      * Retrieves all the blobs and their metadata for an account from the
      * blockchain.
@@ -149,7 +194,7 @@ declare class ShelbyBlobClient {
      *
      * @example
      * ```typescript
-     * // BlobMetadata[]
+     * // FullObjectMetadata[]
      * const blobs = await client.getAccountBlobs({
      *   account: AccountAddress.fromString("0x1"),
      * });
@@ -163,7 +208,19 @@ declare class ShelbyBlobClient {
         };
         orderBy?: Blobs_Order_By;
         where?: Omit<Blobs_Bool_Exp, "owner">;
-    }): Promise<BlobMetadata[]>;
+    }): Promise<FullObjectMetadata[]>;
+    /**
+     * Object-facing default filter: only committed, non-deleted, unexpired rows.
+     * The blobs table is UID-keyed, so during an atomic overwrite a single
+     * object_name transiently has two non-deleted rows — the currently committed
+     * blob and the new pending (is_committed = "0") blob. Filtering on
+     * is_committed keeps name lookups/listings pinned to the committed object and
+     * avoids returning or duplicating the in-flight pending row. Applied to
+     * getBlobs *and* the getBlobsCount / getTotalBlobsSize aggregates so counts
+     * and sizes agree with the listing mid-overwrite. Callers can override any
+     * key (e.g. is_committed) via their own `where`.
+     */
+    private activeBlobsWhere;
     /**
      * Retrieves blobs and their metadata from the blockchain.
      *
@@ -174,7 +231,7 @@ declare class ShelbyBlobClient {
      *
      * @example
      * ```typescript
-     * // BlobMetadata[]
+     * // FullObjectMetadata[]
      * const blobs = await client.getBlobs({
      *   where: { owner: { _eq: AccountAddress.fromString("0x1").toString() } },
      * });
@@ -187,7 +244,7 @@ declare class ShelbyBlobClient {
             offset?: number;
         };
         orderBy?: Blobs_Order_By;
-    }): Promise<BlobMetadata[]>;
+    }): Promise<FullObjectMetadata[]>;
     getBlobActivities(params: {
         where?: Blob_Activities_Bool_Exp;
         pagination?: {
@@ -207,7 +264,7 @@ declare class ShelbyBlobClient {
      * const count = await client.getBlobsCount();
      * ```
      */
-    getBlobsCount(params: {
+    getBlobsCount(params?: {
         where?: Blobs_Bool_Exp;
     }): Promise<number>;
     /**
@@ -272,6 +329,7 @@ declare class ShelbyBlobClient {
         blobMerkleRoot: string;
         size: number;
         expirationMicros: number;
+        encryption?: BlobEncryption;
         config?: ErasureCodingConfig;
         options?: WriteBlobCommitmentsOptions;
     }): Promise<{
@@ -289,13 +347,13 @@ declare class ShelbyBlobClient {
      * @example
      * ```typescript
      *
-     * const { transaction } = await client.deleteBlob({
+     * const { transaction } = await client.deleteObject({
      *   account: signer,
      *   blobName: "foo/bar.txt",
      * });
      * ```
      */
-    deleteBlob(params: {
+    deleteObject(params: {
         account: Account;
         blobName: BlobName;
         options?: InputGenerateTransactionOptions;
@@ -305,10 +363,6 @@ declare class ShelbyBlobClient {
     /**
      * 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.
      *
@@ -323,13 +377,13 @@ declare class ShelbyBlobClient {
      * @example
      * ```typescript
      *
-     * const { transaction } = await client.deleteMultipleBlobs({
+     * const { transaction } = await client.deleteMultipleObjects({
      *   account: signer,
      *   blobNames: ["foo/bar.txt", "baz.txt"],
      * });
      * ```
      */
-    deleteMultipleBlobs(params: {
+    deleteMultipleObjects(params: {
         account: Account;
         blobNames: BlobName[];
         options?: InputGenerateTransactionOptions;
@@ -377,11 +431,49 @@ declare class ShelbyBlobClient {
             blobSize: number;
             blobMerkleRoot: string;
         }[];
+        encryption?: BlobEncryption;
         config?: ErasureCodingConfig;
         options?: WriteBlobCommitmentsOptions;
     }): Promise<{
         transaction: PendingTransactionResponse;
     }>;
+    /**
+     * Extracts the on-chain UIDs assigned at registration from a committed
+     * register transaction's events.
+     *
+     * `register_blob` / `register_multiple_blobs` create *pending* blobs and emit
+     * one `BlobRegisteredEvent` per blob. The UID is published only on this event
+     * (the blob is not yet in the `objects` map, so it cannot be read back by
+     * name), so callers must parse it here before uploading bytes or committing.
+     *
+     * @param events - The committed transaction's events (from `waitForTransaction`).
+     * @param deployer - The contract deployer address.
+     * @returns One entry per registered blob, keyed by its full object name
+     *   (`@<owner>/<suffix>`, matching {@link createBlobKey}).
+     */
+    static registeredBlobUids(events: ReadonlyArray<{
+        type: string;
+        data: unknown;
+    }>, deployer: AccountAddress): {
+        objectName: string;
+        uid: bigint;
+    }[];
+    /**
+     * Detects whether `commit_object` rejected the write for `uid` rather than
+     * applying it. A rejected commit is still a *successful* transaction — the
+     * contract tears down the pending blob and emits `ObjectCommitRejectedEvent`
+     * instead of aborting — so callers must inspect the finalized transaction's
+     * events to tell a durable write apart from a silent no-op.
+     *
+     * @param events - The committed transaction's events (from `waitForTransaction`).
+     * @param deployer - The contract deployer address.
+     * @param uid - The UID passed to `commit_object`.
+     * @returns The rejection reason, or `undefined` if the commit was applied.
+     */
+    static findObjectCommitRejection(events: ReadonlyArray<{
+        type: string;
+        data: unknown;
+    }>, deployer: AccountAddress, uid: bigint): CommitRejectionReason | undefined;
     /**
      * Creates a transaction payload to register a blob on the blockchain.
      * This is a static helper method for constructing the Move function call payload.
@@ -395,19 +487,25 @@ declare class ShelbyBlobClient {
      * @param params.numChunksets - The total number of chunksets in the blob.
      *
      * @returns An Aptos transaction payload data object for the register_blob Move function.
-     *
-     * @see https://github.com/shelby/shelby/blob/e08e84742cf2b80ad8bb7227deb3013398076d53/move/shelby_contract/sources/global_metadata.move#L357
      */
     static createRegisterBlobPayload(params: {
         deployer?: AccountAddress;
         account: AccountAddress;
         blobName: BlobName;
+        selectedLocation?: string;
+        locationHint?: string;
         blobSize: number;
         blobMerkleRoot: string;
         expirationMicros: number;
         numChunksets: number;
         useSponsoredUsdVariant?: boolean;
         encoding: number;
+        encryption?: BlobEncryption;
+        /**
+         * TEMP (#1739): drop the trailing encryption arg to match contracts that
+         * predate the encryption upgrade (e.g. shelbynet). Defaults to false.
+         */
+        omitEncryptionArg?: boolean;
     }): InputGenerateTransactionPayloadData;
     /**
      * Creates a transaction payload to register multiple blobs on the blockchain.
@@ -423,12 +521,12 @@ declare class ShelbyBlobClient {
      * @param params.blobs.numChunksets - The total number of chunksets in the blob.
      *
      * @returns An Aptos transaction payload data object for the register_multiple_blobs Move function.
-     *
-     * @see https://github.com/shelby/shelby/blob/e08e84742cf2b80ad8bb7227deb3013398076d53/move/shelby_contract/sources/global_metadata.move#L357
      */
     static createBatchRegisterBlobsPayload(params: {
         deployer?: AccountAddress;
         account: AccountAddress;
+        selectedLocation?: string;
+        locationHint?: string;
         expirationMicros: number;
         blobs: {
             blobName: BlobName;
@@ -438,6 +536,12 @@ declare class ShelbyBlobClient {
         }[];
         useSponsoredUsdVariant?: boolean;
         encoding: number;
+        encryption?: BlobEncryption;
+        /**
+         * TEMP (#1739): drop the trailing encryption arg to match contracts that
+         * predate the encryption upgrade (e.g. shelbynet). Defaults to false.
+         */
+        omitEncryptionArg?: boolean;
     }): InputGenerateTransactionPayloadData;
     /**
      * Creates a transaction payload to delete a blob on the blockchain.
@@ -446,11 +550,9 @@ declare class ShelbyBlobClient {
      * @param params.deployer - Optional deployer account address. Defaults to SHELBY_DEPLOYER.
      * @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.
-     *
-     * @see https://github.com/shelby/shelby/blob/64e9d7b4f0005e586faeb1e4085c79159234b6b6/move/shelby_contract/sources/global_metadata.move#L616
+     * @returns An Aptos transaction payload data object for the delete_object Move function.
      */
-    static createDeleteBlobPayload(params: {
+    static createDeleteObjectPayload(params: {
         deployer?: AccountAddress;
         blobName: string;
     }): InputGenerateTransactionPayloadData;
@@ -458,10 +560,6 @@ declare class ShelbyBlobClient {
      * 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.
      *
@@ -470,25 +568,42 @@ declare class ShelbyBlobClient {
      *   (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
+     * @returns An Aptos transaction payload data object for the delete_multiple_objects Move function.
      */
-    static createDeleteMultipleBlobsPayload(params: {
+    static createDeleteMultipleObjectsPayload(params: {
         deployer?: AccountAddress;
         blobNames: string[];
     }): InputGenerateTransactionPayloadData;
-    static createBlobAcknowledgementsPayload(params: {
-        blobOwner: AccountAddress;
+    /**
+     * Sort acks by slot and reduce to the `(ack_bits, signatures)` pair the
+     * contract expects: it walks the set bits low-to-high and consumes the
+     * signatures in that same order.
+     */
+    private static encodeAcks;
+    /**
+     * Payload for `commit_object(uid, object_name_suffix, overwrite, if_match_etag,
+     * ack_bits, signatures)` — binds a written pending blob under its object name,
+     * finalizing the upload. SP acks may be batched in here (the contract applies
+     * them before the `is_written` check), so register → upload → commit needs
+     * only a single finalize transaction.
+     *
+     * @param params.uid - The blob UID returned at registration.
+     * @param params.blobName - The object name suffix the blob was registered under.
+     * @param params.overwrite - Allow replacing an existing binding under this name.
+     * @param params.storageProviderAcks - Acks applied atomically with the commit.
+     */
+    static createCommitObjectPayload(params: {
+        deployer?: AccountAddress;
+        uid: bigint;
         blobName: BlobName;
-        creationMicros: number;
+        overwrite: boolean;
         storageProviderAcks: StorageProviderAck[];
     }): InputGenerateTransactionPayloadData;
-    addBlobAcknowledgements(params: {
+    commitObject(params: {
         account: Account;
-        blobOwner: AccountAddress;
+        uid: bigint;
         blobName: BlobName;
-        creationMicros: number;
+        overwrite: boolean;
         storageProviderAcks: StorageProviderAck[];
         options?: AckTransactionOptions;
     }): Promise<{
@@ -496,4 +611,4 @@ declare class ShelbyBlobClient {
     }>;
 }
 
-export { type AckTransactionOptions, type BuildOptions, MissingTransactionSubmitterError, ShelbyBlobClient, type UsdSponsorOptions, type WriteBlobCommitmentsOptions };
+export { type AckTransactionOptions, type BuildOptions, type CommitRejectionReason, MissingTransactionSubmitterError, ObjectCommitRejectedError, ShelbyBlobClient, type UsdSponsorOptions, type WriteBlobCommitmentsOptions };