stxer 0.3.2 → 0.4.0

package/README.md

@@ -12,12 +12,43 @@ yarn add stxer
 
 ## Features
 
-### 1. Batch Operations
+### 1. Transaction Simulation
 
-The SDK provides efficient batch reading capabilities for Stacks blockchain:
+Simulate complex transaction sequences before executing them on-chain:
 
 ```typescript
-import { batchRead, batchReadonly } from 'stxer';
+import { SimulationBuilder } from 'stxer';
+
+const simulationId = await SimulationBuilder.new({
+  network: 'mainnet', // or 'testnet'
+})
+  .withSender('ST...') // Set default sender
+  .addContractCall({
+    contract_id: 'ST...contract-name',
+    function_name: 'my-function',
+    function_args: [/* clarity values */]
+  })
+  .addSTXTransfer({
+    recipient: 'ST...',
+    amount: 1000000 // in microSTX
+  })
+  .addContractDeploy({
+    contract_name: 'my-contract',
+    source_code: '(define-public (hello) (ok "world"))'
+  })
+  .run();
+
+// View simulation results at: https://stxer.xyz/simulations/{network}/{simulationId}
+```
+
+### 2. Batch Operations
+
+The SDK provides two approaches for efficient batch reading from the Stacks blockchain:
+
+#### Direct Batch Reading
+
+```typescript
+import { batchRead } from 'stxer';
 
 // Batch read variables and maps
 const result = await batchRead({
@@ -29,11 +60,7 @@ const result = await batchRead({
     contract: contractPrincipalCV(...),
     mapName: 'my-map',
     mapKey: someCV
-  }]
-});
-
-// Batch readonly function calls
-const readonlyResult = await batchReadonly({
+  }],
   readonly: [{
     contract: contractPrincipalCV(...),
     functionName: 'my-function',
@@ -42,35 +69,114 @@ const readonlyResult = await batchReadonly({
 });
 ```
 
-### 2. Transaction Simulation
+#### BatchProcessor for Queue-based Operations
 
-Simulate complex transaction sequences before executing them on-chain:
+The BatchProcessor allows you to queue multiple read operations and automatically batch them together after a specified delay:
 
 ```typescript
-import { SimulationBuilder } from 'stxer';
+import { BatchProcessor } from 'stxer';
 
-const simulationId = await SimulationBuilder.new({
-  network: 'mainnet', // or 'testnet'
-})
-  .withSender('ST...') // Set default sender
-  .addContractCall({
-    contract_id: 'ST...contract-name',
-    function_name: 'my-function',
-    function_args: [/* clarity values */]
-  })
-  .addSTXTransfer({
-    recipient: 'ST...',
-    amount: 1000000 // in microSTX
-  })
-  .addContractDeploy({
-    contract_name: 'my-contract',
-    source_code: '(define-public (hello) (ok "world"))'
+const processor = new BatchProcessor({
+  stxerAPIEndpoint: 'https://api.stxer.xyz', // optional
+  batchDelayMs: 1000, // delay before processing batch
+});
+
+// Queue multiple operations that will be batched together
+const [resultA, resultB] = await Promise.all([
+  new Promise((resolve, reject) => {
+    processor.enqueue({
+      request: {
+        mode: 'variable',
+        contractAddress: 'SP...',
+        contractName: 'my-contract',
+        variableName: 'variable-a'
+      },
+      resolve,
+      reject
+    });
+  }),
+  new Promise((resolve, reject) => {
+    processor.enqueue({
+      request: {
+        mode: 'variable',
+        contractAddress: 'SP...',
+        contractName: 'my-contract',
+        variableName: 'variable-b'
+      },
+      resolve,
+      reject
+    });
   })
-  .run();
+]);
+
+// You can also queue different types of operations
+processor.enqueue({
+  request: {
+    mode: 'readonly',
+    contractAddress: 'SP...',
+    contractName: 'my-contract',
+    functionName: 'get-value',
+    functionArgs: []
+  },
+  resolve: (value) => console.log('Function result:', value),
+  reject: (error) => console.error('Error:', error)
+});
 
-// View simulation results at: https://stxer.xyz/simulations/{network}/{simulationId}
+processor.enqueue({
+  request: {
+    mode: 'mapEntry',
+    contractAddress: 'SP...',
+    contractName: 'my-contract',
+    mapName: 'my-map',
+    mapKey: someKey
+  },
+  resolve: (value) => console.log('Map entry:', value),
+  reject: (error) => console.error('Error:', error)
+});
 ```
 
+The BatchProcessor automatically:
+- Queues read operations
+- Batches them together after the specified delay
+- Makes a single API call for all queued operations
+- Distributes results back to the respective promises
+
+This is particularly useful when you need to make multiple blockchain reads and want to optimize network calls.
+
+### 3. Clarity API Utilities
+
+The SDK provides convenient utilities for reading data from Clarity contracts:
+
+```typescript
+import { callReadonly, readVariable, readMap } from 'stxer';
+import { SIP010TraitABI } from 'clarity-abi/abis';
+import { unwrapResponse } from 'ts-clarity';
+
+// Read from a contract function
+const supply = await callReadonly({
+  abi: SIP010TraitABI.functions,
+  functionName: 'get-total-supply',
+  contract: 'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-alex',
+}).then(unwrapResponse);
+
+// Read a contract variable
+const paused = await readVariable({
+  abi: [{ name: 'paused', type: 'bool', access: 'variable' }],
+  variableName: 'paused',
+  contract: 'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-vault-v2-01',
+});
+
+// Read from a contract map
+const approved = await readMap({
+  abi: [{ key: 'principal', name: 'approved-tokens', value: 'bool' }],
+  mapName: 'approved-tokens',
+  key: 'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-alex',
+  contract: 'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-vault-v2-01',
+});
+```
+
+These utilities provide type-safe ways to interact with Clarity contracts, with built-in ABI support and response unwrapping.
+
 ## Configuration
 
 You can customize the API endpoints:

package/dist/{batch-api.d.ts → BatchAPI.d.ts}

@@ -1,4 +1,10 @@
-import { type ClarityValue, type ContractPrincipalCV, type OptionalCV } from '@stacks/transactions';
+/**
+ * WARNING:
+ *
+ * this file will be used in cross-runtime environments (browser, cloudflare workers, XLinkSDK, etc.),
+ * so please be careful when adding `import`s to it.
+ */
+import { type ClarityValue, type ContractPrincipalCV } from '@stacks/transactions';
 export interface BatchReads {
     variables?: {
         contract: ContractPrincipalCV;
@@ -9,22 +15,20 @@ export interface BatchReads {
         mapName: string;
         mapKey: ClarityValue;
     }[];
+    readonly?: {
+        contract: ContractPrincipalCV;
+        functionName: string;
+        functionArgs: ClarityValue[];
+    }[];
     index_block_hash?: string;
 }
 export interface BatchReadsResult {
-    variables: (ClarityValue | Error)[];
-    maps: (OptionalCV | Error)[];
+    tip: string;
+    vars: (ClarityValue | Error)[];
+    maps: (ClarityValue | Error)[];
+    readonly: (ClarityValue | Error)[];
 }
 export interface BatchApiOptions {
     stxerApi?: string;
 }
 export declare function batchRead(reads: BatchReads, options?: BatchApiOptions): Promise<BatchReadsResult>;
-export interface BatchReadonlyRequest {
-    readonly: {
-        contract: ContractPrincipalCV;
-        functionName: string;
-        functionArgs: ClarityValue[];
-    }[];
-    index_block_hash?: string;
-}
-export declare function batchReadonly(req: BatchReadonlyRequest, options?: BatchApiOptions): Promise<(ClarityValue | Error)[]>;

package/dist/BatchProcessor.d.ts

@@ -0,0 +1,47 @@
+/**
+ * WARNING:
+ *
+ * this file will be used in cross-runtime environments (browser, cloudflare workers, XLinkSDK, etc.),
+ * so please be careful when adding `import`s to it.
+ */
+import { type ClarityValue, type OptionalCV } from '@stacks/transactions';
+export interface ReadOnlyRequest {
+    mode: 'readonly';
+    contractAddress: string;
+    contractName: string;
+    functionName: string;
+    functionArgs: ClarityValue[];
+}
+export interface MapEntryRequest {
+    mode: 'mapEntry';
+    contractAddress: string;
+    contractName: string;
+    mapName: string;
+    mapKey: ClarityValue;
+}
+export interface VariableRequest {
+    mode: 'variable';
+    contractAddress: string;
+    contractName: string;
+    variableName: string;
+}
+export type BatchRequest = MapEntryRequest | VariableRequest | ReadOnlyRequest;
+export interface QueuedRequest {
+    request: BatchRequest;
+    tip?: string;
+    resolve: (value: ClarityValue | OptionalCV) => void;
+    reject: (error: Error) => void;
+}
+export declare class BatchProcessor {
+    private queues;
+    private timeoutIds;
+    private readonly stxerAPIEndpoint;
+    private readonly batchDelayMs;
+    constructor(options: {
+        stxerAPIEndpoint?: string;
+        batchDelayMs: number;
+    });
+    private getQueueKey;
+    enqueue(request: QueuedRequest): void;
+    private processBatch;
+}

package/dist/clarity-api.d.ts

@@ -0,0 +1,27 @@
+import type { ClarityAbiFunction, ClarityAbiMap, ClarityAbiVariable, TContractPrincipal, TPrincipal } from 'clarity-abi';
+import type { InferReadonlyCallParameterType, InferReadonlyCallResultType, InferMapValueType, InferReadMapParameterType, InferReadVariableParameterType, InferVariableType } from 'ts-clarity';
+import { BatchProcessor } from './BatchProcessor';
+export type ReadonlyCallRuntimeOptions = {
+    sender?: TPrincipal;
+    contract: TContractPrincipal;
+    stacksEndpoint?: string;
+    indexBlockHash?: string;
+    batchProcessor?: BatchProcessor;
+};
+export type ReadMapRuntimeParameters = {
+    contract: TContractPrincipal;
+    stacksEndpoint?: string;
+    proof?: boolean;
+    indexBlockHash?: string;
+    batchProcessor?: BatchProcessor;
+};
+export type ReadVariableRuntimeParameterType = {
+    contract: TContractPrincipal;
+    stacksEndpoint?: string;
+    proof?: boolean;
+    indexBlockHash?: string;
+    batchProcessor?: BatchProcessor;
+};
+export declare function callReadonly<Functions extends readonly ClarityAbiFunction[] | readonly unknown[], FunctionName extends string>(params: InferReadonlyCallParameterType<Functions, FunctionName> & ReadonlyCallRuntimeOptions): Promise<InferReadonlyCallResultType<Functions, FunctionName>>;
+export declare function readMap<Maps extends readonly ClarityAbiMap[] | readonly unknown[] = readonly ClarityAbiMap[], MapName extends string = string>(params: InferReadMapParameterType<Maps, MapName> & ReadMapRuntimeParameters): Promise<InferMapValueType<Maps, MapName> | null>;
+export declare function readVariable<Variables extends readonly ClarityAbiVariable[] | readonly unknown[] = readonly ClarityAbiVariable[], VariableName extends string = string>(params: InferReadVariableParameterType<Variables, VariableName> & ReadVariableRuntimeParameterType): Promise<InferVariableType<Variables, VariableName>>;

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-export * from './batch-api';
+export * from './BatchAPI';
 export * from './simulation';
+export * from './clarity-api';