stxer 0.4.5 → 0.6.1

package/README.md

@@ -1,6 +1,6 @@
 # stxer SDK
 
-A powerful SDK for Stacks blockchain that provides batch operations and transaction simulation capabilities.
+A powerful SDK for Stacks blockchain that provides transaction simulation, batch operations, contract AST parsing, and chain tip information.
 
 ## Installation
 
@@ -12,36 +12,252 @@ yarn add stxer
 
 ## Features
 
-### 1. Transaction Simulation
+### 1. Transaction Simulation (V2 API)
 
-Simulate complex transaction sequences before executing them on-chain:
+Simulate complex transaction sequences before executing them on-chain. The SDK supports all V2 step types:
+
+#### Basic Simulation
 
 ```typescript
 import { SimulationBuilder } from 'stxer';
 
 const simulationId = await SimulationBuilder.new({
   network: 'mainnet', // or 'testnet'
+  skipTracing: false, // Set to true for faster simulations without debug info
 })
-  .withSender('ST...') // Set default sender
+  .useBlockHeight(130818) // Optional: use specific block height
+  .withSender('SP...') // Set default sender
   .addContractCall({
-    contract_id: 'ST...contract-name',
+    contract_id: 'SP...contract-name',
     function_name: 'my-function',
-    function_args: [/* clarity values */]
+    function_args: [/* clarity values */],
+    sender: 'SP...', // Optional: overrides default sender
+    fee: 100, // Optional: fee in microSTX
   })
   .addSTXTransfer({
-    recipient: 'ST...',
-    amount: 1000000 // in microSTX
+    recipient: 'SP...',
+    amount: 1000000, // in microSTX
+  })
+  .addContractDeploy({
+    contract_name: 'my-contract',
+    source_code: '(define-public (hello) (ok "world"))',
+    deployer: 'SP...', // Optional: overrides default sender
+    clarity_version: 4, // Optional: Clarity1, Clarity2, Clarity3, or Clarity4
+  })
+  .run();
+
+// View simulation results at: https://stxer.xyz/simulations/mainnet/{simulationId}
+```
+
+#### Advanced V2 Step Types
+
+The SDK supports all V2 simulation step types:
+
+```typescript
+import { SimulationBuilder, ClarityVersion } from 'stxer';
+
+const simulationId = await SimulationBuilder.new()
+  .withSender('SP...')
+
+  // === Transaction Steps ===
+  // STX Transfer
+  .addSTXTransfer({ recipient: 'SP...', amount: 1000 })
+
+  // Contract Call
+  .addContractCall({
+    contract_id: 'SP...contract',
+    function_name: 'my-function',
+    function_args: [boolCV(true), uintCV(123)],
   })
+
+  // Contract Deploy
   .addContractDeploy({
     contract_name: 'my-contract',
-    source_code: '(define-public (hello) (ok "world"))'
+    source_code: '(define-data-var counter uint u0)',
+    clarity_version: ClarityVersion.Clarity4,
+  })
+
+  // === Eval Steps ===
+  // Read state
+  .addEvalCode('SP...contract', '(var-get counter)')
+
+  // Modify state
+  .addEvalCode('SP...contract', '(var-set counter u100)')
+
+  // === SetContractCode Step ===
+  // Directly set contract code without a transaction
+  .addSetContractCode({
+    contract_id: 'SP...contract',
+    source_code: '(define-data-var enabled bool false)',
+    clarity_version: ClarityVersion.Clarity4,
   })
+
+  // === Reads Batch Step ===
+  // Batch multiple read operations in a single step
+  .addReads([
+    { DataVar: ['SP...contract', 'counter'] },
+    { DataVar: ['SP...contract', 'enabled'] },
+    { StxBalance: 'SP...' },
+    { Nonce: 'SP...' },
+    { EvalReadonly: ['SP...', '', 'SP...contract', '(get-counter)'] },
+  ])
+
+  // === TenureExtend Step ===
+  // Extend tenure (resets execution cost)
+  .addTenureExtend()
+
   .run();
+```
+
+#### Reads Batch Sub-Types
+
+The `Reads` step supports multiple read operation types:
+
+```typescript
+.addReads([
+  // Read a data variable
+  { DataVar: ['SP...contract', 'my-var'] },
+
+  // Read a map entry (key must be hex-encoded Clarity value)
+  { MapEntry: ['SP...contract', 'my-map', '0x0...'] },
+
+  // Call a read-only function
+  { EvalReadonly: ['SP...', '', 'SP...contract', '(my-function)'] },
+
+  // Read STX balance
+  { StxBalance: 'SP...' },
+
+  // Read fungible token balance
+  { FtBalance: ['SP...token-contract', 'token-name', 'SP...principal'] },
+
+  // Read fungible token supply
+  { FtSupply: ['SP...token-contract', 'token-name'] },
+
+  // Read account nonce
+  { Nonce: 'SP...' },
+])
+```
+
+### 2. Programmatic Simulation APIs
+
+For advanced use cases where you need more control than `SimulationBuilder` provides, the SDK exposes low-level programmatic APIs that directly map to the stxer V2 simulation endpoints.
+
+#### Instant Simulation
+
+Simulate a single transaction without creating a session. Useful for apps/wallets to preview transaction results before sending:
+
+```typescript
+import { instantSimulation } from 'stxer';
+
+const result = await instantSimulation({
+  transaction: '0x...', // Hex-encoded transaction
+  reads: [
+    { DataVar: ['SP...contract', 'my-var'] },
+    { StxBalance: 'SP...' }
+  ]
+});
+
+console.log(result.receipt.result); // Transaction result
+console.log(result.reads); // Optional read results
+```
+
+#### Session-Based Simulation
+
+For more complex scenarios with multiple steps:
+
+```typescript
+import {
+  createSimulationSession,
+  submitSimulationSteps,
+  getSimulationResult,
+  simulationBatchReads
+} from 'stxer';
+
+// 1. Create a simulation session
+const sessionId = await createSimulationSession({
+  skip_tracing: false // Set to true for faster simulations
+});
+
+// 2. Submit steps to the session
+const stepResults = await submitSimulationSteps(sessionId, {
+  steps: [
+    { Transaction: '0x...' },
+    { Eval: ['SP...', '', 'SP...contract', '(var-get my-var)'] },
+    { SetContractCode: ['SP...contract', '(define-data-var x uint u0)', 4] },
+    { Reads: [
+      { DataVar: ['SP...contract', 'my-var'] },
+      { StxBalance: 'SP...' }
+    ]},
+    { TenureExtend: [] }
+  ]
+});
+
+console.log(`Executed ${stepResults.steps.length} steps`);
+
+// 3. Get full simulation results
+const result = await getSimulationResult(sessionId);
+console.log(result.metadata);
+console.log(result.steps);
 
-// View simulation results at: https://stxer.xyz/simulations/{network}/{simulationId}
+// 4. Batch reads from simulation state
+const reads = await simulationBatchReads(sessionId, {
+  vars: [['SP...contract', 'my-var']],
+  maps: [['SP...contract', 'my-map', '0x...']],
+  stx: ['SP...']
+});
+console.log(reads.vars);
+console.log(reads.stx);
+```
+
+#### API Options
+
+All programmatic APIs accept an optional `stxerApi` parameter to customize the endpoint:
+
+```typescript
+const sessionId = await createSimulationSession(
+  { skip_tracing: true },
+  { stxerApi: 'https://testnet-api.stxer.xyz' }
+);
+```
+
+### 3. Get Chain Tip
+
+Fetch the current chain tip information:
+
+```typescript
+import { getTip, type SidecarTip } from 'stxer';
+
+const tip: SidecarTip = await getTip();
+console.log(`Current block: ${tip.block_height}`);
+console.log(`Block hash: ${tip.block_hash}`);
+console.log(`Bitcoin height: ${tip.bitcoin_height}`);
+console.log(`Tenure cost: ${tip.tenure_cost}`);
+```
+
+### 4. Contract AST Operations
+
+Fetch or parse contract Abstract Syntax Trees:
+
+```typescript
+import { getContractAST, parseContract } from 'stxer';
+
+// Fetch on-chain contract AST
+const ast = await getContractAST({
+  contractId: 'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-pool-v2-01'
+});
+console.log(ast.source_code);
+console.log(ast.abi);
+
+// Parse local source code
+const parsed = await parseContract({
+  contractId: 'SP...contract-name',
+  sourceCode: '(define-public (hello) (ok "world"))',
+  clarityVersion: '4', // Optional: '1' | '2' | '3' | '4'
+  epoch: 'Epoch33' // Optional
+});
 ```
 
-### 2. Batch Operations
+### 5. Batch Operations
 
 The SDK provides two approaches for efficient batch reading from the Stacks blockchain:
 
@@ -123,7 +339,7 @@ The BatchProcessor automatically:
 
 This is particularly useful when you need to make multiple blockchain reads and want to optimize network calls.
 
-### 3. Clarity API Utilities
+### 6. Clarity API Utilities
 
 The SDK provides convenient utilities for reading data from Clarity contracts:
 
@@ -159,16 +375,106 @@ These utilities provide type-safe ways to interact with Clarity contracts, with
 
 ## Configuration
 
-You can customize the API endpoints:
+### API Endpoint Constants
+
+The SDK exports constants for stxer API endpoints:
 
 ```typescript
+import { STXER_API_MAINNET, STXER_API_TESTNET } from 'stxer';
+
+console.log(STXER_API_MAINNET); // https://api.stxer.xyz
+console.log(STXER_API_TESTNET); // https://testnet-api.stxer.xyz
+```
+
+### Customizing API Endpoints
+
+You can customize the API endpoints for all operations:
+
+```typescript
+import { SimulationBuilder, STXER_API_TESTNET } from 'stxer';
+
 const builder = SimulationBuilder.new({
-  apiEndpoint: 'https://api.stxer.xyz', // Default stxer API endpoint
-  stacksNodeAPI: 'https://api.hiro.so', // Default Stacks API endpoint
-  network: 'mainnet' // or 'testnet'
+  apiEndpoint: STXER_API_TESTNET, // Use testnet
+  stacksNodeAPI: 'https://api.testnet.hiro.so', // Testnet Stacks API
+  network: 'testnet',
+  skipTracing: false, // Set to true for faster simulations (no debug UI support)
 });
 ```
 
+For `getTip` and AST operations:
+
+```typescript
+import { getTip, getContractAST, parseContract, STXER_API_MAINNET } from 'stxer';
+
+const tip = await getTip({
+  stxerApi: STXER_API_MAINNET // Optional, defaults to mainnet
+});
+
+const ast = await getContractAST({
+  contractId: 'SP...contract',
+  stxerApi: STXER_API_MAINNET // Optional
+});
+```
+
+## API Reference
+
+### Constants
+
+- `STXER_API_MAINNET` - Mainnet API endpoint (https://api.stxer.xyz)
+- `STXER_API_TESTNET` - Testnet API endpoint (https://testnet-api.stxer.xyz)
+- `DEFAULT_STXER_API` - Default API endpoint (same as STXER_API_MAINNET)
+
+### Simulation Builder (High-Level)
+
+- `SimulationBuilder.new(options)` - Create a new simulation builder
+- `builder.useBlockHeight(height)` - Set block height for simulation
+- `builder.withSender(address)` - Set default sender address
+
+**Transaction Steps:**
+- `builder.addContractCall(params)` - Add a contract call step
+- `builder.addSTXTransfer(params)` - Add an STX transfer step
+- `builder.addContractDeploy(params)` - Add a contract deployment step
+
+**V2 Step Types:**
+- `builder.addEvalCode(contractId, code)` - Add arbitrary code evaluation (with state modification)
+- `builder.addSetContractCode(params)` - Directly set contract code without transaction
+- `builder.addReads(reads[])` - Batch read operations in a single step
+- `builder.addTenureExtend()` - Extend tenure (resets execution cost)
+
+**Execution:**
+- `builder.run()` - Execute the simulation and return simulation ID
+
+### Programmatic Simulation APIs (Low-Level)
+
+**Instant Simulation:**
+- `instantSimulation(request, options?)` - Simulate a single transaction without session
+
+**Session Management:**
+- `createSimulationSession(options?, apiOptions?)` - Create a new simulation session
+- `submitSimulationSteps(sessionId, request, options?)` - Submit steps to a session
+- `getSimulationResult(sessionId, options?)` - Get full simulation results
+- `simulationBatchReads(sessionId, request, options?)` - Batch reads from simulation state
+
+### Chain Tip
+
+- `getTip(options?)` - Fetch current chain tip information
+
+### Contract AST
+
+- `getContractAST({ contractId, stxerApi? })` - Fetch on-chain contract AST
+- `parseContract({ sourceCode, contractId, clarityVersion?, epoch?, stxerApi? })` - Parse source code to AST
+
+### Batch Operations
+
+- `batchRead(reads, options?)` - Execute batch read operations
+- `new BatchProcessor({ stxerAPIEndpoint?, batchDelayMs })` - Create a batch processor
+
+### Clarity API
+
+- `callReadonly(params)` - Call a read-only contract function
+- `readVariable(params)` - Read a contract variable
+- `readMap(params)` - Read from a contract map
+
 ## Support
 
 This product is made possible through community support. Consider supporting the development:

package/dist/ast.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 { ClarityEpoch, ContractAST } from './types';
+export interface AstOptions {
+    stxerApi?: string;
+}
+export interface GetContractAstOptions extends AstOptions {
+    contractId: string;
+}
+/**
+ * Fetch the AST for an on-chain contract.
+ * @param options - Contract ID and optional API endpoint
+ * @returns The contract AST with metadata
+ */
+export declare function getContractAST(options: GetContractAstOptions): Promise<ContractAST>;
+export interface ParseContractOptions extends AstOptions {
+    sourceCode: string;
+    contractId: string;
+    clarityVersion?: '1' | '2' | '3' | '4';
+    epoch?: ClarityEpoch;
+}
+/**
+ * Parse contract source code into an AST.
+ * @param options - Source code, contract ID, and optional configuration
+ * @returns The parsed contract AST
+ */
+export declare function parseContract(options: ParseContractOptions): Promise<ContractAST>;
+export type { ClarityAbi, ClarityAbiFunction, ClarityAbiFungibleToken, ClarityAbiMap, ClarityAbiNonFungibleToken, ClarityAbiType, ClarityAbiVariable, ClarityEpoch, ClarityVersion, ContractAST, SymbolicExpression, } from './types';

package/dist/clarity-api.d.ts

@@ -1,6 +1,6 @@
 import type { ClarityAbiFunction, ClarityAbiMap, ClarityAbiVariable, TContractPrincipal, TPrincipal } from 'clarity-abi';
 import type { InferMapValueType, InferReadMapParameterType, InferReadonlyCallParameterType, InferReadonlyCallResultType, InferReadVariableParameterType, InferVariableType } from 'ts-clarity';
-import { BatchProcessor } from './BatchProcessor';
+import { BatchProcessor } from './batch-processor';
 export type ReadonlyCallRuntimeOptions = {
     sender?: TPrincipal;
     contract: TContractPrincipal;

package/dist/constants.d.ts

@@ -0,0 +1,9 @@
+/**
+ * API endpoint constants
+ */
+/** Default stxer API endpoint for mainnet */
+export declare const STXER_API_MAINNET = "https://api.stxer.xyz";
+/** stxer API endpoint for testnet */
+export declare const STXER_API_TESTNET = "https://testnet-api.stxer.xyz";
+/** Default stxer API endpoint (mainnet) */
+export declare const DEFAULT_STXER_API = "https://api.stxer.xyz";

package/dist/index.d.ts

@@ -1,3 +1,8 @@
-export * from './BatchAPI';
+export * from './ast';
+export * from './batch-api';
 export * from './clarity-api';
+export * from './constants';
 export * from './simulation';
+export { type CreateSessionOptions, createSimulationSession, getSimulationResult, instantSimulation, type SimulationApiOptions, simulationBatchReads, submitSimulationSteps, } from './simulation-api';
+export * from './tip';
+export * from './types';

package/dist/simulation-api.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Low-level programmatic simulation APIs
+ *
+ * These functions provide direct access to the stxer V2 simulation endpoints
+ * for programmatic use cases where you need more control than SimulationBuilder provides.
+ */
+import type { InstantSimulationRequest, InstantSimulationResponse, SimulationBatchReadsRequest, SimulationBatchReadsResponse, SimulationResult, SubmitSimulationStepsRequest, SubmitSimulationStepsResponse } from './types';
+/**
+ * Options for API calls
+ */
+export interface SimulationApiOptions {
+    /** stxer API endpoint (default: https://api.stxer.xyz) */
+    stxerApi?: string;
+}
+/**
+ * Create simulation session options
+ */
+export interface CreateSessionOptions {
+    /** Block height for simulation (optional, uses tip if not provided) */
+    block_height?: number;
+    /** Block hash corresponding to block_height */
+    block_hash?: string;
+    /** Skip debug tracing for faster simulations */
+    skip_tracing?: boolean;
+}
+/**
+ * Instantly simulate a transaction
+ *
+ * This is useful for apps/wallets to get the result of a transaction before sending it.
+ * Lightweight - no debug tracing information.
+ *
+ * @param request - Instant simulation request
+ * @param options - API options
+ * @returns Instant simulation response with receipt and optional reads
+ *
+ * @example
+ * ```typescript
+ * import { instantSimulation } from 'stxer';
+ *
+ * const result = await instantSimulation({
+ *   transaction: '0x...',
+ *   block_height: 130818,
+ *   block_hash: '0x...',
+ *   reads: [
+ *     { DataVar: ['SP...contract', 'my-var'] },
+ *     { StxBalance: 'SP...' }
+ *   ]
+ * });
+ * console.log(result.receipt.result);
+ * ```
+ */
+export declare function instantSimulation(request: InstantSimulationRequest, options?: SimulationApiOptions): Promise<InstantSimulationResponse>;
+/**
+ * Create a new simulation session
+ *
+ * A session allows you to run multiple steps in a forked chain state.
+ *
+ * @param options - Create session options
+ * @param apiOptions - API options
+ * @returns Session ID
+ *
+ * @example
+ * ```typescript
+ * import { createSimulationSession } from 'stxer';
+ *
+ * const sessionId = await createSimulationSession({
+ *   block_height: 130818,
+ *   skip_tracing: false
+ * });
+ * ```
+ */
+export declare function createSimulationSession(options?: CreateSessionOptions, apiOptions?: SimulationApiOptions): Promise<string>;
+/**
+ * Submit steps to a simulation session
+ *
+ * Steps are executed sequentially in the session's forked chain state.
+ *
+ * @param sessionId - Simulation session ID
+ * @param request - Steps to submit
+ * @param options - API options
+ * @returns Array of step results
+ *
+ * @example
+ * ```typescript
+ * import { submitSimulationSteps } from 'stxer';
+ *
+ * const results = await submitSimulationSteps(sessionId, {
+ *   steps: [
+ *     { Transaction: '0x...' },
+ *     { Eval: ['SP...', '', 'SP...contract', '(var-get my-var)'] },
+ *     { Reads: [{ DataVar: ['SP...contract', 'my-var'] }] }
+ *   ]
+ * });
+ * ```
+ */
+export declare function submitSimulationSteps(sessionId: string, request: SubmitSimulationStepsRequest, options?: SimulationApiOptions): Promise<SubmitSimulationStepsResponse>;
+/**
+ * Get simulation session results
+ *
+ * Returns the full simulation result including metadata and all step results.
+ *
+ * @param sessionId - Simulation session ID
+ * @param options - API options
+ * @returns Complete simulation result
+ *
+ * @example
+ * ```typescript
+ * import { getSimulationResult } from 'stxer';
+ *
+ * const result = await getSimulationResult(sessionId);
+ * console.log(result.metadata);
+ * console.log(result.steps);
+ * ```
+ */
+export declare function getSimulationResult(sessionId: string, options?: SimulationApiOptions): Promise<SimulationResult>;
+/**
+ * Batch reads from a simulation session
+ *
+ * Similar to sidecar batch reads, but reads from the simulation's forked state.
+ *
+ * @param sessionId - Simulation session ID
+ * @param request - Batch reads request
+ * @param options - API options
+ * @returns Batch read results
+ *
+ * @example
+ * ```typescript
+ * import { simulationBatchReads } from 'stxer';
+ *
+ * const results = await simulationBatchReads(sessionId, {
+ *   vars: [['SP...contract', 'my-var']],
+ *   maps: [['SP...contract', 'my-map', '0x...']],
+ *   stx: ['SP...']
+ * });
+ * console.log(results.vars);
+ * ```
+ */
+export declare function simulationBatchReads(sessionId: string, request: SimulationBatchReadsRequest, options?: SimulationApiOptions): Promise<SimulationBatchReadsResponse>;

package/dist/simulation.d.ts

@@ -1,20 +1,21 @@
 import { type StacksNetworkName } from '@stacks/network';
-import { type ClarityValue, ClarityVersion, type StacksTransactionWire } from '@stacks/transactions';
+import { type ClarityValue, ClarityVersion } from '@stacks/transactions';
+import type { ReadStep } from './types';
 export interface SimulationEval {
     contract_id: string;
     code: string;
 }
-export declare function runEval({ contract_id, code }: SimulationEval): import("@stacks/transactions").TupleCV<import("@stacks/transactions").TupleData<import("@stacks/transactions").BufferCV | import("@stacks/transactions").UIntCV>>;
-export declare function runSimulation(apiEndpoint: string, block_hash: string, block_height: number, txs: (StacksTransactionWire | SimulationEval)[]): Promise<string>;
 interface SimulationBuilderOptions {
     apiEndpoint?: string;
     stacksNodeAPI?: string;
     network?: StacksNetworkName | string;
+    skipTracing?: boolean;
 }
 export declare class SimulationBuilder {
     private apiEndpoint;
     private stacksNodeAPI;
     private network;
+    private skipTracing;
     private constructor();
     static new(options?: SimulationBuilderOptions): SimulationBuilder;
     private block;
@@ -46,8 +47,15 @@ export declare class SimulationBuilder {
     addEvalCode(inside_contract_id: string, code: string): this;
     addMapRead(contract_id: string, map: string, key: string): this;
     addVarRead(contract_id: string, variable: string): this;
+    addSetContractCode(params: {
+        contract_id: string;
+        source_code: string;
+        clarity_version?: ClarityVersion;
+    }): this;
+    addReads(reads: ReadStep[]): this;
+    addTenureExtend(): this;
     private getBlockInfo;
     run(): Promise<string>;
     pipe(transform: (builder: SimulationBuilder) => SimulationBuilder): SimulationBuilder;
 }
-export {};
+export type { CreateSimulationRequest, ExecutionCost, InstantSimulationRequest, InstantSimulationResponse, ReadResult, ReadStep, SimulationMetadata, SimulationResult, SimulationStepInput, TransactionReceipt, } from './types';