stxer 0.4.3 → 0.6.1

package/src/types.ts

@@ -0,0 +1,392 @@
+/**
+ * Type definitions for stxer-api V2 endpoints
+ * Hand-written types based on OpenAPI spec at https://api.stxer.xyz/openapi.json
+ */
+
+// =============================================================================
+// Sidecar Tip Types
+// =============================================================================
+
+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;
+}
+
+// =============================================================================
+// AST Types
+// =============================================================================
+
+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;
+}
+
+// =============================================================================
+// V2 Simulation Types
+// =============================================================================
+
+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;
+}
+
+// Read step types
+export interface MapEntryStep {
+  MapEntry: [string, string, string]; // [contract_id, map_name, key_hex]
+}
+
+export interface DataVarStep {
+  DataVar: [string, string]; // [contract_id, variable_name]
+}
+
+export interface EvalReadonlyStep {
+  EvalReadonly: [string, string, string, string]; // [sender, sponsor, contract_id, code]
+}
+
+export interface StxBalanceStep {
+  StxBalance: string; // principal
+}
+
+export interface FtBalanceStep {
+  FtBalance: [string, string, string]; // [contract_id, token_name, principal]
+}
+
+export interface FtSupplyStep {
+  FtSupply: [string, string]; // [contract_id, token_name]
+}
+
+export interface NonceStep {
+  Nonce: string; // principal
+}
+
+export type ReadStep =
+  | MapEntryStep
+  | DataVarStep
+  | EvalReadonlyStep
+  | StxBalanceStep
+  | FtBalanceStep
+  | FtSupplyStep
+  | NonceStep;
+
+export interface ReadOkResult {
+  Ok: string; // clarity value hex OR number string for balances/nonces
+}
+
+export interface ReadErrResult {
+  Err: string;
+}
+
+export type ReadResult = ReadOkResult | ReadErrResult;
+
+// Simulation step types (summary format from GET /devtools/v2/simulations/{id})
+export interface TransactionStepSummary {
+  Transaction: string; // tx hex
+  TxId: string;
+  Result: {
+    Transaction: TransactionOkResult | TransactionErrResult;
+  };
+  ExecutionCost: ExecutionCost;
+}
+
+export interface ReadsStepSummary {
+  Reads: ReadStep[];
+  Result: {
+    Reads: ReadResult[];
+  };
+}
+
+export interface SetContractCodeStepSummary {
+  SetContractCode: [string, string, number]; // [contract_id, code, clarity_version]
+  Result: {
+    SetContractCode: { Ok: null } | { Err: string };
+  };
+}
+
+export interface EvalStepSummary {
+  Eval: [string, string, string, string]; // [sender, sponsor, contract_id, code]
+  Result: {
+    Eval: { Ok: string } | { Err: string };
+  };
+}
+
+export interface TenureExtendStepSummary {
+  Result: {
+    TenureExtend: ExecutionCost;
+  };
+}
+
+export type SimulationStepSummary =
+  | TransactionStepSummary
+  | ReadsStepSummary
+  | SetContractCodeStepSummary
+  | EvalStepSummary
+  | TenureExtendStepSummary;
+
+// Simulation metadata
+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;
+}
+
+// Full simulation result
+export interface SimulationResult {
+  metadata: SimulationMetadata;
+  steps: SimulationStepSummary[];
+}
+
+// Create session request
+export interface CreateSimulationRequest {
+  block_height?: number;
+  block_hash?: string;
+  skip_tracing?: boolean;
+}
+
+export interface CreateSimulationResponse {
+  id: string;
+}
+
+// Submit steps request
+export type SimulationStepInput =
+  | { Transaction: string } // tx hex
+  | { Eval: [string, string, string, string] } // [sender, sponsor, contract_id, code]
+  | { SetContractCode: [string, string, number] } // [contract_id, code, clarity_version]
+  | { Reads: ReadStep[] }
+  | { TenureExtend: [] };
+
+export interface SubmitSimulationStepsRequest {
+  steps: SimulationStepInput[];
+}
+
+export interface SubmitSimulationStepsResponse {
+  steps: SimulationStepSummary[];
+}
+
+// Batch reads from simulation
+export interface SimulationBatchReadsRequest {
+  vars?: [string, string][]; // [contract_id, variable_name]
+  maps?: [string, string, string][]; // [contract_id, map_name, key_hex]
+  readonly?: Array<string | [string, string, string, string]>; // [contract_id, function_name, ...args]
+  readonly_with_sender?: Array<
+    // [sender, sponsor, contract_id, function_name, ...args]
+    [string, string, string, string, ...string[]]
+  >;
+  stx?: string[]; // principals
+  nonces?: string[]; // principals
+  ft_balance?: [string, string][]; // [token_identifier, principal]
+  ft_supply?: [string, string][]; // [contract_id, ft_token_name]
+}
+
+export interface SimulationBatchReadsResponse {
+  vars: ReadResult[];
+  maps: ReadResult[];
+  readonly: ReadResult[];
+  readonly_with_sender: ReadResult[];
+  stx: ReadResult[];
+  nonces: ReadResult[];
+  ft_balance: ReadResult[];
+  ft_supply: ReadResult[];
+}
+
+// Instant simulation
+export interface InstantSimulationRequest {
+  transaction: string; // tx hex
+  block_height?: number;
+  block_hash?: string;
+  reads?: ReadStep[];
+}
+
+export interface InstantSimulationResponse {
+  reads?: ReadResult[];
+  receipt: TransactionReceipt;
+}

package/dist/sample/counter.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/sample/read.d.ts

@@ -1 +0,0 @@
-export {};

package/src/sample/counter.ts

@@ -1,42 +0,0 @@
-import { uintCV } from '@stacks/transactions';
-import { SimulationBuilder } from '..';
-
-const sender = 'SP212Y5JKN59YP3GYG07K3S8W5SSGE4KH6B5STXER';
-
-const test = () =>
-  SimulationBuilder.new()
-    .withSender(sender)
-    .addContractDeploy({
-      contract_name: 'test-simulation',
-      source_code: `
-;; counter example
-(define-data-var counter uint u0)
-
-(define-public (increment (delta uint))
-  (begin
-    (var-set counter (+ (var-get counter) delta))
-    (ok (var-get counter))))
-
-(define-public (decrement)
-  (begin 
-    (var-set counter (- (var-get counter) u1))
-    (ok (var-get counter))))
-
-(define-read-only (get-counter)
-  (ok (var-get counter)))
-`,
-    })
-    .addEvalCode(`${sender}.test-simulation`, '(get-counter)')
-    .addContractCall({
-      contract_id: `${sender}.test-simulation`,
-      function_name: 'increment',
-      function_args: [uintCV(10)],
-    })
-    .addEvalCode(`${sender}.test-simulation`, '(get-counter)')
-    .run();
-
-if (require.main === module) {
-  (async () => {
-    await test();
-  })().catch(console.error);
-}

package/src/sample/read.ts

@@ -1,139 +0,0 @@
-import {
-  contractPrincipalCV,
-  principalCV,
-  tupleCV,
-  uintCV,
-} from '@stacks/transactions';
-import { SIP010TraitABI } from 'clarity-abi/abis';
-import { unwrapResponse } from 'ts-clarity';
-import { batchRead } from '../BatchAPI';
-import { BatchProcessor } from '../BatchProcessor';
-import { callReadonly, readMap, readVariable } from '../clarity-api';
-
-async function batchReadsExample() {
-  const rs = await batchRead({
-    // index_block_hash:
-    //   'ce04817b9c6d90814ff9c06228d3a07d64335b1d9b01a233456fc304e34f7c0e', // block 373499
-    variables: [
-      {
-        contract: contractPrincipalCV(
-          'SP1Z92MPDQEWZXW36VX71Q25HKF5K2EPCJ304F275',
-          'liquidity-token-v5kbe3oqvac',
-        ),
-        variableName: 'balance-x',
-      },
-      {
-        contract: contractPrincipalCV(
-          'SP1Z92MPDQEWZXW36VX71Q25HKF5K2EPCJ304F275',
-          'liquidity-token-v5kbe3oqvac',
-        ),
-        variableName: 'balance-y',
-      },
-      {
-        contract: contractPrincipalCV(
-          'SP1Z92MPDQEWZXW36VX71Q25HKF5K2EPCJ304F275',
-          'liquidity-token-v5kbe3oqvac',
-        ),
-        variableName: 'something-not-exists',
-      },
-    ],
-    maps: [
-      {
-        contract: contractPrincipalCV(
-          'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM',
-          'amm-registry-v2-01',
-        ),
-        mapName: 'pools-data-map',
-        mapKey: tupleCV({
-          'token-x': principalCV(
-            'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-wstx-v2',
-          ),
-          'token-y': principalCV(
-            'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-alex',
-          ),
-          factor: uintCV(1e8),
-        }),
-      },
-      {
-        contract: contractPrincipalCV(
-          'SP1Y5YSTAHZ88XYK1VPDH24GY0HPX5J4JECTMY4A1',
-          'univ2-core',
-        ),
-        mapName: 'pools',
-        mapKey: uintCV(1),
-      },
-      {
-        contract: contractPrincipalCV(
-          'SP1Y5YSTAHZ88XYK1VPDH24GY0HPX5J4JECTMY4A1',
-          'contract-not-exists',
-        ),
-        mapName: 'pools',
-        mapKey: uintCV(1),
-      },
-    ],
-  });
-  console.log(rs);
-}
-
-async function batchQueueProcessorExample() {
-  const processor = new BatchProcessor({
-    stxerAPIEndpoint: 'https://api.stxer.xyz',
-    batchDelayMs: 1000,
-  });
-
-  const promiseA = processor.read({
-    mode: 'variable',
-    contractAddress: 'SP1Z92MPDQEWZXW36VX71Q25HKF5K2EPCJ304F275',
-    contractName: 'liquidity-token-v5kbe3oqvac',
-    variableName: 'balance-x',
-  });
-
-  const promiseB = processor.read({
-    mode: 'variable',
-    contractAddress: 'SP1Z92MPDQEWZXW36VX71Q25HKF5K2EPCJ304F275',
-    contractName: 'liquidity-token-v5kbe3oqvac',
-    variableName: 'balance-y',
-  });
-
-  const result = await Promise.all([promiseA, promiseB]);
-  console.log(result);
-}
-
-async function batchSip010Example() {
-  const supply = callReadonly({
-    abi: SIP010TraitABI.functions,
-    functionName: 'get-total-supply',
-    contract: 'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-alex',
-  }).then(unwrapResponse);
-  const balance = callReadonly({
-    abi: SIP010TraitABI.functions,
-    functionName: 'get-balance',
-    contract: 'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-alex',
-    args: {
-      who: 'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-vault-v2-01',
-    },
-  }).then(unwrapResponse);
-  const paused = readVariable({
-    abi: [{ name: 'paused', type: 'bool', access: 'variable' }],
-    variableName: 'paused',
-    contract: 'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-vault-v2-01',
-  });
-  const approved = readMap({
-    abi: [{ key: 'principal', name: 'approved-tokens', value: 'bool' }],
-    mapName: 'approved-tokens',
-    key: 'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.token-alex',
-    contract: 'SP102V8P0F7JX67ARQ77WEA3D3CFB5XW39REDT0AM.amm-vault-v2-01',
-  });
-  const result = await Promise.all([supply, balance, paused, approved]);
-  console.log(result);
-}
-
-async function main() {
-  await batchReadsExample();
-  await batchQueueProcessorExample();
-  await batchSip010Example();
-}
-
-if (require.main === module) {
-  main().catch(console.error);
-}