@storagehub-sdk/core 0.0.5 → 0.1.1

package/dist/abi/FileSystem.abi.json

@@ -0,0 +1,427 @@
+[
+  {
+    "anonymous": false,
+    "inputs": [
+      {
+        "indexed": true,
+        "internalType": "address",
+        "name": "who",
+        "type": "address"
+      },
+      {
+        "indexed": true,
+        "internalType": "bytes32",
+        "name": "bucketId",
+        "type": "bytes32"
+      },
+      {
+        "indexed": true,
+        "internalType": "bytes32",
+        "name": "mspId",
+        "type": "bytes32"
+      }
+    ],
+    "name": "BucketCreated",
+    "type": "event"
+  },
+  {
+    "anonymous": false,
+    "inputs": [
+      {
+        "indexed": true,
+        "internalType": "address",
+        "name": "who",
+        "type": "address"
+      },
+      {
+        "indexed": true,
+        "internalType": "bytes32",
+        "name": "bucketId",
+        "type": "bytes32"
+      }
+    ],
+    "name": "BucketDeleted",
+    "type": "event"
+  },
+  {
+    "anonymous": false,
+    "inputs": [
+      {
+        "indexed": true,
+        "internalType": "address",
+        "name": "who",
+        "type": "address"
+      },
+      {
+        "indexed": true,
+        "internalType": "bytes32",
+        "name": "bucketId",
+        "type": "bytes32"
+      },
+      {
+        "indexed": true,
+        "internalType": "bytes32",
+        "name": "newMspId",
+        "type": "bytes32"
+      }
+    ],
+    "name": "BucketMoveRequested",
+    "type": "event"
+  },
+  {
+    "anonymous": false,
+    "inputs": [
+      {
+        "indexed": true,
+        "internalType": "address",
+        "name": "who",
+        "type": "address"
+      },
+      {
+        "indexed": true,
+        "internalType": "bytes32",
+        "name": "bucketId",
+        "type": "bytes32"
+      },
+      {
+        "indexed": false,
+        "internalType": "bool",
+        "name": "_private",
+        "type": "bool"
+      }
+    ],
+    "name": "BucketPrivacyUpdated",
+    "type": "event"
+  },
+  {
+    "anonymous": false,
+    "inputs": [
+      {
+        "indexed": true,
+        "internalType": "address",
+        "name": "who",
+        "type": "address"
+      },
+      {
+        "indexed": true,
+        "internalType": "bytes32",
+        "name": "bucketId",
+        "type": "bytes32"
+      },
+      {
+        "indexed": true,
+        "internalType": "bytes32",
+        "name": "collectionId",
+        "type": "bytes32"
+      }
+    ],
+    "name": "CollectionCreated",
+    "type": "event"
+  },
+  {
+    "anonymous": false,
+    "inputs": [
+      {
+        "indexed": true,
+        "internalType": "bytes32",
+        "name": "fileKey",
+        "type": "bytes32"
+      },
+      {
+        "indexed": true,
+        "internalType": "address",
+        "name": "owner",
+        "type": "address"
+      }
+    ],
+    "name": "FileDeletionRequested",
+    "type": "event"
+  },
+  {
+    "anonymous": false,
+    "inputs": [
+      {
+        "indexed": true,
+        "internalType": "address",
+        "name": "who",
+        "type": "address"
+      },
+      {
+        "indexed": true,
+        "internalType": "bytes32",
+        "name": "fileKey",
+        "type": "bytes32"
+      },
+      {
+        "indexed": true,
+        "internalType": "bytes32",
+        "name": "bucketId",
+        "type": "bytes32"
+      }
+    ],
+    "name": "StorageRequestIssued",
+    "type": "event"
+  },
+  {
+    "anonymous": false,
+    "inputs": [
+      {
+        "indexed": true,
+        "internalType": "bytes32",
+        "name": "fileKey",
+        "type": "bytes32"
+      }
+    ],
+    "name": "StorageRequestRevoked",
+    "type": "event"
+  },
+  {
+    "inputs": [
+      {
+        "internalType": "bytes32",
+        "name": "bucketId",
+        "type": "bytes32"
+      }
+    ],
+    "name": "createAndAssociateCollectionWithBucket",
+    "outputs": [],
+    "stateMutability": "nonpayable",
+    "type": "function"
+  },
+  {
+    "inputs": [
+      {
+        "internalType": "bytes32",
+        "name": "mspId",
+        "type": "bytes32"
+      },
+      {
+        "internalType": "bytes",
+        "name": "name",
+        "type": "bytes"
+      },
+      {
+        "internalType": "bool",
+        "name": "_private",
+        "type": "bool"
+      },
+      {
+        "internalType": "bytes32",
+        "name": "valuePropId",
+        "type": "bytes32"
+      }
+    ],
+    "name": "createBucket",
+    "outputs": [],
+    "stateMutability": "nonpayable",
+    "type": "function"
+  },
+  {
+    "inputs": [
+      {
+        "internalType": "bytes32",
+        "name": "bucketId",
+        "type": "bytes32"
+      }
+    ],
+    "name": "deleteBucket",
+    "outputs": [],
+    "stateMutability": "nonpayable",
+    "type": "function"
+  },
+  {
+    "inputs": [
+      {
+        "internalType": "address",
+        "name": "owner",
+        "type": "address"
+      },
+      {
+        "internalType": "bytes",
+        "name": "name",
+        "type": "bytes"
+      }
+    ],
+    "name": "deriveBucketId",
+    "outputs": [
+      {
+        "internalType": "bytes32",
+        "name": "bucketId",
+        "type": "bytes32"
+      }
+    ],
+    "stateMutability": "view",
+    "type": "function"
+  },
+  {
+    "inputs": [
+      {
+        "internalType": "address",
+        "name": "user",
+        "type": "address"
+      }
+    ],
+    "name": "getPendingFileDeletionRequestsCount",
+    "outputs": [
+      {
+        "internalType": "uint32",
+        "name": "count",
+        "type": "uint32"
+      }
+    ],
+    "stateMutability": "view",
+    "type": "function"
+  },
+  {
+    "inputs": [
+      {
+        "internalType": "bytes32",
+        "name": "bucketId",
+        "type": "bytes32"
+      },
+      {
+        "internalType": "bytes",
+        "name": "location",
+        "type": "bytes"
+      },
+      {
+        "internalType": "bytes32",
+        "name": "fingerprint",
+        "type": "bytes32"
+      },
+      {
+        "internalType": "uint64",
+        "name": "size",
+        "type": "uint64"
+      },
+      {
+        "internalType": "bytes32",
+        "name": "mspId",
+        "type": "bytes32"
+      },
+      {
+        "internalType": "bytes[]",
+        "name": "peerIds",
+        "type": "bytes[]"
+      },
+      {
+        "internalType": "enum FileSystem.ReplicationTarget",
+        "name": "replicationTarget",
+        "type": "uint8"
+      },
+      {
+        "internalType": "uint32",
+        "name": "customReplicationTarget",
+        "type": "uint32"
+      }
+    ],
+    "name": "issueStorageRequest",
+    "outputs": [],
+    "stateMutability": "nonpayable",
+    "type": "function"
+  },
+  {
+    "inputs": [
+      {
+        "components": [
+          {
+            "internalType": "bytes32",
+            "name": "fileKey",
+            "type": "bytes32"
+          },
+          {
+            "internalType": "enum FileSystem.FileOperation",
+            "name": "operation",
+            "type": "uint8"
+          }
+        ],
+        "internalType": "struct FileSystem.FileOperationIntention",
+        "name": "signedIntention",
+        "type": "tuple"
+      },
+      {
+        "internalType": "bytes",
+        "name": "signature",
+        "type": "bytes"
+      },
+      {
+        "internalType": "bytes32",
+        "name": "bucketId",
+        "type": "bytes32"
+      },
+      {
+        "internalType": "bytes",
+        "name": "location",
+        "type": "bytes"
+      },
+      {
+        "internalType": "uint64",
+        "name": "size",
+        "type": "uint64"
+      },
+      {
+        "internalType": "bytes32",
+        "name": "fingerprint",
+        "type": "bytes32"
+      }
+    ],
+    "name": "requestDeleteFile",
+    "outputs": [],
+    "stateMutability": "nonpayable",
+    "type": "function"
+  },
+  {
+    "inputs": [
+      {
+        "internalType": "bytes32",
+        "name": "bucketId",
+        "type": "bytes32"
+      },
+      {
+        "internalType": "bytes32",
+        "name": "newMspId",
+        "type": "bytes32"
+      },
+      {
+        "internalType": "bytes32",
+        "name": "newValuePropId",
+        "type": "bytes32"
+      }
+    ],
+    "name": "requestMoveBucket",
+    "outputs": [],
+    "stateMutability": "nonpayable",
+    "type": "function"
+  },
+  {
+    "inputs": [
+      {
+        "internalType": "bytes32",
+        "name": "fileKey",
+        "type": "bytes32"
+      }
+    ],
+    "name": "revokeStorageRequest",
+    "outputs": [],
+    "stateMutability": "nonpayable",
+    "type": "function"
+  },
+  {
+    "inputs": [
+      {
+        "internalType": "bytes32",
+        "name": "bucketId",
+        "type": "bytes32"
+      },
+      {
+        "internalType": "bool",
+        "name": "_private",
+        "type": "bool"
+      }
+    ],
+    "name": "updateBucketPrivacy",
+    "outputs": [],
+    "stateMutability": "nonpayable",
+    "type": "function"
+  }
+]

package/dist/abi/filesystem.d.ts

@@ -0,0 +1,49 @@
+export declare const filesystemAbi: ({
+    anonymous: boolean;
+    inputs: {
+        indexed: boolean;
+        internalType: string;
+        name: string;
+        type: string;
+    }[];
+    name: string;
+    type: string;
+    outputs?: never;
+    stateMutability?: never;
+} | {
+    inputs: {
+        internalType: string;
+        name: string;
+        type: string;
+    }[];
+    name: string;
+    outputs: {
+        internalType: string;
+        name: string;
+        type: string;
+    }[];
+    stateMutability: string;
+    type: string;
+    anonymous?: never;
+} | {
+    inputs: ({
+        components: {
+            internalType: string;
+            name: string;
+            type: string;
+        }[];
+        internalType: string;
+        name: string;
+        type: string;
+    } | {
+        internalType: string;
+        name: string;
+        type: string;
+        components?: never;
+    })[];
+    name: string;
+    outputs: never[];
+    stateMutability: string;
+    type: string;
+    anonymous?: never;
+})[];

package/dist/evm/clients.d.ts

@@ -0,0 +1,49 @@
+/**
+ * EVM client helpers (Core)
+ *
+ * Normalize how Core talks to an EVM endpoint in both environments (browser EIP‑1193 and Node HTTP)
+ * and return viem clients for reads (public) and writes (wallet) with a minimal API.
+ */
+import { type Account, type Chain, createPublicClient, createWalletClient, type EIP1193Provider } from "viem";
+/**
+ * HTTP transport configuration.
+ * - Requires a JSON‑RPC URL and an explicit viem Chain.
+ */
+type HttpTransport = {
+    httpUrl: string;
+    chain: Chain;
+};
+/**
+ * EIP‑1193 transport configuration (e.g., window.ethereum).
+ * - Chain can be inferred from the provider; explicit Chain is not required.
+ */
+type Eip1193Transport = {
+    eip1193: EIP1193Provider;
+};
+export type EvmClientsOptions = {
+    transport: HttpTransport | Eip1193Transport;
+    account?: Account | `0x${string}`;
+    timeoutMs?: number;
+};
+/**
+ * Returned clients:
+ * - readClient: public client for reads/logs (always available)
+ * - writeClient: wallet client for transactions (only when account is provided)
+ */
+export type EvmClients = {
+    readClient: ReturnType<typeof createPublicClient>;
+    writeClient: ReturnType<typeof createWalletClient> | undefined;
+};
+/**
+ * Factory to create EVM clients for Core.
+ *
+ * Transport:
+ * - HTTP:   { transport: { httpUrl, chain }, account?, timeoutMs? }
+ * - EIP1193:{ transport: { eip1193 },          account?, timeoutMs? }
+ *
+ * Returns:
+ * - readClient: always present (public client)
+ * - writeClient: present when an account is provided (wallet client)
+ */
+export declare function createEvmClients(opts: EvmClientsOptions): EvmClients;
+export {};

package/dist/evm/storageHubClient.d.ts

@@ -0,0 +1,149 @@
+/**
+ * StorageHubClient - Unified EVM client for StorageHub blockchain
+ *
+ * Provides ergonomic read/write methods for StorageHub precompiles using viem.
+ * Handles gas estimation automatically with Frontier-optimized defaults.
+ *
+ * All arguments are strongly typed. String data (names, paths) are passed as strings and encoded internally.
+ * Binary data (signatures) are passed as Uint8Array. Hex values are 0x-prefixed strings (32-byte IDs).
+ */
+import { filesystemAbi } from "../abi/filesystem";
+import type { EvmWriteOptions, StorageHubClientOptions } from "./types";
+import type { ReplicationLevel } from "./types";
+import { type Address } from "viem";
+export { filesystemAbi };
+export declare class StorageHubClient {
+    private readonly publicClient;
+    private readonly walletClient;
+    private readonly filesystemContractAddress;
+    private static readonly MAX_BUCKET_NAME_BYTES;
+    private static readonly MAX_LOCATION_BYTES;
+    private static readonly MAX_PEER_ID_BYTES;
+    private static readonly DEFAULT_GAS_MULTIPLIER;
+    private static readonly DEFAULT_GAS_PRICE;
+    /**
+     * Get write contract instance bound to the wallet client.
+     *
+     * @returns Contract instance for write operations (transactions)
+     */
+    private getWriteContract;
+    /**
+     * Get read contract instance bound to the public client.
+     *
+     * @returns Contract instance for read operations (view calls)
+     */
+    private getReadContract;
+    /**
+     * Reusable gas estimation for any contract method.
+     *
+     * Uses internal PublicClient for reliable estimation on Frontier chains.
+     * Applies safety multiplier to handle weight→gas conversion issues.
+     *
+     * @param functionName - Contract method name
+     * @param args - Method arguments
+     * @param options - Gas overrides (explicit gas, multiplier, etc.)
+     * @returns Estimated gas limit with safety multiplier applied
+     */
+    private estimateGas;
+    /**
+     * Build transaction options with gas and fee settings.
+     * Handles both legacy and EIP-1559 fee structures.
+     */
+    private buildTxOptions;
+    /**
+     * Validate string length in UTF-8 bytes and convert to hex.
+     * @param str - Input string to validate and encode
+     * @param maxBytes - Maximum allowed byte length
+     * @param label - Label for error messages
+     * @returns 0x-prefixed hex string
+     */
+    private validateStringLength;
+    /**
+     * Create a StorageHub client with automatic gas estimation.
+     *
+     * @param opts.rpcUrl - RPC endpoint URL for the StorageHub chain
+     * @param opts.chain - Viem chain configuration
+     * @param opts.walletClient - Wallet client for transaction signing
+     * @param opts.filesystemContractAddress - Optional filesystem precompile address
+     */
+    constructor(opts: StorageHubClientOptions);
+    /**
+     * Derive a bucket ID deterministically from owner + name.
+     * @param owner - EVM address of the bucket owner
+     * @param name - bucket name as string (max 100 UTF-8 bytes)
+     * @returns bucketId as 0x-prefixed 32-byte hex
+     */
+    deriveBucketId(owner: Address, name: string): Promise<unknown> | undefined;
+    /**
+     * Get how many file deletion requests a user currently has pending.
+     * @param user - user EVM address
+     * @returns count as number
+     */
+    getPendingFileDeletionRequestsCount(user: Address): Promise<unknown> | undefined;
+    /**
+     * Create a new bucket.
+     * @param mspId - 32-byte MSP ID (0x-prefixed hex)
+     * @param name - bucket name as string (max 100 UTF-8 bytes)
+     * @param isPrivate - true for private bucket
+     * @param valuePropId - 32-byte value proposition ID (0x-prefixed hex)
+     * @param options - optional gas and fee overrides
+     */
+    createBucket(mspId: `0x${string}`, name: string, isPrivate: boolean, valuePropId: `0x${string}`, options?: EvmWriteOptions): Promise<`0x${string}` | undefined>;
+    /**
+     * Request moving a bucket to a new MSP/value proposition.
+     * @param bucketId - 32-byte bucket ID
+     * @param newMspId - 32-byte new MSP ID
+     * @param newValuePropId - 32-byte new value proposition ID
+     * @param options - optional gas and fee overrides
+     */
+    requestMoveBucket(bucketId: `0x${string}`, newMspId: `0x${string}`, newValuePropId: `0x${string}`, options?: EvmWriteOptions): Promise<`0x${string}` | undefined>;
+    /**
+     * Update bucket privacy flag.
+     * @param bucketId - 32-byte bucket ID
+     * @param isPrivate - true for private
+     * @param options - optional gas and fee overrides
+     */
+    updateBucketPrivacy(bucketId: `0x${string}`, isPrivate: boolean, options?: EvmWriteOptions): Promise<`0x${string}` | undefined>;
+    /**
+     * Create and associate a collection with a bucket.
+     * @param bucketId - 32-byte bucket ID
+     * @param options - optional gas and fee overrides
+     */
+    createAndAssociateCollectionWithBucket(bucketId: `0x${string}`, options?: EvmWriteOptions): Promise<`0x${string}` | undefined>;
+    /**
+     * Delete an empty bucket.
+     * @param bucketId - 32-byte bucket ID
+     * @param options - optional gas and fee overrides
+     */
+    deleteBucket(bucketId: `0x${string}`, options?: EvmWriteOptions): Promise<`0x${string}` | undefined>;
+    /**
+     * Issue a storage request for a file.
+     * @param bucketId - 32-byte bucket ID
+     * @param location - file path as string (max 512 UTF-8 bytes)
+     * @param fingerprint - 32-byte file fingerprint
+     * @param size - file size as bigint (storage units)
+     * @param mspId - 32-byte MSP ID
+     * @param peerIds - array of peer ID strings (max 5 entries, each max 100 UTF-8 bytes)
+     * @param replicationLevel - replication level
+     * @param replicas - number of replicas (only required for ReplicationLevel.Custom)
+     * @param options - optional gas and fee overrides
+     */
+    issueStorageRequest(bucketId: `0x${string}`, location: string, fingerprint: `0x${string}`, size: bigint, mspId: `0x${string}`, peerIds: string[], replicationLevel: ReplicationLevel, replicas: number, options?: EvmWriteOptions): Promise<`0x${string}` | undefined>;
+    /**
+     * Revoke a pending storage request by file key.
+     * @param fileKey - 32-byte file key
+     * @param options - optional gas and fee overrides
+     */
+    revokeStorageRequest(fileKey: `0x${string}`, options?: EvmWriteOptions): Promise<`0x${string}` | undefined>;
+    /**
+     * Request deletion of a file using a signed intention.
+     * @param signedIntention - tuple [fileKey: 0x32, operation: number] where operation must be 0 (Delete)
+     * @param signature - 65-byte secp256k1 signature over the SCALE-encoded intention
+     * @param bucketId - 32-byte bucket ID
+     * @param location - file path as string (max 512 UTF-8 bytes)
+     * @param size - file size as bigint (storage units)
+     * @param fingerprint - 32-byte file fingerprint
+     * @param options - optional gas and fee overrides
+     */
+    requestDeleteFile(signedIntention: readonly [`0x${string}`, number], signature: Uint8Array, bucketId: `0x${string}`, location: string, size: bigint, fingerprint: `0x${string}`, options?: EvmWriteOptions): Promise<`0x${string}` | undefined>;
+}