stxer 0.4.5 → 0.7.0

package/src/ast.ts

@@ -0,0 +1,120 @@
+/**
+ * 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 { DEFAULT_STXER_API } from './constants';
+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 async function getContractAST(
+  options: GetContractAstOptions,
+): Promise<ContractAST> {
+  const url = `${options.stxerApi ?? DEFAULT_STXER_API}/contracts/${options.contractId}`;
+
+  const response = await fetch(url, {
+    method: 'GET',
+    headers: {
+      Accept: 'application/json',
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch contract AST: ${response.status} ${response.statusText}`,
+    );
+  }
+
+  const text = await response.text();
+  if (!text.startsWith('{')) {
+    throw new Error(`Invalid response from contracts endpoint: ${text}`);
+  }
+
+  return JSON.parse(text) as 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 async function parseContract(
+  options: ParseContractOptions,
+): Promise<ContractAST> {
+  const url = `${options.stxerApi ?? DEFAULT_STXER_API}/contracts:parse`;
+
+  const payload: {
+    contract_id: string;
+    source_code: string;
+    clarity_version?: string;
+    epoch?: string;
+  } = {
+    contract_id: options.contractId,
+    source_code: options.sourceCode,
+  };
+
+  if (options.clarityVersion !== undefined) {
+    payload.clarity_version = options.clarityVersion;
+  }
+  if (options.epoch !== undefined) {
+    payload.epoch = options.epoch;
+  }
+
+  const response = await fetch(url, {
+    method: 'POST',
+    body: JSON.stringify(payload),
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `Failed to parse contract: ${response.status} ${response.statusText}`,
+    );
+  }
+
+  const text = await response.text();
+  if (!text.startsWith('{')) {
+    throw new Error(`Invalid response from contract parse endpoint: ${text}`);
+  }
+
+  return JSON.parse(text) as ContractAST;
+}
+
+// Re-export AST-related types for convenience
+export type {
+  ClarityAbi,
+  ClarityAbiFunction,
+  ClarityAbiFungibleToken,
+  ClarityAbiMap,
+  ClarityAbiNonFungibleToken,
+  ClarityAbiType,
+  ClarityAbiVariable,
+  ClarityEpoch,
+  ClarityVersion,
+  ContractAST,
+  SymbolicExpression,
+} from './types';

package/src/{BatchAPI.ts → batch-api.ts}

@@ -31,7 +31,8 @@ export interface BatchReads {
 }
 
 export interface BatchReadsResult {
-  tip: string;
+  /** Index block hash the batch ran against. Matches the wire field name. */
+  index_block_hash: string;
   vars: (ClarityValue | Error)[];
   maps: (ClarityValue | Error)[];
   readonly: (ClarityValue | Error)[];
@@ -44,10 +45,10 @@ export interface BatchApiOptions {
 const DEFAULT_STXER_API = 'https://api.stxer.xyz';
 
 function convertResults(
-  rs: ({ Ok: string } | { Err: string })[],
+  rs: ({ Ok: string } | { Err: string })[] | undefined,
 ): (ClarityValue | Error)[] {
   const results: (ClarityValue | Error)[] = [];
-  for (const v of rs) {
+  for (const v of rs ?? []) {
     if ('Ok' in v) {
       results.push(deserializeCV(v.Ok));
     } else {
@@ -123,14 +124,14 @@ export async function batchRead(
   }
 
   const rs = JSON.parse(text) as {
-    tip: string;
-    vars: ({ Ok: string } | { Err: string })[];
-    maps: ({ Ok: string } | { Err: string })[];
-    readonly: ({ Ok: string } | { Err: string })[];
+    index_block_hash: string;
+    vars?: ({ Ok: string } | { Err: string })[];
+    maps?: ({ Ok: string } | { Err: string })[];
+    readonly?: ({ Ok: string } | { Err: string })[];
   };
 
   return {
-    tip: rs.tip,
+    index_block_hash: rs.index_block_hash,
     vars: convertResults(rs.vars),
     maps: convertResults(rs.maps),
     readonly: convertResults(rs.readonly),

package/src/{BatchProcessor.ts → batch-processor.ts}

@@ -10,7 +10,7 @@ import {
   contractPrincipalCV,
   type OptionalCV,
 } from '@stacks/transactions';
-import { type BatchReads, batchRead } from './BatchAPI';
+import { type BatchReads, batchRead } from './batch-api';
 
 export interface ReadOnlyRequest {
   mode: 'readonly';

package/src/clarity-api.ts

@@ -19,7 +19,7 @@ import type {
   InferVariableType,
 } from 'ts-clarity';
 import { decodeAbi, encodeAbi } from 'ts-clarity';
-import { BatchProcessor } from './BatchProcessor';
+import { BatchProcessor } from './batch-processor';
 
 // Shared processor instance with default settings
 const defaultProcessor = new BatchProcessor({

package/src/constants.ts

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

package/src/index.ts

@@ -1,3 +1,12 @@
-export * from './BatchAPI';
+// `dts build` (rollup-plugin-typescript2 + babel) does not enable
+// `@babel/preset-typescript` on the entry, so inline `type` specifiers
+// inside `export {}` and standalone `export type {}` blocks both crash
+// the build (babel falls back to flow grammar). Stick with `export *`.
+export * from './ast';
+export * from './batch-api';
 export * from './clarity-api';
+export * from './constants';
 export * from './simulation';
+export * from './simulation-api';
+export * from './tip';
+export * from './types';

package/src/simulation-api.ts

@@ -0,0 +1,273 @@
+/**
+ * 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 { DEFAULT_STXER_API } from './constants';
+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 async function instantSimulation(
+  request: InstantSimulationRequest,
+  options: SimulationApiOptions = {},
+): Promise<InstantSimulationResponse> {
+  const apiEndpoint = options.stxerApi ?? DEFAULT_STXER_API;
+
+  const response = await fetch(
+    `${apiEndpoint}/devtools/v2/simulations:instant`,
+    {
+      method: 'POST',
+      body: JSON.stringify(request),
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      },
+    },
+  );
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Instant simulation failed: ${text}`);
+  }
+
+  return response.json() as 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 async function createSimulationSession(
+  options: CreateSessionOptions = {},
+  apiOptions: SimulationApiOptions = {},
+): Promise<string> {
+  const apiEndpoint = apiOptions.stxerApi ?? DEFAULT_STXER_API;
+
+  const response = await fetch(`${apiEndpoint}/devtools/v2/simulations`, {
+    method: 'POST',
+    body: JSON.stringify(options),
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+    },
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Failed to create simulation session: ${text}`);
+  }
+
+  const result = (await response.json()) as { id: string };
+  return result.id;
+}
+
+/**
+ * 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 async function submitSimulationSteps(
+  sessionId: string,
+  request: SubmitSimulationStepsRequest,
+  options: SimulationApiOptions = {},
+): Promise<SubmitSimulationStepsResponse> {
+  const apiEndpoint = options.stxerApi ?? DEFAULT_STXER_API;
+
+  const response = await fetch(
+    `${apiEndpoint}/devtools/v2/simulations/${sessionId}`,
+    {
+      method: 'POST',
+      body: JSON.stringify(request),
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      },
+    },
+  );
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Failed to submit simulation steps: ${text}`);
+  }
+
+  return response.json() as 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 async function getSimulationResult(
+  sessionId: string,
+  options: SimulationApiOptions = {},
+): Promise<SimulationResult> {
+  const apiEndpoint = options.stxerApi ?? DEFAULT_STXER_API;
+
+  const response = await fetch(
+    `${apiEndpoint}/devtools/v2/simulations/${sessionId}`,
+    {
+      method: 'GET',
+      headers: {
+        Accept: 'application/json',
+      },
+    },
+  );
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Failed to get simulation result: ${text}`);
+  }
+
+  return response.json() as 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 async function simulationBatchReads(
+  sessionId: string,
+  request: SimulationBatchReadsRequest,
+  options: SimulationApiOptions = {},
+): Promise<SimulationBatchReadsResponse> {
+  const apiEndpoint = options.stxerApi ?? DEFAULT_STXER_API;
+
+  const response = await fetch(
+    `${apiEndpoint}/devtools/v2/simulations/${sessionId}/reads`,
+    {
+      method: 'POST',
+      body: JSON.stringify(request),
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      },
+    },
+  );
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Failed to batch reads from simulation: ${text}`);
+  }
+
+  return response.json() as Promise<SimulationBatchReadsResponse>;
+}