@shelby-protocol/sdk 0.2.0 → 0.2.1

package/dist/chunk-KTVNKLBT.mjs

@@ -0,0 +1,207 @@
+import {
+  MICROPAYMENTS_DEPLOYER
+} from "./chunk-4ZOFT75Q.mjs";
+
+// src/core/types/payments.ts
+import {
+  AccountAddress,
+  Deserializer,
+  Hex,
+  Serializer
+} from "@aptos-labs/ts-sdk";
+var MICROPAYMENTS_MODULE_NAME = "micropayments";
+var WITHDRAW_APPROVAL_STRUCT_NAME = "WithdrawApproval";
+function serializeTypeInfo(serializer, moduleAddress, moduleName, structName) {
+  moduleAddress.serialize(serializer);
+  const moduleNameBytes = new TextEncoder().encode(moduleName);
+  serializer.serializeBytes(moduleNameBytes);
+  const structNameBytes = new TextEncoder().encode(structName);
+  serializer.serializeBytes(structNameBytes);
+}
+var StaleChannelStateError = class _StaleChannelStateError extends Error {
+  /**
+   * The last valid micropayment stored by the server.
+   * Clients can use this to reset their local channel state.
+   */
+  storedMicropayment;
+  constructor(storedMicropayment, message) {
+    super(
+      message ?? "Client has stale channel state. Use the returned micropayment to reset local state."
+    );
+    this.name = "StaleChannelStateError";
+    this.storedMicropayment = storedMicropayment;
+  }
+  /**
+   * Returns the stored micropayment as a base64-encoded string.
+   */
+  toBase64() {
+    const bytes = this.storedMicropayment.bcsToBytes();
+    const binaryString = Array.from(
+      bytes,
+      (byte) => String.fromCharCode(byte)
+    ).join("");
+    return btoa(binaryString);
+  }
+  /**
+   * Creates a StaleChannelStateError from a base64-encoded micropayment string.
+   */
+  static fromBase64(base64, message) {
+    const binaryString = atob(base64);
+    const bytes = Uint8Array.from(binaryString, (char) => char.charCodeAt(0));
+    const micropayment = SenderBuiltMicropayment.deserialize(bytes);
+    return new _StaleChannelStateError(micropayment, message);
+  }
+};
+var SenderBuiltMicropayment = class _SenderBuiltMicropayment {
+  /**
+   * The sender's address (owner of the payment channel).
+   */
+  sender;
+  /**
+   * The receiver's address (beneficiary of the withdrawal).
+   */
+  receiver;
+  /**
+   * The unique ID of the payment channel.
+   */
+  paymentChannelId;
+  /**
+   * The cumulative amount the receiver is authorized to withdraw.
+   */
+  amount;
+  /**
+   * The fungible asset metadata address.
+   */
+  fungibleAssetAddress;
+  /**
+   * Monotonically increasing sequence number for replay protection.
+   */
+  sequenceNumber;
+  /**
+   * The sender's Ed25519 public key (32 bytes).
+   * Used by the receiver to verify the signature before submitting.
+   */
+  publicKey;
+  /**
+   * The Ed25519 signature of the SignedMessage<WithdrawApproval> struct.
+   * The SignedMessage includes TypeInfo for domain separation.
+   */
+  signature;
+  /**
+   * The deployer address of the micropayments module.
+   * This is needed to reconstruct the TypeInfo for signature verification.
+   */
+  deployer;
+  constructor(sender, receiver, paymentChannelId, amount, fungibleAssetAddress, sequenceNumber, publicKey, signature, deployer) {
+    this.sender = sender;
+    this.receiver = receiver;
+    this.paymentChannelId = paymentChannelId;
+    this.amount = amount;
+    this.fungibleAssetAddress = fungibleAssetAddress;
+    this.sequenceNumber = sequenceNumber;
+    this.publicKey = publicKey;
+    this.signature = signature;
+    this.deployer = deployer ?? AccountAddress.fromString(MICROPAYMENTS_DEPLOYER);
+  }
+  /**
+   * Creates the BCS-serialized message that was signed.
+   * This is a SignedMessage<WithdrawApproval> which includes:
+   * 1. TypeInfo (module_address, module_name, struct_name)
+   * 2. WithdrawApproval struct fields
+   *
+   * This format is used with signature_verify_strict_t for domain separation.
+   */
+  getSignedMessage() {
+    return _SenderBuiltMicropayment.buildSignedMessage({
+      deployer: this.deployer,
+      sender: this.sender,
+      receiver: this.receiver,
+      fungibleAssetAddress: this.fungibleAssetAddress,
+      amount: this.amount,
+      paymentChannelId: this.paymentChannelId,
+      sequenceNumber: this.sequenceNumber
+    });
+  }
+  /**
+   * Static helper to build the SignedMessage<WithdrawApproval> bytes from raw parameters.
+   * This can be used to create the message for signing without constructing the full object.
+   *
+   * @param params - The withdrawal approval parameters.
+   * @returns The BCS-serialized SignedMessage<WithdrawApproval> bytes.
+   */
+  static buildSignedMessage(params) {
+    const serializer = new Serializer();
+    serializeTypeInfo(
+      serializer,
+      params.deployer,
+      MICROPAYMENTS_MODULE_NAME,
+      WITHDRAW_APPROVAL_STRUCT_NAME
+    );
+    params.sender.serialize(serializer);
+    params.receiver.serialize(serializer);
+    params.fungibleAssetAddress.serialize(serializer);
+    serializer.serializeU64(params.amount);
+    serializer.serializeU64(params.paymentChannelId);
+    serializer.serializeU64(params.sequenceNumber);
+    return serializer.toUint8Array();
+  }
+  serialize(serializer) {
+    this.sender.serialize(serializer);
+    this.receiver.serialize(serializer);
+    this.fungibleAssetAddress.serialize(serializer);
+    serializer.serializeU64(this.amount);
+    serializer.serializeU64(this.paymentChannelId);
+    serializer.serializeU64(this.sequenceNumber);
+    serializer.serializeBytes(this.publicKey);
+    serializer.serializeBytes(this.signature);
+    this.deployer.serialize(serializer);
+  }
+  bcsToBytes() {
+    const serializer = new Serializer();
+    this.serialize(serializer);
+    return serializer.toUint8Array();
+  }
+  bcsToHex() {
+    return Hex.fromHexInput(this.bcsToBytes());
+  }
+  toStringWithoutPrefix() {
+    return this.bcsToHex().toStringWithoutPrefix();
+  }
+  toString() {
+    return this.bcsToHex().toString();
+  }
+  /**
+   * Deserializes a SenderBuiltMicropayment from BCS bytes.
+   * @param bytes - The bytes to deserialize from (Uint8Array or hex string).
+   * @returns A new SenderBuiltMicropayment instance.
+   */
+  static deserialize(bytes) {
+    const bytesArray = typeof bytes === "string" ? Hex.fromHexInput(bytes).toUint8Array() : bytes;
+    const deserializer = new Deserializer(bytesArray);
+    const sender = AccountAddress.deserialize(deserializer);
+    const receiver = AccountAddress.deserialize(deserializer);
+    const fungibleAssetAddress = AccountAddress.deserialize(deserializer);
+    const amount = deserializer.deserializeU64();
+    const paymentChannelId = deserializer.deserializeU64();
+    const sequenceNumber = deserializer.deserializeU64();
+    const publicKey = deserializer.deserializeBytes();
+    const signature = deserializer.deserializeBytes();
+    const deployer = AccountAddress.deserialize(deserializer);
+    return new _SenderBuiltMicropayment(
+      sender,
+      receiver,
+      paymentChannelId,
+      amount,
+      fungibleAssetAddress,
+      sequenceNumber,
+      publicKey,
+      signature,
+      deployer
+    );
+  }
+};
+
+export {
+  StaleChannelStateError,
+  SenderBuiltMicropayment
+};

package/dist/{chunk-E5QCRTBU.mjs → chunk-OQNP5QXH.mjs}

@@ -1,12 +1,15 @@
 import {
   SenderBuiltMicropayment
-} from "./chunk-4MG4XGY4.mjs";
+} from "./chunk-KTVNKLBT.mjs";
 import {
   getShelbyIndexerClient
 } from "./chunk-CGYJLKBU.mjs";
 import {
   getAptosConfig
 } from "./chunk-AABBONAF.mjs";
+import {
+  normalizeAddress
+} from "./chunk-UEZNZBJO.mjs";
 import {
   MICROPAYMENTS_DEPLOYER
 } from "./chunk-4ZOFT75Q.mjs";
@@ -14,7 +17,8 @@ import {
 // src/core/clients/ShelbyMicropaymentChannelClient.ts
 import {
   AccountAddress,
-  Aptos
+  Aptos,
+  MoveVector
 } from "@aptos-labs/ts-sdk";
 var ShelbyMicropaymentChannelClient = class _ShelbyMicropaymentChannelClient {
   aptos;
@@ -110,7 +114,8 @@ var ShelbyMicropaymentChannelClient = class _ShelbyMicropaymentChannelClient {
           receiver: params.receiver,
           expirationMicros: params.expirationMicros,
           depositAmount: params.depositAmount,
-          fungibleAssetAddress: params.fungibleAssetAddress
+          fungibleAssetAddress: params.fungibleAssetAddress,
+          publicKey: params.publicKey ?? params.sender.publicKey.toUint8Array()
         }
       ),
       sender: params.sender.accountAddress
@@ -132,6 +137,7 @@ var ShelbyMicropaymentChannelClient = class _ShelbyMicropaymentChannelClient {
    * @param params.expirationMicros - The expiration of the micropayment channel.
    * @param params.depositAmount - The amount of the asset locked to the channel.
    * @param params.fungibleAssetAddress - The account address of the fungible asset.
+   * @param params.publicKey - The Ed25519 public key bytes for the channel.
    *
    * @returns An Aptos transaction payload data object for the create_channel Move function.
    */
@@ -142,7 +148,8 @@ var ShelbyMicropaymentChannelClient = class _ShelbyMicropaymentChannelClient {
         params.receiver,
         params.expirationMicros,
         params.depositAmount,
-        params.fungibleAssetAddress
+        params.fungibleAssetAddress,
+        MoveVector.U8(params.publicKey)
       ]
     };
   }
@@ -200,94 +207,86 @@ var ShelbyMicropaymentChannelClient = class _ShelbyMicropaymentChannelClient {
   }
   /**
    * Creates a micropayment that can be sent to a receiver.
+   * The sender signs a WithdrawApproval message that authorizes the receiver
+   * to withdraw funds from the micropayment channel.
    *
-   * @param params.sender - The account address of the sender.
-   * @param params.receiver - The account that is withdrawing funds.
-   * @param params.amount - The amount to withdraw into the receiver's account.
-   * @param params.paymentChannelId - The id of the payment channel.
-   * @param params.sequenceNumber - The sequence number of the micropayment. These must be increasing to be able to store on chain.
+   * @param params.sender - The account that owns the payment channel and signs the approval.
+   * @param params.receiver - The account address that will receive funds.
    * @param params.fungibleAssetAddress - The account address of the fungible asset.
-   * @param params.options - Optional transaction generation options.
+   * @param params.amount - The cumulative amount to authorize (not incremental).
+   * @param params.paymentChannelId - The id of the payment channel.
+   * @param params.sequenceNumber - The sequence number of the micropayment. Must be >= channel's next_withdrawn_sequence_number.
    *
-   * @returns An object containing the pending transaction and signature.
+   * @returns A SenderBuiltMicropayment containing the signed approval.
    *
    * @example
    * ```typescript
-   * const senderBuiltMicropayment = await client.createMicropayment({
-   *   sender: senderAddress,
-   *   receiver: receiver,
-   *   amount: 1,
-   *   paymentChannelId: channelIdFromLookup,
-   *   sequenceNumber: localSequenceNumber,
+   * const senderBuiltMicropayment = client.createMicropayment({
+   *   sender: senderAccount,
+   *   receiver: receiverAddress,
    *   fungibleAssetAddress: fungibleAssetAddress,
+   *   amount: 100,
+   *   paymentChannelId: channelId,
+   *   sequenceNumber: 1,
    * });
    * ```
    */
-  async createMicropayment(params) {
-    const replayProtectionNonce = params.options?.replayProtectionNonce ?? Math.floor(Math.random() * 2 ** 24);
-    const {
-      accountSequenceNumber: _unusedSequenceNumber,
-      expireTimestamp: _unusedTimestamp,
-      ...restOptions
-    } = params.options ?? {};
-    const micropayment = await this.aptos.transaction.build.multiAgent({
-      options: {
-        ...restOptions,
-        replayProtectionNonce,
-        expireTimestamp: Math.floor(Date.now() / 1e3 + 60)
-        // 60 seconds from now
-      },
-      withFeePayer: true,
-      data: _ShelbyMicropaymentChannelClient.createMicropaymentTransactionPayload(
-        {
-          deployer: this.deployer,
-          amount: params.amount,
-          paymentChannelId: params.paymentChannelId,
-          sequenceNumber: params.sequenceNumber,
-          fungibleAssetAddress: params.fungibleAssetAddress
-        }
-      ),
+  createMicropayment(params) {
+    const message = SenderBuiltMicropayment.buildSignedMessage({
+      deployer: this.deployer,
       sender: params.sender.accountAddress,
-      secondarySignerAddresses: [params.receiver]
+      receiver: params.receiver,
+      fungibleAssetAddress: params.fungibleAssetAddress,
+      amount: params.amount,
+      paymentChannelId: params.paymentChannelId,
+      sequenceNumber: params.sequenceNumber
     });
+    const signature = params.sender.sign(message);
     return new SenderBuiltMicropayment(
-      micropayment,
-      this.aptos.sign({
-        signer: params.sender,
-        transaction: micropayment
-      })
+      params.sender.accountAddress,
+      params.receiver,
+      BigInt(params.paymentChannelId),
+      BigInt(params.amount),
+      params.fungibleAssetAddress,
+      BigInt(params.sequenceNumber),
+      params.sender.publicKey.toUint8Array(),
+      signature.toUint8Array(),
+      this.deployer
     );
   }
   /**
-   * Creates a static payload for the receiver_withdraw Move function. This is what
-   * constitutes a miropaymet.
-   * This is a helper method for constructing the transaction payload without signing.
+   * Creates a static payload for the receiver_withdraw Move function.
+   * This is a helper method for constructing the transaction payload.
    *
    * @param params.deployer - Optional deployer account address. Defaults to MICROPAYMENTS_DEPLOYER.
-   * @param params.amount - The amount of the fungible asset's smallest increment to send.
-   * @param params.paymentChannelId - The payment channel id.
+   * @param params.sender - The sender's account address.
    * @param params.fungibleAssetAddress - The account address of the fungible asset.
+   * @param params.amount - The cumulative amount authorized to withdraw.
+   * @param params.paymentChannelId - The payment channel id.
+   * @param params.sequenceNumber - The sequence number for this withdrawal.
+   * @param params.signature - The Ed25519 signature bytes.
    *
-   * @returns An Aptos transaction payload data object for the sender_withdraw Move function.
+   * @returns An Aptos transaction payload data object for the receiver_withdraw Move function.
    */
   static createMicropaymentTransactionPayload(params) {
     return {
       function: `${(params.deployer ?? MICROPAYMENTS_DEPLOYER).toString()}::micropayments::receiver_withdraw`,
       functionArguments: [
+        params.sender,
+        params.fungibleAssetAddress,
         params.amount,
         params.paymentChannelId,
         params.sequenceNumber,
-        params.fungibleAssetAddress
+        MoveVector.U8(params.signature)
       ]
     };
   }
   /**
-   * Withdraws funds from a micropayment channel as the receiver. The receiver
-   * does this by signing and submitting a signed transaction the sender sent it.
+   * Withdraws funds from a micropayment channel as the receiver.
+   * The receiver submits the sender's signed approval to claim funds.
    *
-   * @param params.receiver - The receiver withdrawing funds.
-   * @param params.receiverSignature - The fee-paying transaction signature.
-   * @param params.micropayment - The fee-paying transaction signature.
+   * @param params.receiver - The receiver account that will sign and submit the transaction.
+   * @param params.micropayment - The sender's signed micropayment approval.
    * @param params.options - Optional transaction generation options.
    *
    * @returns An object containing the pending transaction.
@@ -295,23 +294,31 @@ var ShelbyMicropaymentChannelClient = class _ShelbyMicropaymentChannelClient {
    * @example
    * ```typescript
    * const { transaction } = await client.receiverWithdraw({
-   *   receiver: receiver,
-   *   micropayment,
-   *   senderSignature,
+   *   receiver: receiverAccount,
+   *   micropayment: senderBuiltMicropayment,
    * });
    * ```
    */
   async receiverWithdraw(params) {
-    const mySignature = this.aptos.signAsFeePayer({
-      signer: params.receiver,
-      transaction: params.micropayment.micropayment
+    const transaction = await this.aptos.transaction.build.simple({
+      options: params.options,
+      data: _ShelbyMicropaymentChannelClient.createMicropaymentTransactionPayload(
+        {
+          deployer: this.deployer,
+          sender: params.micropayment.sender,
+          fungibleAssetAddress: params.micropayment.fungibleAssetAddress,
+          amount: params.micropayment.amount,
+          paymentChannelId: params.micropayment.paymentChannelId,
+          sequenceNumber: params.micropayment.sequenceNumber,
+          signature: params.micropayment.signature
+        }
+      ),
+      sender: params.receiver.accountAddress
     });
     return {
-      transaction: await this.aptos.transaction.submit.multiAgent({
-        transaction: params.micropayment.micropayment,
-        senderAuthenticator: params.micropayment.senderSignature,
-        additionalSignersAuthenticators: [mySignature],
-        feePayerAuthenticator: mySignature
+      transaction: await this.aptos.signAndSubmitTransaction({
+        signer: params.receiver,
+        transaction
       })
     };
   }
@@ -447,7 +454,7 @@ var ShelbyMicropaymentChannelClient = class _ShelbyMicropaymentChannelClient {
    * ```typescript
    * const channelInfoVec = await client.getChannelInfo({
    *   sender: AccountAddress.fromString("0x1"),
-   *   receiver: AccountAddress.fromSTring("0x2"),
+   *   receiver: AccountAddress.fromString("0x2"),
    * });
    * ```
    */
@@ -466,10 +473,14 @@ var ShelbyMicropaymentChannelClient = class _ShelbyMicropaymentChannelClient {
     const channelInfoArray = rawArray[0];
     return channelInfoArray.map(
       (channelInfo) => {
+        const publicKeyHex = channelInfo.public_key.startsWith("0x") ? channelInfo.public_key.slice(2) : channelInfo.public_key;
+        const publicKey = new Uint8Array(
+          publicKeyHex.match(/.{1,2}/g)?.map((byte) => Number.parseInt(byte, 16)) ?? []
+        );
         return {
           sender: params.sender,
           receiver: params.receiver,
-          fungibleAssetAddress: AccountAddress.fromString(
+          fungibleAssetAddress: normalizeAddress(
             channelInfo.asset_metadata.inner
           ),
           balance: Number(channelInfo.balance),
@@ -481,7 +492,8 @@ var ShelbyMicropaymentChannelClient = class _ShelbyMicropaymentChannelClient {
           paymentChannelId: Number(channelInfo.payment_channel_id),
           receiverWithdrawnAmount: Number(
             channelInfo.receiver_withdrawn_amount
-          )
+          ),
+          publicKey
         };
       }
     );

package/dist/{chunk-4JZO2D7T.mjs → chunk-UEZNZBJO.mjs}

@@ -1,5 +1,8 @@
 // src/core/utils.ts
-import { Hex } from "@aptos-labs/ts-sdk";
+import {
+  AccountAddress,
+  Hex
+} from "@aptos-labs/ts-sdk";
 async function* readInChunks(input, chunkSize) {
   let idx = 0;
   if (isReadableStream(input)) {
@@ -87,11 +90,15 @@ function getBlobNameSuffix(blobName) {
   const parts = blobName.split("/");
   return parts.slice(1).join("/") || "";
 }
+function normalizeAddress(address) {
+  return AccountAddress.from(address, { maxMissingChars: 63 });
+}
 
 export {
   readInChunks,
   zeroPadBytes,
   concatHashes,
   buildRequestUrl,
-  getBlobNameSuffix
+  getBlobNameSuffix,
+  normalizeAddress
 };

package/dist/core/blobs.mjs

@@ -1,6 +1,7 @@
 import {
   createBlobKey
-} from "../chunk-OTBLZL2S.mjs";
+} from "../chunk-3NRBHSMQ.mjs";
+import "../chunk-UEZNZBJO.mjs";
 import "../chunk-7P6ASYW6.mjs";
 export {
   createBlobKey

package/dist/core/clients/ShelbyBlobClient.mjs

@@ -1,17 +1,17 @@
 import {
   MissingTransactionSubmitterError,
   ShelbyBlobClient
-} from "../../chunk-SRV4YWFH.mjs";
+} from "../../chunk-IBAUPQOF.mjs";
 import "../../chunk-XNEIWM4O.mjs";
+import "../../chunk-NHWWORCH.mjs";
 import "../../chunk-HPPMI7DC.mjs";
 import "../../chunk-OGKZ575S.mjs";
-import "../../chunk-NHWWORCH.mjs";
 import "../../chunk-CGYJLKBU.mjs";
 import "../../chunk-KJ24NKPH.mjs";
 import "../../chunk-AABBONAF.mjs";
-import "../../chunk-OTBLZL2S.mjs";
-import "../../chunk-2WEX3K7C.mjs";
-import "../../chunk-4JZO2D7T.mjs";
+import "../../chunk-3NRBHSMQ.mjs";
+import "../../chunk-BXEVML7N.mjs";
+import "../../chunk-UEZNZBJO.mjs";
 import "../../chunk-JTXYKO3U.mjs";
 import "../../chunk-AUQDI5BS.mjs";
 import "../../chunk-4ZOFT75Q.mjs";

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

@@ -6,8 +6,8 @@ import { WriteBlobCommitmentsOptions, ShelbyBlobClient } from './ShelbyBlobClien
 import { ShelbyClientConfig } from './ShelbyClientConfig.js';
 import { ShelbyMetadataClient } from './ShelbyMetadataClient.js';
 import { ShelbyRPCClient } from './ShelbyRPCClient.js';
-import 'zod';
 import '@shelby-protocol/clay-codes';
+import 'zod';
 import '../types/blobs.js';
 import '../operations/index.js';
 import 'graphql-request';

package/dist/core/clients/ShelbyClient.mjs

@@ -1,26 +1,26 @@
 import {
   ShelbyClient
-} from "../../chunk-7PN65RDX.mjs";
-import "../../chunk-SRV4YWFH.mjs";
+} from "../../chunk-5CES6RPZ.mjs";
+import "../../chunk-EFR6H3RT.mjs";
+import "../../chunk-IBAUPQOF.mjs";
 import "../../chunk-XNEIWM4O.mjs";
+import "../../chunk-NHWWORCH.mjs";
 import "../../chunk-HPPMI7DC.mjs";
 import "../../chunk-OGKZ575S.mjs";
-import "../../chunk-NHWWORCH.mjs";
-import "../../chunk-MV6FNYAU.mjs";
-import "../../chunk-PJVWGMVI.mjs";
-import "../../chunk-4MG4XGY4.mjs";
+import "../../chunk-7O77OM4T.mjs";
+import "../../chunk-KTVNKLBT.mjs";
 import "../../chunk-CGYJLKBU.mjs";
 import "../../chunk-KJ24NKPH.mjs";
 import "../../chunk-AABBONAF.mjs";
+import "../../chunk-Z4FZ7W6L.mjs";
 import "../../chunk-I6NG5GNL.mjs";
 import "../../chunk-IE6LYVIA.mjs";
-import "../../chunk-OTBLZL2S.mjs";
-import "../../chunk-2WEX3K7C.mjs";
-import "../../chunk-4JZO2D7T.mjs";
+import "../../chunk-3NRBHSMQ.mjs";
+import "../../chunk-BXEVML7N.mjs";
+import "../../chunk-UEZNZBJO.mjs";
 import "../../chunk-JTXYKO3U.mjs";
 import "../../chunk-AUQDI5BS.mjs";
 import "../../chunk-4ZOFT75Q.mjs";
-import "../../chunk-Z4FZ7W6L.mjs";
 import "../../chunk-7P6ASYW6.mjs";
 export {
   ShelbyClient

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

@@ -54,19 +54,70 @@ declare class ShelbyMetadataClient {
      */
     getSliceAddresses(): Promise<AccountAddress[]>;
     /**
-     * Retrieves the storage providers assigned to a slice, through a placement group.
+     * Gets the placement group address for a slice.
+     *
+     * @param sliceAddress - The address of the slice account.
+     * @returns The placement group address as a string.
+     */
+    private getPlacementGroupAddressForSlice;
+    /**
+     * 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 });
+     * ```
+     */
+    getDesignatedStorageProvidersForSlice(params: {
+        account: AccountAddressInput;
+    }): Promise<(AccountAddress | 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 });
+     * ```
+     */
+    getActiveStorageProvidersForSlice(params: {
+        account: AccountAddressInput;
+    }): Promise<(AccountAddress | 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 The list of storage providers for the slice, or an empty array if none exist.
+     * @returns An array where result[i] contains the serving SPs for slot i.
      *
      * @example
      * ```typescript
-     * const pgInfo = await client.getStorageProvidersForSlice();
+     * const providers = await client.getServingStorageProvidersForSlice({ account: sliceAddress });
      * ```
      */
-    getStorageProvidersForSlice(params: {
+    getServingStorageProvidersForSlice(params: {
         account: AccountAddressInput;
-    }): Promise<AccountAddress[]>;
+    }): Promise<AccountAddress[][]>;
 }
 
 export { ShelbyMetadataClient };

package/dist/core/clients/ShelbyMetadataClient.mjs

@@ -1,7 +1,8 @@
 import {
   ShelbyMetadataClient
-} from "../../chunk-MV6FNYAU.mjs";
+} from "../../chunk-7O77OM4T.mjs";
 import "../../chunk-AABBONAF.mjs";
+import "../../chunk-UEZNZBJO.mjs";
 import "../../chunk-4ZOFT75Q.mjs";
 import "../../chunk-7P6ASYW6.mjs";
 export {