@storagehub-sdk/core 0.0.5 → 0.1.1

package/README.md

@@ -31,7 +31,139 @@ import { HttpClient, type HttpClientConfig } from '@storagehub-sdk/core';
 const http = new HttpClient({
   baseUrl: 'https://example.invalid',
 } satisfies HttpClientConfig);
+```
+
+### EVM Integration with StorageHub
+
+The Core SDK provides seamless integration with StorageHub's EVM precompiles, offering automatic gas estimation, type safety, and a clean developer experience.
+
+#### ABI Generation
+- Solidity contracts are automatically compiled to ABI during `prebuild` using `solc-js`
+- Generated ABIs are strongly typed using `viem` and `abitype`
+- No code generation required - pure TypeScript type inference
+
+#### StorageHubClient - Unified EVM Interface
+
+```ts
+import { StorageHubClient } from '@storagehub-sdk/core';
+import { createWalletClient, defineChain, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+
+// Define your StorageHub chain
+const storageHubChain = defineChain({
+  id: 181222,
+  name: 'StorageHub',
+  nativeCurrency: { name: 'StorageHub', symbol: 'SH', decimals: 18 },
+  rpcUrls: { default: { http: ['http://localhost:9944'] } },
+});
+
+// Create wallet client
+const account = privateKeyToAccount('0x...');
+const walletClient = createWalletClient({
+  chain: storageHubChain,
+  account,
+  transport: http('http://localhost:9944')
+});
+
+// Create StorageHub client - handles everything automatically
+const hub = new StorageHubClient({
+  rpcUrl: 'http://localhost:9944',
+  chain: storageHubChain,
+  walletClient
+});
+```
+
+#### Basic Usage
+
+```ts
+// Read operations (no gas required)
+const name = new TextEncoder().encode('my-bucket');
+const bucketId = await hub.deriveBucketId('0xOwnerAddress', name);
+const pendingRequests = await hub.getPendingFileDeletionRequestsCount('0xUserAddress');
+
+// Write operations (automatic gas estimation)
+const txHash = await hub.createBucket(
+  '0xMspId',           // MSP ID
+  name,               // Bucket name (max 100 bytes)
+  false,              // isPrivate
+  '0xValuePropId'     // Value proposition ID
+);
+
+// Write with custom gas options
+const txHash2 = await hub.updateBucketPrivacy('0xBucketId', true, {
+  gasMultiplier: 8,        // Higher safety margin
+  gasPrice: parseGwei('2') // Custom gas price
+});
+```
+
+#### Available Methods
+
+**Bucket Management:**
+- `createBucket(mspId, name, isPrivate, valuePropId, options?)`
+- `deleteBucket(bucketId, options?)`
+- `updateBucketPrivacy(bucketId, isPrivate, options?)`
+- `requestMoveBucket(bucketId, newMspId, newValuePropId, options?)`
+
+**Storage Operations:**
+- `issueStorageRequest(bucketId, location, fingerprint, size, mspId, peerIds, replicationTarget, customReplicationTarget, options?)`
+- `revokeStorageRequest(fileKey, options?)`
+- `requestDeleteFile(signedIntention, signature, bucketId, location, size, fingerprint, options?)`
+
+**Collections:**
+- `createAndAssociateCollectionWithBucket(bucketId, options?)`
+
+**Read Operations:**
+- `deriveBucketId(owner, name)`
+- `getPendingFileDeletionRequestsCount(user)`
+
+#### Gas Handling
+
+The SDK provides intelligent gas estimation with Frontier chain optimizations:
+
+```ts
+// Automatic gas estimation (recommended)
+await hub.createBucket(mspId, name, false, valuePropId);
+
+// Custom gas options
+await hub.createBucket(mspId, name, false, valuePropId, {
+  gasMultiplier: 6,           // Safety multiplier (default: 5)
+  gasPrice: parseGwei('1.5'), // Legacy gas pricing
+  // OR EIP-1559 fees:
+  maxFeePerGas: parseGwei('2'),
+  maxPriorityFeePerGas: parseGwei('0.5')
+});
+
+// Explicit gas limit
+await hub.createBucket(mspId, name, false, valuePropId, {
+  gas: 500_000n  // Skip estimation, use exact amount
+});
+```
+
+#### Error Handling
+
+```ts
+try {
+  await hub.createBucket(mspId, name, false, valuePropId);
+} catch (error) {
+  if (error.message.includes('exceeds maximum length')) {
+    // Handle validation errors
+  } else if (error.message.includes('OutOfGas')) {
+    // Handle gas estimation issues
+  }
+}
+```
+
+#### Type Safety
+
+All methods are fully typed with parameter validation:
+
+```ts
+// ✅ Type-safe parameters
+const name = new TextEncoder().encode('bucket-name'); // Uint8Array
+const mspId = '0x...' as `0x${string}`;              // Hex string type
 
+// ❌ Compile-time errors for invalid types
+await hub.createBucket('invalid', 'string', false, mspId); // TypeScript error
 ```
 
 ### Local wallet