@shelby-protocol/sdk 0.3.0 → 0.4.0

package/dist/core/clients/ShelbyPlacementGroupClient.mjs

@@ -1,11 +1,313 @@
-import {
-  ShelbyPlacementGroupClient
-} from "../../chunk-S6Q4OG7H.mjs";
-import "../../chunk-NEO7Z3ZQ.mjs";
-import "../../chunk-TET3DJEO.mjs";
-import "../../chunk-V4B3GAMQ.mjs";
-import "../../chunk-MNCQBEMS.mjs";
-import "../../chunk-7P6ASYW6.mjs";
+// src/core/operations/index.ts
+import { Network as Network2 } from "@aptos-labs/ts-sdk";
+import { GraphQLClient } from "graphql-request";
+
+// src/core/clients/utils.ts
+import { AptosConfig } from "@aptos-labs/ts-sdk";
+
+// src/core/constants.ts
+import { Network } from "@aptos-labs/ts-sdk";
+var NetworkToShelbyRPCBaseUrl = {
+  [Network.SHELBYNET]: "https://shelby.shelbynet.shelby.xyz/shelby",
+  [Network.NETNA]: void 0,
+  [Network.DEVNET]: void 0,
+  [Network.TESTNET]: "https://api.testnet.shelby.xyz/shelby",
+  [Network.MAINNET]: void 0,
+  [Network.LOCAL]: "http://localhost:9090",
+  [Network.CUSTOM]: void 0
+};
+var NetworkToShelbyBlobIndexerBaseUrl = {
+  [Network.SHELBYNET]: "https://api.shelbynet.aptoslabs.com/nocode/v1/public/alias/shelby/shelbynet/v1/graphql",
+  [Network.NETNA]: void 0,
+  [Network.DEVNET]: void 0,
+  [Network.TESTNET]: "https://api.testnet.aptoslabs.com/nocode/v1/public/alias/shelby/testnet/v1/graphql",
+  [Network.MAINNET]: void 0,
+  [Network.LOCAL]: "http://localhost:8091/v1/graphql",
+  [Network.CUSTOM]: void 0
+};
+var NetworkToGasStationBaseUrl = {
+  [Network.SHELBYNET]: "https://api.shelbynet.shelby.xyz/gs/v1",
+  [Network.NETNA]: void 0,
+  [Network.DEVNET]: void 0,
+  [Network.TESTNET]: "https://api.testnet.shelby.xyz/gs/v1",
+  [Network.MAINNET]: void 0,
+  [Network.LOCAL]: void 0,
+  [Network.CUSTOM]: void 0
+};
+
+// src/core/clients/utils.ts
+var getAptosConfig = (config) => {
+  const baseFaucetConfig = config.faucet?.authToken ? { AUTH_TOKEN: config.faucet.authToken } : void 0;
+  if (config.aptos) {
+    return new AptosConfig({
+      // Spread user's aptos config first
+      ...config.aptos,
+      // Network from top-level is authoritative - cannot be overridden
+      network: config.network,
+      // Merge clientConfig with API_KEY default
+      clientConfig: {
+        API_KEY: config.apiKey,
+        ...config.aptos.clientConfig
+      },
+      // Merge faucetConfig: aptos config first, then base authToken (authoritative)
+      faucetConfig: {
+        ...config.aptos.faucetConfig,
+        ...baseFaucetConfig
+      }
+    });
+  }
+  return new AptosConfig({
+    network: config.network,
+    clientConfig: {
+      API_KEY: config.apiKey
+    },
+    faucetConfig: baseFaucetConfig
+  });
+};
+
+// src/core/operations/generated/sdk.ts
+import gql from "graphql-tag";
+var GetBlobsDocument = gql`
+    query getBlobs($where: blobs_bool_exp, $orderBy: [blobs_order_by!], $limit: Int, $offset: Int) {
+  blobs(where: $where, order_by: $orderBy, limit: $limit, offset: $offset) {
+    uid
+    object_name
+    owner
+    blob_commitment
+    created_at
+    expires_at
+    updated_at
+    num_chunksets
+    size
+    slice_address
+    placement_group
+    is_persisted
+    is_committed
+    is_deleted
+  }
+}
+    `;
+var GetBlobActivitiesDocument = gql`
+    query getBlobActivities($where: blob_activities_bool_exp, $orderBy: [blob_activities_order_by!], $limit: Int, $offset: Int) {
+  blob_activities(
+    where: $where
+    order_by: $orderBy
+    limit: $limit
+    offset: $offset
+  ) {
+    uid
+    object_name
+    event_index
+    event_type
+    transaction_hash
+    transaction_version
+    timestamp
+    owner
+  }
+}
+    `;
+var GetBlobsCountDocument = gql`
+    query getBlobsCount($where: blobs_bool_exp) {
+  blobs_aggregate(where: $where) {
+    aggregate {
+      count
+    }
+  }
+}
+    `;
+var GetBlobActivitiesCountDocument = gql`
+    query getBlobActivitiesCount($where: blob_activities_bool_exp) {
+  blob_activities_aggregate(where: $where) {
+    aggregate {
+      count
+    }
+  }
+}
+    `;
+var GetTotalBlobsSizeDocument = gql`
+    query getTotalBlobsSize($where: blobs_bool_exp) {
+  blobs_aggregate(where: $where) {
+    aggregate {
+      sum {
+        size
+      }
+    }
+  }
+}
+    `;
+var GetPlacementGroupSlotsDocument = gql`
+    query getPlacementGroupSlots($where: placement_group_slots_bool_exp, $orderBy: [placement_group_slots_order_by!], $limit: Int, $offset: Int) {
+  placement_group_slots(
+    where: $where
+    order_by: $orderBy
+    limit: $limit
+    offset: $offset
+  ) {
+    placement_group
+    slot_index
+    storage_provider
+    status
+    updated_at
+  }
+}
+    `;
+var GetPlacementGroupSlotsCountDocument = gql`
+    query getPlacementGroupSlotsCount($where: placement_group_slots_bool_exp) {
+  placement_group_slots_aggregate(where: $where) {
+    aggregate {
+      count
+    }
+  }
+}
+    `;
+var GetProcessorStatusDocument = gql`
+    query getProcessorStatus {
+  processor_status {
+    last_success_version
+    last_transaction_timestamp
+    last_updated
+  }
+}
+    `;
+var defaultWrapper = (action, _operationName, _operationType, _variables) => action();
+function getSdk(client, withWrapper = defaultWrapper) {
+  return {
+    getBlobs(variables, requestHeaders, signal) {
+      return withWrapper((wrappedRequestHeaders) => client.request({ document: GetBlobsDocument, variables, requestHeaders: { ...requestHeaders, ...wrappedRequestHeaders }, signal }), "getBlobs", "query", variables);
+    },
+    getBlobActivities(variables, requestHeaders, signal) {
+      return withWrapper((wrappedRequestHeaders) => client.request({ document: GetBlobActivitiesDocument, variables, requestHeaders: { ...requestHeaders, ...wrappedRequestHeaders }, signal }), "getBlobActivities", "query", variables);
+    },
+    getBlobsCount(variables, requestHeaders, signal) {
+      return withWrapper((wrappedRequestHeaders) => client.request({ document: GetBlobsCountDocument, variables, requestHeaders: { ...requestHeaders, ...wrappedRequestHeaders }, signal }), "getBlobsCount", "query", variables);
+    },
+    getBlobActivitiesCount(variables, requestHeaders, signal) {
+      return withWrapper((wrappedRequestHeaders) => client.request({ document: GetBlobActivitiesCountDocument, variables, requestHeaders: { ...requestHeaders, ...wrappedRequestHeaders }, signal }), "getBlobActivitiesCount", "query", variables);
+    },
+    getTotalBlobsSize(variables, requestHeaders, signal) {
+      return withWrapper((wrappedRequestHeaders) => client.request({ document: GetTotalBlobsSizeDocument, variables, requestHeaders: { ...requestHeaders, ...wrappedRequestHeaders }, signal }), "getTotalBlobsSize", "query", variables);
+    },
+    getPlacementGroupSlots(variables, requestHeaders, signal) {
+      return withWrapper((wrappedRequestHeaders) => client.request({ document: GetPlacementGroupSlotsDocument, variables, requestHeaders: { ...requestHeaders, ...wrappedRequestHeaders }, signal }), "getPlacementGroupSlots", "query", variables);
+    },
+    getPlacementGroupSlotsCount(variables, requestHeaders, signal) {
+      return withWrapper((wrappedRequestHeaders) => client.request({ document: GetPlacementGroupSlotsCountDocument, variables, requestHeaders: { ...requestHeaders, ...wrappedRequestHeaders }, signal }), "getPlacementGroupSlotsCount", "query", variables);
+    },
+    getProcessorStatus(variables, requestHeaders, signal) {
+      return withWrapper((wrappedRequestHeaders) => client.request({ document: GetProcessorStatusDocument, variables, requestHeaders: { ...requestHeaders, ...wrappedRequestHeaders }, signal }), "getProcessorStatus", "query", variables);
+    }
+  };
+}
+
+// src/core/operations/index.ts
+function createShelbyIndexerClient(baseUrl, options) {
+  const graphqlClient = new GraphQLClient(baseUrl, options);
+  return getSdk(graphqlClient);
+}
+function getShelbyIndexerClient(config) {
+  const aptosConfig = getAptosConfig(config);
+  let { apiKey: indexerApiKey, baseUrl } = config.indexer ?? {};
+  if (!baseUrl) {
+    switch (aptosConfig?.network) {
+      // TODO: Add endpoints for core networks
+      case Network2.MAINNET:
+      case Network2.TESTNET:
+      case Network2.DEVNET:
+      case Network2.SHELBYNET:
+      case Network2.LOCAL:
+        baseUrl = NetworkToShelbyBlobIndexerBaseUrl[aptosConfig.network];
+        break;
+    }
+  }
+  if (baseUrl === void 0) {
+    throw new Error(
+      "The ShelbyClientConfig does not support the Shelby indexer. Please configure the endpoint in the ShelbyClientConfig.indexer.endpoint or provide a supported Aptos network."
+    );
+  }
+  const apiKey = indexerApiKey ?? config.apiKey;
+  return createShelbyIndexerClient(baseUrl, {
+    headers: {
+      ...apiKey ? { Authorization: `Bearer ${apiKey}` } : {},
+      "x-aptos-client": "shelby-ts-sdk"
+    }
+  });
+}
+
+// src/core/clients/ShelbyPlacementGroupClient.ts
+var ShelbyPlacementGroupClient = class {
+  indexer;
+  /**
+   * Creates a new ShelbyPlacementGroupClient.
+   *
+   * @param config - The client configuration object.
+   *
+   * @example
+   * ```typescript
+   * const pgClient = new ShelbyPlacementGroupClient({
+   *   network: Network.SHELBYNET,
+   * });
+   * ```
+   */
+  constructor(config) {
+    this.indexer = getShelbyIndexerClient(config);
+  }
+  /**
+   * Retrieves placement group slots from the indexer.
+   *
+   * @param params.where (optional) - The where clause to filter slots by.
+   * @param params.pagination (optional) - The pagination options.
+   * @param params.orderBy (optional) - The order by clause to sort slots by.
+   * @returns The placement group slots that match the filter.
+   *
+   * @example
+   * ```typescript
+   * // Get all active slots
+   * const slots = await client.getPlacementGroupSlots({
+   *   where: { status: { _eq: "active" } },
+   * });
+   * ```
+   */
+  async getPlacementGroupSlots(params) {
+    const { limit, offset } = params.pagination ?? {};
+    const { orderBy, where } = params;
+    const { placement_group_slots } = await this.indexer.getPlacementGroupSlots(
+      {
+        where,
+        limit,
+        offset,
+        orderBy
+      }
+    );
+    return placement_group_slots.map(
+      (slot) => ({
+        placementGroup: slot.placement_group,
+        slotIndex: Number(slot.slot_index),
+        storageProvider: slot.storage_provider,
+        status: slot.status,
+        updatedAt: Number(slot.updated_at)
+      })
+    );
+  }
+  /**
+   * Retrieves the total count of placement group slots from the indexer.
+   *
+   * @param params.where (optional) - The where clause to filter slots by.
+   * @returns The count of placement group slots that match the filter.
+   *
+   * @example
+   * ```typescript
+   * // Get count of active slots
+   * const count = await client.getPlacementGroupSlotsCount({
+   *   where: { status: { _eq: "active" } },
+   * });
+   * ```
+   */
+  async getPlacementGroupSlotsCount(params) {
+    const { where } = params;
+    const { placement_group_slots_aggregate } = await this.indexer.getPlacementGroupSlotsCount({ where });
+    return placement_group_slots_aggregate?.aggregate?.count ?? 0;
+  }
+};
 export {
   ShelbyPlacementGroupClient
 };

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

@@ -1,9 +1,12 @@
-import { AccountAddressInput } from '@aptos-labs/ts-sdk';
+import { Account, AccountAddressInput } from '@aptos-labs/ts-sdk';
 import { ShelbyBlob } from '../blobs.js';
-import { BlobName } from '../layout.js';
+import { BlobCommitments } from '../commitments.js';
 import { ShelbyIndexerClient } from '../operations/index.js';
+import { ChallengeResponse } from '../rpc-responses.js';
+import { StorageProviderAck } from '../types/blobs.js';
 import { SenderBuiltMicropayment } from '../types/payments.js';
 import { ShelbyRPCConfig, ShelbyClientConfig } from './ShelbyClientConfig.js';
+import '../layout.js';
 import 'zod';
 import '../../clay-codes-DdXABBDx.js';
 import '@shelby-protocol/clay-codes';
@@ -12,14 +15,57 @@ import '../operations/generated/sdk.js';
 import 'graphql';
 import '../networks.js';
 
+/**
+ * Auth scheme identifier sent in X-Shelby-Auth-Scheme.
+ * - "ed25519": standard Ed25519 account (default when header is absent)
+ * - "derivable": Derived Abstracted Account (Solana, Ethereum, etc.)
+ */
+type AuthScheme = "ed25519" | "derivable";
+interface BlobOwnerAuthBase {
+    challenge: string;
+    signature: Uint8Array;
+    publicKey: Uint8Array;
+}
+interface Ed25519BlobOwnerAuth extends BlobOwnerAuthBase {
+    authScheme?: "ed25519";
+}
+interface DerivableBlobOwnerAuth extends BlobOwnerAuthBase {
+    authScheme: "derivable";
+    /** External identity (e.g. Solana base58 pubkey). */
+    identity: string;
+    /** dApp domain used during key derivation. */
+    domain: string;
+    /** On-chain authentication function (e.g. "0x1::solana_derivable_account::authenticate"). */
+    authFunction: string;
+}
+/**
+ * Authentication credentials for blob owner operations.
+ *
+ * Ed25519 (default): only the base fields are needed.
+ * Derivable: requires identity, domain, and authFunction.
+ */
+type BlobOwnerAuth = Ed25519BlobOwnerAuth | DerivableBlobOwnerAuth;
 type BlobDataSource = Uint8Array | ReadableStream<Uint8Array>;
-type PutBlobProgress = {
-    phase: "uploading" | "finalizing";
-    partIdx: number;
-    totalParts: number;
-    partBytes: number;
+type PutBlobChunksetsProgress = {
+    phase: "uploading";
+    chunksetIdx: number;
+    totalChunksets: number;
+    chunksetBytes: number;
     uploadedBytes: number;
     totalBytes: number;
+    acksReceived?: number;
+    /** SP blob acknowledgements from this chunkset (if any) */
+    spAcks?: StorageProviderAck[];
+};
+/**
+ * Result of putBlobChunksets operation.
+ */
+type PutBlobChunksetsResult = {
+    /**
+     * Aggregated SP blob acknowledgements collected across all chunksets.
+     * Deduplicated by slot (latest signature wins if an SP acks multiple times).
+     */
+    spAcks: StorageProviderAck[];
 };
 declare class ShelbyRPCClient {
     #private;
@@ -33,6 +79,9 @@ declare class ShelbyRPCClient {
      *
      * @param config - The client configuration object.
      * @param config.network - The Shelby network to use.
+     * @param options.signChallengeHandler - Optional override for challenge
+     *   signing. When set, `putBlobChunksets` uses this instead of the built-in
+     *   `signChallenge`. Intended for kit-level overrides (e.g. Solana DAA).
      *
      * @example
      * ```typescript
@@ -42,36 +91,79 @@ declare class ShelbyRPCClient {
      * });
      * ```
      */
-    constructor(config: ShelbyClientConfig);
+    constructor(config: ShelbyClientConfig, options?: {
+        signChallengeHandler?: (account: Account, challenge: string) => BlobOwnerAuth;
+    });
     /**
-     * Uploads blob data to the Shelby RPC node for storage by storage providers.
-     * This method should be called after blob commitments have been registered on the blockchain.
-     * Uses multipart upload for efficient handling of large files.
+     * Request an authentication challenge for the given account.
+     * The challenge must be signed and included in subsequent authenticated requests.
      *
-     * @param params.account - The account that owns the blob.
-     * @param params.blobName - The name/path of the blob (e.g. "folder/file.txt").
+     * @param account - The Aptos account address to authenticate as.
+     * @returns The challenge string and expiration timestamp.
+     *
+     * @example
+     * ```typescript
+     * const { challenge, expiresAt } = await client.getChallenge(account.accountAddress);
+     * const auth = client.signChallenge(account, challenge);
+     * ```
+     */
+    getChallenge(account: AccountAddressInput): Promise<ChallengeResponse>;
+    /**
+     * Sign a challenge using the given account and return auth credentials.
+     *
+     * @param account - The Aptos account to sign with.
+     * @param challenge - The hex-encoded challenge string from getChallenge().
+     * @returns BlobOwnerAuth credentials for authenticated requests.
+     */
+    signChallenge(account: Account, challenge: string): BlobOwnerAuth;
+    /**
+     * Uploads blob data to the Shelby RPC node using the v2 chunkset API.
+     * This method authenticates using challenge-response and uploads chunksets
+     * directly to storage providers via the RPC's worker pool.
+     *
+     * This method:
+     * - Sends raw chunkset data directly to the RPC for erasure encoding
+     * - Requires pre-computed blob commitments to generate inclusion proofs
+     * - Does not support resume (each chunkset is idempotent on the SP side)
+     *
+     * @param params.account - The Aptos Account (with signing capability) that owns the blob.
+     * @param params.uid - The blob's on-chain UID (from `BlobRegisteredEvent` at registration).
      * @param params.blobData - The raw blob data as a Uint8Array or ReadableStream.
+     * @param params.commitments - Pre-computed blob commitments (from generateCommitments).
      * @param params.totalBytes - Total byte length. Required for streams; optional for Uint8Array.
+     * @param params.chunksetConcurrency - Number of chunksets to upload in parallel. Defaults to 4.
+     * @param params.onProgress - Optional callback for upload progress.
+     * @param params.signal - Optional AbortSignal for cancellation. When aborted, in-flight
+     *   HTTP requests are cancelled and an AbortError is thrown.
      *
      * @example
      * ```typescript
-     * const blobData = new TextEncoder().encode("Hello, world!");
+     * // First, generate commitments for the blob
+     * const commitments = await generateCommitments(provider, fileData);
      *
-     * await client.putBlob({
-     *   account: AccountAddress.from("0x1"),
-     *   blobName: "greetings/hello.txt",
-     *   blobData,
+     * // Register the blob on chain, then read its UID from the register tx's
+     * // BlobRegisteredEvent (see ShelbyBlobClient.registeredBlobUids).
+     *
+     * // Upload using chunkset API
+     * await rpcClient.putBlobChunksets({
+     *   account: myAccount,
+     *   uid: blobUid,
+     *   blobData: fileData,
+     *   commitments,
+     *   chunksetConcurrency: 8,
      * });
      * ```
      */
-    putBlob(params: {
-        account: AccountAddressInput;
-        blobName: BlobName;
+    putBlobChunksets(params: {
+        account: Account;
+        uid: bigint;
         blobData: BlobDataSource;
-        /** Required when blobData is a ReadableStream. Inferred from .length for Uint8Array. */
+        commitments: BlobCommitments;
         totalBytes?: number;
-        onProgress?: (progress: PutBlobProgress) => void;
-    }): Promise<void>;
+        chunksetConcurrency?: number;
+        onProgress?: (progress: PutBlobChunksetsProgress) => void;
+        signal?: AbortSignal;
+    }): Promise<PutBlobChunksetsResult>;
     /**
      * Downloads a blob from the Shelby RPC node.
      * Returns a streaming response with validation to ensure data integrity.
@@ -122,4 +214,4 @@ declare class ShelbyRPCClient {
     }): Promise<ShelbyBlob>;
 }
 
-export { type BlobDataSource, type PutBlobProgress, ShelbyRPCClient };
+export { type AuthScheme, type BlobDataSource, type BlobOwnerAuth, type DerivableBlobOwnerAuth, type Ed25519BlobOwnerAuth, type PutBlobChunksetsProgress, type PutBlobChunksetsResult, ShelbyRPCClient };