@shelby-protocol/sdk 0.3.0 → 0.4.0

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

@@ -5,7 +5,7 @@ import { ShelbyNetwork } from '../networks.js';
  * Configuration for the Shelby RPC connection.
  */
 type ShelbyRPCConfig = {
-    /** Base URL of the Shelby RPC node (e.g., "https://api.shelbynet.shelby.xyz/shelby"). */
+    /** Base URL of the Shelby RPC node (e.g., "https://shelby.shelbynet.shelby.xyz/shelby"). */
     baseUrl?: string;
     /** API key for authenticating with the RPC node. */
     apiKey?: string;
@@ -57,6 +57,14 @@ interface ShelbyClientConfig {
      * generated automatically for each transaction.
      */
     orderless?: boolean;
+    /**
+     * Best-effort location (region) hint sent with every blob registration from this client,
+     * typically the location closest to where the client runs. Honored only for accounts in
+     * the default `FollowHint` location-preference mode, and overridden by a per-write
+     * `selectedLocation`. Without a resolvable location (no preference, no selection, no
+     * hint), writes abort on chain.
+     */
+    locationHint?: string;
 }
 
 export type { ShelbyClientConfig, ShelbyIndexerConfig, ShelbyRPCConfig };

package/dist/core/clients/ShelbyClientConfig.mjs

@@ -1 +0,0 @@
-import "../../chunk-Z7RFCADT.mjs";

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

@@ -32,27 +32,41 @@ declare class ShelbyMetadataClient {
      */
     getStorageProviders(): Promise<StorageProviderInfo[]>;
     /**
-     * Retrieves the list of placement group addresses.
+     * Retrieves the names of every activated location (region). Locations that are
+     * registered but not yet brought online are admin-internal and not listed.
      *
+     * @returns The location name list.
+     *
+     * @example
+     * ```typescript
+     * const locations = await client.getLocationNames();
+     * ```
+     */
+    getLocationNames(): Promise<string[]>;
+    /**
+     * Retrieves the list of placement group addresses in a location.
+     *
+     * @param locationName - The location whose placement groups to list.
      * @returns The placement group address list, or an empty array if none exist.
      *
      * @example
      * ```typescript
-     * const pgList = await client.getPlacementGroupAddresses();
+     * const pgList = await client.getPlacementGroupAddresses("us-east-1");
      * ```
      */
-    getPlacementGroupAddresses(): Promise<AccountAddress[]>;
+    getPlacementGroupAddresses(locationName: string): Promise<AccountAddress[]>;
     /**
-     * Retrieves the list of slice addresses.
+     * Retrieves the list of slice addresses in a location.
      *
+     * @param locationName - The location whose slices to list.
      * @returns The slice group list, or an empty array if none exist.
      *
      * @example
      * ```typescript
-     * const pgList = await client.getSliceAddresses();
+     * const pgList = await client.getSliceAddresses("us-east-1");
      * ```
      */
-    getSliceAddresses(): Promise<AccountAddress[]>;
+    getSliceAddresses(locationName: string): Promise<AccountAddress[]>;
     /**
      * Gets the placement group address for a slice.
      *

package/dist/core/clients/ShelbyMetadataClient.mjs

@@ -1,10 +1,392 @@
+// src/core/clients/ShelbyMetadataClient.ts
 import {
-  ShelbyMetadataClient
-} from "../../chunk-6FJNAUU5.mjs";
-import "../../chunk-V4B3GAMQ.mjs";
-import "../../chunk-UEZNZBJO.mjs";
-import "../../chunk-MNCQBEMS.mjs";
-import "../../chunk-7P6ASYW6.mjs";
+  AccountAddress as AccountAddress2,
+  Aptos,
+  Hex as Hex2
+} 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
+};
+var SHELBY_DEPLOYER = "0x85fdb9a176ab8ef1d9d9c1b60d60b3924f0800ac1de1cc2085fb0b8bb4988e6a";
+
+// src/core/types/storage_providers.ts
+var ACTIVE_PROVIDER_CONDITIONS = [
+  "Normal",
+  "Faulty",
+  "Leaving",
+  "Evicted",
+  "PendingLeaving"
+];
+function isActiveProviderCondition(value) {
+  return typeof value === "string" && ACTIVE_PROVIDER_CONDITIONS.includes(value);
+}
+
+// src/core/utils.ts
+import {
+  AccountAddress,
+  Hex
+} from "@aptos-labs/ts-sdk";
+function normalizeAddress(address) {
+  return AccountAddress.from(address, { maxMissingChars: 63 });
+}
+
+// src/core/clients/utils.ts
+import { AptosConfig } from "@aptos-labs/ts-sdk";
+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/clients/ShelbyMetadataClient.ts
+function parseActiveProviderCondition(raw) {
+  const variant = raw?.__variant__;
+  if (!isActiveProviderCondition(variant)) {
+    throw new Error(
+      `Unknown ActiveProviderCondition variant: ${JSON.stringify(raw)}`
+    );
+  }
+  return variant;
+}
+function parseStorageProviderState(raw) {
+  switch (raw.__variant__) {
+    case "Active":
+      return {
+        variant: "Active",
+        quota: raw.quota.value,
+        stakeAtStartOfStakingEpoch: raw.stake_at_start_of_staking_epoch,
+        condition: parseActiveProviderCondition(raw.condition)
+      };
+    case "Waitlisted":
+      return {
+        variant: "Waitlisted"
+      };
+    case "Frozen":
+      return {
+        variant: "Frozen",
+        frozenReason: raw.frozen_reason,
+        frozenFrom: raw.frozen_from,
+        frozenTill: raw.frozen_till
+      };
+    default:
+      throw new Error(
+        `Unknown StorageProviderStateDetails variant: ${JSON.stringify(raw)}`
+      );
+  }
+}
+var ShelbyMetadataClient = class {
+  aptos;
+  deployer;
+  /**
+   * The ShelbyMetadataClient is used to interact with the Shelby contract on the Aptos blockchain. This
+   * includes functions like gathering basic details about the Shelby system, including storage provider information.
+   *
+   * @param config.aptos.config - The Aptos config.
+   * @param config.shelbyDeployer - The deployer account address of the Shelby contract. If not provided, the default deployer address will be used.
+   *
+   * @example
+   * ```typescript
+   * const aptos = new Aptos(new AptosConfig({ network: Network.TESTNET }));
+   * const metadataClient = new ShelbyMetadataClient({ aptos });
+   * ```
+   */
+  constructor(config) {
+    this.aptos = new Aptos(getAptosConfig(config));
+    this.deployer = config.deployer ?? AccountAddress2.fromString(SHELBY_DEPLOYER);
+  }
+  /**
+   * Retrieves storage provider list from the blockchain.
+   *
+   * @returns A list of storage providers, or empty array if none exist.
+   *
+   * @example
+   * ```typescript
+   * const spList = await client.getStorageProviders();
+   * ```
+   */
+  async getStorageProviders() {
+    try {
+      const rawMetadata = await this.aptos.view({
+        payload: {
+          function: `${this.deployer.toString()}::storage_provider_registry::get_all_storage_providers`,
+          functionArguments: []
+        }
+      });
+      const metadata = rawMetadata[0];
+      return metadata.map((provider) => ({
+        address: normalizeAddress(provider.address),
+        ipAddress: provider.ip_address,
+        port: provider.port,
+        blsPublicKey: Hex2.fromHexInput(provider.bls_public_key).toUint8Array(),
+        availabilityZone: provider.availability_zone,
+        state: parseStorageProviderState(provider.state)
+      }));
+    } catch (error) {
+      if (error instanceof Error && // Depending on the network, the error message may show up differently.
+      error.message?.includes("sub_status: Some(404)")) {
+        return [];
+      }
+      throw error;
+    }
+  }
+  /**
+   * Retrieves the names of every activated location (region). Locations that are
+   * registered but not yet brought online are admin-internal and not listed.
+   *
+   * @returns The location name list.
+   *
+   * @example
+   * ```typescript
+   * const locations = await client.getLocationNames();
+   * ```
+   */
+  async getLocationNames() {
+    const names = await this.aptos.view({
+      payload: {
+        function: `${this.deployer.toString()}::location::activated_location_names`,
+        functionArguments: []
+      }
+    });
+    return names[0];
+  }
+  /**
+   * Retrieves the list of placement group addresses in a location.
+   *
+   * @param locationName - The location whose placement groups to list.
+   * @returns The placement group address list, or an empty array if none exist.
+   *
+   * @example
+   * ```typescript
+   * const pgList = await client.getPlacementGroupAddresses("us-east-1");
+   * ```
+   */
+  async getPlacementGroupAddresses(locationName) {
+    try {
+      const pgSizeMetadata = await this.aptos.view({
+        payload: {
+          function: `${this.deployer.toString()}::placement_group_registry::get_number_of_placement_groups`,
+          functionArguments: [locationName]
+        }
+      });
+      if (Number(pgSizeMetadata[0]) === 0) {
+        return [];
+      }
+      const finalPlacementGroupIndex = pgSizeMetadata[0] - 1;
+      const addressMetadataArray = await this.aptos.view({
+        payload: {
+          function: `${this.deployer.toString()}::placement_group_registry::get_placement_group_addresses`,
+          functionArguments: [locationName, 0, finalPlacementGroupIndex]
+        }
+      });
+      const metadata = addressMetadataArray[0];
+      return metadata.map((pg) => normalizeAddress(pg));
+    } catch (error) {
+      if (error instanceof Error && // Depending on the network, the error message may show up differently.
+      (error.message?.includes("sub_status: Some(404)") || error.message?.includes("E_PLACEMENT_GROUP_NOT_FOUND"))) {
+        return [];
+      }
+      throw error;
+    }
+  }
+  /**
+   * Retrieves the list of slice addresses in a location.
+   *
+   * @param locationName - The location whose slices to list.
+   * @returns The slice group list, or an empty array if none exist.
+   *
+   * @example
+   * ```typescript
+   * const pgList = await client.getSliceAddresses("us-east-1");
+   * ```
+   */
+  async getSliceAddresses(locationName) {
+    try {
+      const sliceSizeMetadata = await this.aptos.view({
+        payload: {
+          function: `${this.deployer.toString()}::slice_registry::get_number_of_slices`,
+          functionArguments: [locationName]
+        }
+      });
+      if (Number(sliceSizeMetadata[0]) === 0) {
+        return [];
+      }
+      const finalSliceIndex = sliceSizeMetadata[0] - 1;
+      const addressMetadataArray = await this.aptos.view({
+        payload: {
+          function: `${this.deployer.toString()}::slice_registry::get_slice_addresses`,
+          functionArguments: [locationName, 0, finalSliceIndex]
+        }
+      });
+      const metadata = addressMetadataArray[0];
+      return metadata.map((slice) => normalizeAddress(slice));
+    } catch (error) {
+      if (error instanceof Error && // Depending on the network, the error message may show up differently.
+      (error.message?.includes("sub_status: Some(404)") || error.message?.includes("E_SLICE_NOT_FOUND"))) {
+        return [];
+      }
+      throw error;
+    }
+  }
+  /**
+   * Gets the placement group address for a slice.
+   *
+   * @param sliceAddress - The address of the slice account.
+   * @returns The placement group address as a string.
+   */
+  async getPlacementGroupAddressForSlice(sliceAddress) {
+    const sliceMetadata = await this.aptos.view({
+      payload: {
+        function: `${this.deployer.toString()}::slice::get_slice_info`,
+        functionArguments: [sliceAddress.toString()]
+      }
+    });
+    return sliceMetadata[0].placement_group_assignments[0].placement_group_address;
+  }
+  /**
+   * Retrieves the designated storage providers for a slice.
+   *
+   * Designated SPs are those appointed to store data for their slots:
+   * - Active: Currently serving data
+   * - Receiving: Receiving data during slot transfer
+   * - Repairing: Repairing data after crash or failed transfer
+   * - Reconstructing: Reconstructing data if the repair fails
+   *
+   * @param params.account - The address of the slice account.
+   * @returns An array where result[i] is the designated SP for slot i, or null if no SP is designated.
+   *
+   * @example
+   * ```typescript
+   * const providers = await client.getDesignatedStorageProvidersForSlice({ account: sliceAddress });
+   * ```
+   */
+  async getDesignatedStorageProvidersForSlice(params) {
+    const placementGroupAddress = await this.getPlacementGroupAddressForSlice(
+      params.account
+    );
+    const rawMetadata = await this.aptos.view({
+      payload: {
+        function: `${this.deployer.toString()}::placement_group::get_designated_storage_providers`,
+        functionArguments: [placementGroupAddress]
+      }
+    });
+    const providers = rawMetadata[0];
+    return providers.map(
+      (opt) => opt.vec.length > 0 ? normalizeAddress(opt.vec[0]) : null
+    );
+  }
+  /**
+   * Retrieves the active storage providers for a slice.
+   *
+   * Active SPs have a complete copy of the data for the slot, and are not in any data transfer/repair/reconstruction phase.
+   * Active SP can be audited for the data it contains.
+   * Each slot has at most one active SP.
+   *
+   * @param params.account - The address of the slice account.
+   * @returns An array where result[i] is the active SP for slot i, or null if no SP is active.
+   *
+   * @example
+   * ```typescript
+   * const providers = await client.getActiveStorageProvidersForSlice({ account: sliceAddress });
+   * ```
+   */
+  async getActiveStorageProvidersForSlice(params) {
+    const placementGroupAddress = await this.getPlacementGroupAddressForSlice(
+      params.account
+    );
+    const rawMetadata = await this.aptos.view({
+      payload: {
+        function: `${this.deployer.toString()}::placement_group::get_active_storage_providers`,
+        functionArguments: [placementGroupAddress]
+      }
+    });
+    const providers = rawMetadata[0];
+    return providers.map(
+      (opt) => opt.vec.length > 0 ? normalizeAddress(opt.vec[0]) : null
+    );
+  }
+  /**
+   * Retrieves the serving storage providers for a slice.
+   *
+   * Serving SPs are those that can respond to read requests. The serving logic is:
+   * - If an Active SP exists for a slot: Only the Active SP is serving
+   * - If no Active SP (transition in progress): Both Designated and Vacating SPs serve
+   *
+   * Each slot may have multiple serving SPs during transitions.
+   *
+   * @param params.account - The address of the slice account.
+   * @returns An array where result[i] contains the serving SPs for slot i.
+   *
+   * @example
+   * ```typescript
+   * const providers = await client.getServingStorageProvidersForSlice({ account: sliceAddress });
+   * ```
+   */
+  async getServingStorageProvidersForSlice(params) {
+    const placementGroupAddress = await this.getPlacementGroupAddressForSlice(
+      params.account
+    );
+    const rawMetadata = await this.aptos.view({
+      payload: {
+        function: `${this.deployer.toString()}::placement_group::get_serving_storage_providers`,
+        functionArguments: [placementGroupAddress]
+      }
+    });
+    const providers = rawMetadata[0];
+    return providers.map(
+      (slotProviders) => slotProviders.map((addr) => normalizeAddress(addr))
+    );
+  }
+};
 export {
   ShelbyMetadataClient
 };

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

@@ -81,7 +81,7 @@ declare class ShelbyMicropaymentChannelClient {
     createChannel(params: {
         sender: Account;
         receiver: AccountAddress;
-        expirationMicros: number;
+        expirationMicros: number | bigint;
         depositAmount: number;
         fungibleAssetAddress: AccountAddress;
         publicKey?: Uint8Array;
@@ -106,7 +106,7 @@ declare class ShelbyMicropaymentChannelClient {
     static makeCreateMicropaymentChannelPayload(params: {
         deployer?: AccountAddress;
         receiver: AccountAddress;
-        expirationMicros: number;
+        expirationMicros: number | bigint;
         depositAmount: number;
         fungibleAssetAddress: AccountAddress;
         publicKey: Uint8Array;
@@ -183,9 +183,9 @@ declare class ShelbyMicropaymentChannelClient {
         sender: Account;
         receiver: AccountAddress;
         fungibleAssetAddress: AccountAddress;
-        amount: number;
-        paymentChannelId: number;
-        sequenceNumber: number;
+        amount: number | bigint;
+        paymentChannelId: number | bigint;
+        sequenceNumber: number | bigint;
     }): SenderBuiltMicropayment;
     /**
      * Creates a static payload for the receiver_withdraw Move function.
@@ -260,7 +260,7 @@ declare class ShelbyMicropaymentChannelClient {
         sender: Account;
         receiver: AccountAddress;
         fungibleAssetAddress: AccountAddress;
-        newExpirationMicros: number;
+        newExpirationMicros: number | bigint;
         options?: InputGenerateTransactionOptions;
     }): Promise<{
         transaction: PendingTransactionResponse;
@@ -280,7 +280,7 @@ declare class ShelbyMicropaymentChannelClient {
         deployer?: AccountAddress;
         receiver: AccountAddress;
         fungibleAssetAddress: AccountAddress;
-        newExpirationMicros: number;
+        newExpirationMicros: number | bigint;
     }): InputGenerateTransactionPayloadData;
     /**
      * Increases the deposit amount locked in a micropayment channel.