stxer 0.4.5 → 0.6.1

package/dist/types.d.ts

@@ -0,0 +1,327 @@
+/**
+ * Type definitions for stxer-api V2 endpoints
+ * Hand-written types based on OpenAPI spec at https://api.stxer.xyz/openapi.json
+ */
+export interface TenureCost {
+    read_count: number;
+    read_length: number;
+    write_count: number;
+    write_length: number;
+    runtime: number;
+}
+export interface SidecarTip {
+    bitcoin_height: number;
+    block_hash: string;
+    block_height: number;
+    block_time: number;
+    burn_block_height: number;
+    burn_block_time: number;
+    consensus_hash: string;
+    index_block_hash: string;
+    is_nakamoto: boolean;
+    tenure_cost: TenureCost;
+    tenure_height: number;
+    sortition_id: string;
+    epoch_id: string;
+}
+export interface ClarityAbiType {
+    readonly?: {
+        type: ClarityAbiTypeName;
+        length?: number;
+    } | string;
+    tuple?: {
+        name: string;
+        type: ClarityAbiType;
+    }[];
+    list?: {
+        type: ClarityAbiType;
+        length: number;
+    };
+    buffer?: {
+        length: number;
+    };
+    string_ascii?: {
+        length: number;
+    };
+    string_utf8?: {
+        length: number;
+    };
+    principal?: [];
+    bool?: [];
+    int?: {
+        length: number;
+    };
+    uint?: {
+        length: number;
+    };
+    response?: {
+        ok: ClarityAbiType;
+        error: ClarityAbiType;
+    };
+    optional?: ClarityAbiType;
+    contract?: {
+        name: string;
+        address: string;
+    };
+}
+export type ClarityAbiTypeName = 'optional' | 'response' | 'bool' | 'int' | 'uint' | 'string-ascii' | 'string-utf8' | 'buff' | 'list' | 'tuple' | 'principal' | 'trait-reference' | 'contract';
+export interface ClarityAbiFunction {
+    name: string;
+    access: 'private' | 'public' | 'read_only';
+    args: Array<{
+        name: string;
+        type: ClarityAbiType;
+    }>;
+    outputs: {
+        type: ClarityAbiType;
+    };
+}
+export interface ClarityAbiVariable {
+    name: string;
+    access: 'variable' | 'constant';
+    type: ClarityAbiType;
+}
+export interface ClarityAbiMap {
+    name: string;
+    key: ClarityAbiType;
+    value: ClarityAbiType;
+}
+export interface ClarityAbiFungibleToken {
+    name: string;
+}
+export interface ClarityAbiNonFungibleToken {
+    name: string;
+    type: ClarityAbiType;
+}
+export type ClarityEpoch = 'Epoch10' | 'Epoch20' | 'Epoch2_05' | 'Epoch21' | 'Epoch22' | 'Epoch23' | 'Epoch24' | 'Epoch25' | 'Epoch30' | 'Epoch31' | 'Epoch32' | 'Epoch33' | 'Epoch34' | 'Epoch35';
+export type ClarityVersion = 'Clarity1' | 'Clarity2' | 'Clarity3' | 'Clarity4';
+export interface ClarityAbi {
+    functions: ClarityAbiFunction[];
+    variables: ClarityAbiVariable[];
+    maps: ClarityAbiMap[];
+    fungible_tokens: ClarityAbiFungibleToken[];
+    non_fungible_tokens: ClarityAbiNonFungibleToken[];
+    epoch: ClarityEpoch;
+    clarity_version: ClarityVersion;
+}
+export interface SymbolicExpressionField {
+    field: string;
+}
+export interface SymbolicExpressionTraitReference {
+    trait_reference: {
+        clarity_name: string;
+        trait_definition: string;
+        trait_definition_type: 'Defined' | 'Imported';
+    };
+}
+export interface SymbolicExpressionAtom {
+    atom: string;
+}
+export interface SymbolicExpressionAtomValue {
+    atom_value: string;
+}
+export interface SymbolicExpressionLiteralValue {
+    literal_value: string;
+}
+export interface SymbolicExpressionList {
+    list: SymbolicExpression[];
+}
+export type SymbolicExpression = {
+    id: number;
+    span: string;
+    expr: SymbolicExpressionAtom | SymbolicExpressionAtomValue | SymbolicExpressionLiteralValue | SymbolicExpressionList | SymbolicExpressionField | SymbolicExpressionTraitReference;
+    pre_comments?: Array<{
+        comment: string;
+        span: string;
+    }>;
+    post_comments?: Array<{
+        comment: string;
+        span: string;
+    }>;
+    end_line_comment?: string;
+};
+export interface ContractAST {
+    contract_identifier: string;
+    expressions: SymbolicExpression[];
+    top_level_expression_sorting: number[];
+    referenced_traits: Record<string, {
+        trait_definition: string;
+        trait_definition_type: 'Defined' | 'Imported';
+    }>;
+    implemented_traits: string[];
+    tx_id?: string;
+    canonical?: boolean;
+    contract_id?: string;
+    block_height?: number;
+    source_code?: string;
+    abi?: ClarityAbi;
+}
+export interface ExecutionCost {
+    read_count: number;
+    read_length: number;
+    write_count: number;
+    write_length: number;
+    runtime: number;
+}
+export interface TransactionReceipt {
+    result: string;
+    stx_burned: number;
+    tx_index: number;
+    vm_error: string | null;
+    post_condition_aborted: boolean;
+    costs: number;
+    execution_cost: ExecutionCost;
+    events: string[];
+}
+export interface TransactionOkResult {
+    Ok: TransactionReceipt;
+}
+export interface TransactionErrResult {
+    Err: string;
+}
+export interface MapEntryStep {
+    MapEntry: [string, string, string];
+}
+export interface DataVarStep {
+    DataVar: [string, string];
+}
+export interface EvalReadonlyStep {
+    EvalReadonly: [string, string, string, string];
+}
+export interface StxBalanceStep {
+    StxBalance: string;
+}
+export interface FtBalanceStep {
+    FtBalance: [string, string, string];
+}
+export interface FtSupplyStep {
+    FtSupply: [string, string];
+}
+export interface NonceStep {
+    Nonce: string;
+}
+export type ReadStep = MapEntryStep | DataVarStep | EvalReadonlyStep | StxBalanceStep | FtBalanceStep | FtSupplyStep | NonceStep;
+export interface ReadOkResult {
+    Ok: string;
+}
+export interface ReadErrResult {
+    Err: string;
+}
+export type ReadResult = ReadOkResult | ReadErrResult;
+export interface TransactionStepSummary {
+    Transaction: string;
+    TxId: string;
+    Result: {
+        Transaction: TransactionOkResult | TransactionErrResult;
+    };
+    ExecutionCost: ExecutionCost;
+}
+export interface ReadsStepSummary {
+    Reads: ReadStep[];
+    Result: {
+        Reads: ReadResult[];
+    };
+}
+export interface SetContractCodeStepSummary {
+    SetContractCode: [string, string, number];
+    Result: {
+        SetContractCode: {
+            Ok: null;
+        } | {
+            Err: string;
+        };
+    };
+}
+export interface EvalStepSummary {
+    Eval: [string, string, string, string];
+    Result: {
+        Eval: {
+            Ok: string;
+        } | {
+            Err: string;
+        };
+    };
+}
+export interface TenureExtendStepSummary {
+    Result: {
+        TenureExtend: ExecutionCost;
+    };
+}
+export type SimulationStepSummary = TransactionStepSummary | ReadsStepSummary | SetContractCodeStepSummary | EvalStepSummary | TenureExtendStepSummary;
+export interface SimulationMetadata {
+    ast_rules: 0 | 1;
+    block_height: number;
+    block_hash: string;
+    burn_block_height: number;
+    burn_block_hash: string;
+    consensus_hash: string;
+    epoch: string;
+    index_block_hash: string;
+    skip_tracing: boolean;
+    sortition_id: string;
+}
+export interface SimulationResult {
+    metadata: SimulationMetadata;
+    steps: SimulationStepSummary[];
+}
+export interface CreateSimulationRequest {
+    block_height?: number;
+    block_hash?: string;
+    skip_tracing?: boolean;
+}
+export interface CreateSimulationResponse {
+    id: string;
+}
+export type SimulationStepInput = {
+    Transaction: string;
+} | {
+    Eval: [string, string, string, string];
+} | {
+    SetContractCode: [string, string, number];
+} | {
+    Reads: ReadStep[];
+} | {
+    TenureExtend: [];
+};
+export interface SubmitSimulationStepsRequest {
+    steps: SimulationStepInput[];
+}
+export interface SubmitSimulationStepsResponse {
+    steps: SimulationStepSummary[];
+}
+export interface SimulationBatchReadsRequest {
+    vars?: [string, string][];
+    maps?: [string, string, string][];
+    readonly?: Array<string | [string, string, string, string]>;
+    readonly_with_sender?: Array<[
+        string,
+        string,
+        string,
+        string,
+        ...string[]
+    ]>;
+    stx?: string[];
+    nonces?: string[];
+    ft_balance?: [string, string][];
+    ft_supply?: [string, string][];
+}
+export interface SimulationBatchReadsResponse {
+    vars: ReadResult[];
+    maps: ReadResult[];
+    readonly: ReadResult[];
+    readonly_with_sender: ReadResult[];
+    stx: ReadResult[];
+    nonces: ReadResult[];
+    ft_balance: ReadResult[];
+    ft_supply: ReadResult[];
+}
+export interface InstantSimulationRequest {
+    transaction: string;
+    block_height?: number;
+    block_hash?: string;
+    reads?: ReadStep[];
+}
+export interface InstantSimulationResponse {
+    reads?: ReadResult[];
+    receipt: TransactionReceipt;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stxer",
-  "version": "0.4.5",
+  "version": "0.6.1",
   "license": "MIT",
   "author": "Kyle Fang",
   "repository": {
@@ -12,7 +12,9 @@
   "typings": "dist/index.d.ts",
   "files": [
     "dist",
-    "src"
+    "src",
+    "!src/sample",
+    "!dist/sample"
   ],
   "husky": {
     "hooks": {
@@ -42,21 +44,21 @@
     }
   ],
   "devDependencies": {
-    "@biomejs/biome": "^2.3.6",
-    "@size-limit/preset-small-lib": "^11.2.0",
+    "@biomejs/biome": "^2.3.11",
+    "@size-limit/preset-small-lib": "^12.0.0",
     "@tsconfig/recommended": "^1.0.13",
-    "@types/node": "^24.10.1",
+    "@types/node": "^25.0.9",
     "dts-cli": "^2.0.5",
     "husky": "^9.1.7",
-    "size-limit": "^11.2.0",
+    "size-limit": "^12.0.0",
     "tslib": "^2.8.1",
-    "tsx": "^4.20.6",
+    "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@stacks/network": "^7.2.0",
+    "@stacks/network": "^7.3.1",
     "@stacks/stacks-blockchain-api-types": "^7.14.1",
-    "@stacks/transactions": "^7.3.0",
+    "@stacks/transactions": "^7.3.1",
     "c32check": "^2.0.0",
     "clarity-abi": "^0.1.0",
     "ts-clarity": "^0.1.1"

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/{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,17 @@
-export * from './BatchAPI';
+export * from './ast';
+export * from './batch-api';
 export * from './clarity-api';
+export * from './constants';
 export * from './simulation';
+// Export simulation-api functions explicitly to avoid type conflicts
+export {
+  type CreateSessionOptions,
+  createSimulationSession,
+  getSimulationResult,
+  instantSimulation,
+  type SimulationApiOptions,
+  simulationBatchReads,
+  submitSimulationSteps,
+} from './simulation-api';
+export * from './tip';
+export * from './types';