upd README

ts/shielder-sdk/README.md

@@ -1,37 +1,109 @@
 # `shielder-sdk`
 
-A web package for interacting with Shielder, a part of zkOS privacy engine.
+A TypeScript package for interacting with Shielder, a part of zkOS privacy engine. This SDK enables users to perform private transactions and manage accounts within the Shielder protocol.
+
+## Key Features
+
+- **Account Management**: Create and manage private accounts
+- **Private Transactions**: Shield and unshield tokens
+- **State Management**: Track and sync account state
+- **Event Monitoring**: Callbacks for transaction lifecycle events
 
 ## Usage
 
-In order to use most of the modules, WASM needs to be loaded. This package starts loading WASM automatically. User should await the published promise `wasmClientWorkerReady()`.
+The main entry point is the `createShielderClient` function which provides methods for interacting with the Shielder protocol.
+
+### Basic Example
 
-### Example usage
+```typescript
+import { createShielderClient } from "@cardinal-cryptography/shielder-sdk";
+import { CryptoClient } from "shielder-sdk-crypto";
 
+// Initialize the client
+const shielderClient = createShielderClient(
+  shielderSeedPrivateKey, // 32-byte hex format private key
+  chainId, // blockchain chain ID
+  rpcHttpEndpoint, // blockchain RPC endpoint
+  contractAddress, // Shielder contract address
+  relayerUrl, // URL of the relayer service
+  storage, // Storage interface for managing state
+  cryptoClient, // Instance of CryptoClient
+  callbacks // Optional callbacks for monitoring operations
+);
+
+// Shield tokens
+await shielderClient.shield(
+  1000n, // Amount to shield (in wei)
+  sendShielderTransaction, // Function to send transaction
+  "0x..." // From address
+);
 ```
-import {wasmClientWorkerInit, ShielderClient} from "@cardinal-cryptography/shielder-sdk"
 
-const threads = navigator.hardwareConcurrency;
+### CryptoClient
+
+The `CryptoClient` is a general interface for platform-dependent cryptographic operations required by the Shielder protocol. It is defined in `shielder-sdk-crypto` package.
+
+Currently available implementations:
 
-await wasmClientWorkerInit(threads).then(async () => {
-    // WASM initialization complete, ready to use sdk
+- **WebAssembly Implementation** (`shielder-sdk-crypto-wasm`): A high-performance implementation that leverages WebAssembly for cryptographic operations.
 
-    const shielderClient = ShielderClient.create(
-        ...
-        // parameters go there
-    );
-    await shielderClient.shield(1n);
-})
+### Common Operations
 
+#### Shielding Tokens
 
+```typescript
+const txHash = await shielderClient.shield(
+  amount, // Amount in wei
+  sendShielderTransaction, // Transaction sender function
+  fromAddress // Sender's address
+);
 ```
 
-## Development & Contribution
+#### Withdrawing Tokens
 
-If you want to work with local build of `shielder-wasm` package, link the local dependency in `package.json`:
+```typescript
+// Get current withdraw fees
+const fees = await shielderClient.getWithdrawFees();
 
+// Withdraw tokens
+const txHash = await shielderClient.withdraw(
+  amount, // Amount in wei
+  fees.totalFee, // Total fee for the operation
+  toAddress // Recipient's address
+);
 ```
-"shielder-wasm": "link:../../crates/shielder-wasm/pkg",
+
+#### Syncing State
+
+```typescript
+// Sync the local state with blockchain
+await shielderClient.syncShielder();
+
+// Get current account state
+const state = await shielderClient.accountState();
 ```
 
-and do `pnpm update`
+### Callbacks
+
+The SDK supports various callbacks to monitor operations:
+
+```typescript
+const callbacks = {
+  // Called after calldata is generated
+  onCalldataGenerated: (calldata, operation) => {
+    console.log(`Calldata generated for ${operation}`);
+  },
+  // Called after calldata is sent
+  onCalldataSent: (txHash, operation) => {
+    console.log(`Transaction ${txHash} sent for ${operation}`);
+  },
+  // Called when new transactions are found
+  onNewTransaction: (tx) => {
+    console.log("New transaction:", tx);
+  },
+  // Called when errors occur
+  onError: (error, stage, operation) => {
+    console.error(`Error in ${stage} stage of ${operation}:`, error);
+  }
+};
+```