@notifi-network/fusion-sdk 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,188 @@
+# Fusion SDK
+
+Fusion SDK provides TypeScript/JavaScript wrappers and types for interacting with Notifi Fusion blockchain services, including EVM, Sui, Solana, storage management, and subscriptions.
+
+## Installation
+
+```bash
+npm install fusion-sdk
+```
+
+## Usage
+
+```typescript
+import {
+  EvmRpc,
+  SuiRpc,
+  SolanaRpc,
+  PersistentStorage,
+  EphemeralStorage,
+  Subscriptions,
+  BlockchainType,
+  HttpMethod,
+  Region,
+  getParserBlobInput
+} from "fusion-sdk";
+
+const evm = new EvmRpc("your-context-id");
+const sui = new SuiRpc("your-context-id");
+const solana = new SolanaRpc("your-context-id");
+const persistentStorage = new PersistentStorage("your-context-id");
+const ephemeralStorage = new EphemeralStorage("your-context-id");
+const subscriptions = new Subscriptions("your-context-id");
+```
+
+## API Reference
+
+### Classes
+
+#### EvmRpc
+EVM-specific blockchain operations.
+
+**Methods:**
+- `runEthCall(request)`: Executes an Ethereum call operation.
+- `getAccountBalance(request)`: Retrieves the account balance for an Ethereum address.
+
+```typescript
+const evm = new EvmRpc("your-context-id");
+const balance = await evm.getAccountBalance({ address: "0x..." });
+```
+
+#### SuiRpc
+Sui blockchain operations.
+
+**Methods:**
+- `getSuiAccountBalance(request)`: Retrieves the account balance for a Sui address.
+- `runSuiTransaction(request)`: Executes a Sui transaction.
+- `getSuiObject(request)`: Retrieves a Sui object.
+
+```typescript
+const sui = new SuiRpc("your-context-id");
+const balance = await sui.getSuiAccountBalance({ address: "0x..." });
+```
+
+#### SolanaRpc
+Solana blockchain operations.
+
+**Methods:**
+- `getSolanaBalance(request)`: Retrieves the balance for a Solana address.
+- `getSolanaAccountInfo(request)`: Retrieves account information for a Solana address.
+- `getSolanaSlot(request)`: Retrieves the current Solana slot.
+
+```typescript
+const solana = new SolanaRpc("your-context-id");
+const balance = await solana.getSolanaBalance({ address: "..." });
+```
+
+#### PersistentStorage
+CRUD operations for persistent storage.
+
+**Methods:**
+- `put(request)`: Stores a string value in persistent storage.
+- `get(request)`: Retrieves a value from persistent storage.
+- `delete(request)`: Deletes a value from persistent storage.
+
+```typescript
+const persistentStorage = new PersistentStorage("your-context-id");
+await persistentStorage.put({ key: "foo", value: "bar" });
+const value = await persistentStorage.get({ key: "foo" });
+```
+
+**Optimistic Concurrency Example:**
+Fetch a value, increment its version, update, and retry on exception (optimistic locking with 100ms jitter):
+
+```typescript
+function sleep(ms: number) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+async function updateWithOptimisticLock(key: string, newValue: string, maxRetries = 3) {
+  let attempt = 0;
+  while (attempt < maxRetries) {
+    try {
+      // Fetch current value and version
+      const current = await persistentStorage.get({ key });
+      const currentVersion = current.version ?? 0;
+      // Attempt to update with incremented version
+      await persistentStorage.put({ key, value: newValue, version: currentVersion + 1 });
+      return true;
+    } catch (err) {
+      attempt++;
+      if (attempt >= maxRetries) throw err;
+      // Add 100ms jitter before retrying
+      await sleep(100 + Math.floor(Math.random() * 100));
+    }
+  }
+  return false;
+}
+
+// Usage
+await updateWithOptimisticLock("foo", "newBar");
+```
+
+This pattern helps ensure updates are atomic and consistent, retrying if another process updates the value concurrently.
+
+#### EphemeralStorage
+Operations for ephemeral storage.
+
+**Methods:**
+- `put(request)`: Stores a string value in ephemeral storage.
+- `get(request)`: Retrieves a value from ephemeral storage.
+- `delete(request)`: Deletes a value from ephemeral storage.
+- `peek(request)`: Peeks at the next value in a queue in ephemeral storage.
+- `enqueue(request)`: Enqueues a value into a queue in ephemeral storage.
+- `dequeue(request)`: Dequeues a value from a queue in ephemeral storage.
+- `getModuleExecutionParams(request)`: Retrieves module execution parameters.
+- `getOnChainBlock(request)`: Retrieves an on-chain block.
+
+```typescript
+const ephemeralStorage = new EphemeralStorage("your-context-id");
+await ephemeralStorage.put({ key: "temp", value: "baz" });
+const value = await ephemeralStorage.get({ key: "temp" });
+```
+
+#### Subscriptions
+Manage and retrieve subscription data.
+
+**Methods:**
+- `getSubscriptions(request)`: Retrieves subscription data.
+
+```typescript
+const subscriptions = new Subscriptions("your-context-id");
+const subs = await subscriptions.getSubscriptions({ eventTypeId: "event-type-id" });
+```
+
+All wrappers require a `contextId` string for gRPC requests. This is provided as an argument in the parse function in the Fusion system.
+
+### Types & Enums
+- `BlockchainType`: Enum for supported blockchains (EVM, Solana, Sui, etc.)
+
+### Utility Functions
+- `getParserBlobInput(contextId: string, urlForBlob: string)`: Fetches and parses block data from storage. The response can be typed as:
+  - `EvmBlockAndLogs` for EVM chains
+  - `SolanaBlockAndLogs` for Solana
+  - `SuiCheckpointTransactions` for Sui
+  This allows you to safely cast and work with chain-specific block data structures in your application. Not applicable to OffChain parsers.
+
+## Environment Variables (SDK developer usage)
+- `EVM_RPC_ADDRESS`: EVM gRPC endpoint (default: localhost:50054)
+- `SUI_RPC_ADDRESS`: Sui gRPC endpoint (default: localhost:50057)
+- `SOLANA_RPC_ADDRESS`: Solana gRPC endpoint (default: localhost:50055)
+- `PERSISTENT_STORAGE_ADDRESS`: Persistent storage gRPC endpoint (default: localhost:50053)
+- `EPHEMERAL_STORAGE_ADDRESS`: Ephemeral storage gRPC endpoint (default: localhost:50052)
+- `SUBSCRIPTION_MANAGER_ADDRESS`: Subscriptions gRPC endpoint (default: localhost:50056)
+- `GRPC_INSECURE`: Set to "true" for insecure local connections
+
+## Publishing
+
+To publish to npm:
+
+```bash
+npm publish
+```
+
+Ensure your documentation and API are up to date before publishing.
+
+## License
+
+See [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -8,3 +8,4 @@ export { SubscriptionsWrapper as Subscriptions } from './fusion_wrappers/subscri
 export { BlockchainType } from './protos_gen/notifi/common/v1/types.js';
 export { HttpMethod, Region } from './protos_gen/services/fetch_proxy/v1/fetch_proxy.js';
 export { getParserBlobInput } from './utils/execution_param_fetch.js';
+export type { EvmBlock, EvmLogs, EvmBlockAndLogs, EvmTransactions, SolanaBlockAndLogs, SuiCheckpointTransactions } from './types/parserInputTypes.js';

package/dist/types/parserInputTypes.d.ts

@@ -61,5 +61,5 @@ export interface SuiCheckpointTransactions {
     transactions: any[];
 }
 export interface SolanaBlockAndLogs {
-    block: any;
+    solanaBlock: any;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notifi-network/fusion-sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "SDK utils for Notifi Fusion parser development. This includes types and helpers for accessing ephemeral/persistent storage, RPCs for different chains, and other utilities.",
   "type": "module",
   "main": "dist/index.js",