stxer 0.6.1 → 0.8.0

package/dist/bitcoin.d.ts

@@ -0,0 +1,121 @@
+/**
+ * SHA-256. Pure-JS via `@noble/hashes` so this module works in
+ * browsers, Node, and Bun without a polyfill.
+ */
+export declare function sha256(data: Uint8Array): Uint8Array;
+/** Bitcoin-style double-sha256 used for txids, block hashes, and Merkle nodes. */
+export declare function sha256d(data: Uint8Array): Uint8Array;
+/** Decode a hex string (with or without `0x` prefix). */
+export declare function hexToBytes(s: string): Uint8Array;
+/** Lower-case hex (no `0x` prefix). */
+export declare function bytesToHex(b: Uint8Array): string;
+/** P2WPKH output script: `OP_0 <20-byte pubkey-hash>`. */
+export declare function p2wpkhScript(pubKeyHash20: Uint8Array): Uint8Array;
+/** P2PKH output script: `OP_DUP OP_HASH160 <hash> OP_EQUALVERIFY OP_CHECKSIG`. */
+export declare function p2pkhScript(pubKeyHash20: Uint8Array): Uint8Array;
+/**
+ * `OP_RETURN <data>` output. Used to embed peg-in metadata
+ * (recipient principal, marker bytes, etc.). Bitcoin's standard relay
+ * limit caps `data` at 80 bytes; this helper rejects > 75 to leave
+ * room for the prefix bytes.
+ */
+export declare function opReturnScript(data: Uint8Array): Uint8Array;
+export interface BitcoinTxInput {
+    /** 32-byte previous txid in *internal byte order* (raw `sha256d`). */
+    prevTxid: Uint8Array;
+    prevVout: number;
+    /** Script signature bytes. Empty for segwit-style inputs. */
+    scriptSig: Uint8Array;
+    /** Sequence number; default `0xfffffffd`. */
+    sequence?: number;
+}
+export interface BitcoinTxOutput {
+    /** Satoshi amount. */
+    value: bigint;
+    /** Locking script — use {@link p2wpkhScript} / {@link p2pkhScript} / {@link opReturnScript}. */
+    scriptPubKey: Uint8Array;
+}
+export interface ForgedBitcoinTx {
+    /** Wire-encoded non-witness tx bytes (this is what the txid is computed over). */
+    bytes: Uint8Array;
+    /** Canonical txid: `sha256d(bytes)`. Internal byte order. */
+    txid: Uint8Array;
+    /** Display-form (reversed) txid — what block explorers render. */
+    txidDisplay: Uint8Array;
+}
+/**
+ * Build a non-witness Bitcoin transaction (legacy serialization). The
+ * txid is `sha256d` of the returned `bytes`. Use this form when you
+ * only need to assert SPV inclusion; segwit witness data is irrelevant
+ * to the txid.
+ *
+ * Wire format:
+ * ```
+ *   4  version (LE)
+ *   varint  in-count
+ *   per-input: 32 prev_txid + 4 prev_vout + varint script-len + script + 4 sequence
+ *   varint  out-count
+ *   per-output: 8 value (LE) + varint script-len + script
+ *   4  locktime (LE)
+ * ```
+ */
+export declare function forgeBitcoinTx(opts: {
+    version?: number;
+    inputs: BitcoinTxInput[];
+    outputs: BitcoinTxOutput[];
+    locktime?: number;
+}): ForgedBitcoinTx;
+export interface BitcoinHeader {
+    version: number;
+    prevHash: Uint8Array;
+    merkleRoot: Uint8Array;
+    timestamp: number;
+    bits: number;
+    nonce: number;
+}
+export interface BuiltBitcoinHeader {
+    /** Raw 80-byte serialized header. */
+    header: Uint8Array;
+    /**
+     * Display-form hash (`reverse(sha256d(header))`) — what the Stacks
+     * chainstate stores as `BurnchainHeaderHash`. Pass this as the
+     * `burn_header_hashes[i]` override on `addAdvanceBlocks`.
+     */
+    hash: Uint8Array;
+    /** Raw `sha256d(header)` (internal byte order). */
+    rawHash: Uint8Array;
+}
+/**
+ * Build an 80-byte Bitcoin block header. `prevHash` and `merkleRoot`
+ * are written in internal byte order (raw `sha256d` output) — matching
+ * the on-chain `clarity-bitcoin-v1-07` parser convention.
+ */
+export declare function buildBitcoinHeader(h: Partial<BitcoinHeader> & {
+    merkleRoot: Uint8Array;
+}): BuiltBitcoinHeader;
+/**
+ * Single-tx Merkle root — the txid itself. Bitcoin's Merkle tree
+ * convention does NOT pre-hash the leaves; for a one-tx block the
+ * root equals the txid.
+ */
+export declare function singleTxMerkleRoot(txid: Uint8Array): Uint8Array;
+/**
+ * Compute a Bitcoin Merkle proof for `txid` at `index` in `txids`
+ * (transaction order within the block). Returns the sibling hashes
+ * from leaf to root.
+ *
+ * Bitcoin convention:
+ *  - Leaves are the txids themselves (no pre-hashing).
+ *  - Inner nodes are `sha256d(left || right)`.
+ *  - Odd levels duplicate the last entry to pair.
+ */
+export declare function merkleProof(txids: Uint8Array[], index: number): {
+    proof: Uint8Array[];
+    root: Uint8Array;
+};
+/**
+ * Verify a Bitcoin Merkle proof against `root`. Returns `true` iff the
+ * proof reconstructs the root from `txid` at `index`. Matches the
+ * on-chain `verify-merkle-proof` semantic.
+ */
+export declare function verifyMerkleProof(txid: Uint8Array, index: number, proof: Uint8Array[], root: Uint8Array): boolean;

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 export * from './ast';
 export * from './batch-api';
+export * from './bitcoin';
 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 './simulation-api';
 export * from './tip';
+export * from './transaction';
 export * from './types';

package/dist/simulation-api.d.ts

@@ -4,7 +4,30 @@
  * 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';
+import type { InstantSimulationRequest, InstantSimulationResponse, SimulationBatchReadsRequest, SimulationBatchReadsResponse, SimulationResult, SimulationTipResponse, SubmitSimulationStepsRequest, SubmitSimulationStepsResponse, U64 } from './types';
+/**
+ * Server-side error markers. `simulation_busy` ↔ HTTP 409,
+ * `simulation_outdated` ↔ HTTP 410. Other errors keep `marker = null`.
+ */
+export type SimulationErrorMarker = 'simulation_busy' | 'simulation_outdated' | null;
+/**
+ * Thrown by the simulation-api fetch wrappers when the API responds
+ * with a non-2xx status. `status` carries the wire HTTP code so
+ * callers can branch on 409 (busy) / 410 (outdated) without parsing
+ * the message string. `marker` is the server-side classification
+ * extracted from the body prefix (`simulation_busy:` /
+ * `simulation_outdated:`).
+ *
+ * Pre-0.8.0 SDKs threw a plain `Error` whose message embedded the body
+ * text; that lossy form is still used for the message field here so
+ * existing log scrapers keep working.
+ */
+export declare class SimulationError extends Error {
+    readonly status: number;
+    readonly marker: SimulationErrorMarker;
+    readonly body: string;
+    constructor(operation: string, status: number, body: string);
+}
 /**
  * Options for API calls
  */
@@ -16,8 +39,11 @@ export interface SimulationApiOptions {
  * Create simulation session options
  */
 export interface CreateSessionOptions {
-    /** Block height for simulation (optional, uses tip if not provided) */
-    block_height?: number;
+    /**
+     * Block height for simulation (optional, uses tip if not provided).
+     * u64 — `number | string`; see {@link U64}.
+     */
+    block_height?: U64;
     /** Block hash corresponding to block_height */
     block_hash?: string;
     /** Skip debug tracing for faster simulations */
@@ -113,6 +139,29 @@ export declare function submitSimulationSteps(sessionId: string, request: Submit
  * ```
  */
 export declare function getSimulationResult(sessionId: string, options?: SimulationApiOptions): Promise<SimulationResult>;
+/**
+ * Get the current tip of a simulation session.
+ *
+ * Returns the latest synthetic tip when at least one `AdvanceBlocks`
+ * step has run (`synthetic: true`, includes `vrf_seed` and
+ * `tenure_change`). Returns the parent metadata pinned at session
+ * start otherwise (`synthetic: false`, `vrf_seed` and `tenure_change`
+ * omitted).
+ *
+ * Backed by `GET /devtools/v2/simulations/{id}/tip`. Older simulator
+ * builds that predate this route respond 404.
+ *
+ * @example
+ * ```typescript
+ * import { getSimulationTip } from 'stxer';
+ *
+ * const tip = await getSimulationTip(sessionId);
+ * if (tip.synthetic) {
+ *   console.log('synthetic tip vrf_seed:', tip.vrf_seed);
+ * }
+ * ```
+ */
+export declare function getSimulationTip(sessionId: string, options?: SimulationApiOptions): Promise<SimulationTipResponse>;
 /**
  * Batch reads from a simulation session
  *

package/dist/simulation.d.ts

@@ -1,6 +1,8 @@
 import { type StacksNetworkName } from '@stacks/network';
-import { type ClarityValue, ClarityVersion } from '@stacks/transactions';
-import type { ReadStep } from './types';
+import { type ClarityValue, ClarityVersion, PostConditionMode } from '@stacks/transactions';
+import { type SimulationApiOptions } from './simulation-api';
+import { type ContractCallTxArgs } from './transaction';
+import type { AdvanceBlocksRequest, ReadStep, TenureExtendCause, TransactionReceipt } from './types';
 export interface SimulationEval {
     contract_id: string;
     code: string;
@@ -53,9 +55,74 @@ export declare class SimulationBuilder {
         clarity_version?: ClarityVersion;
     }): this;
     addReads(reads: ReadStep[]): this;
-    addTenureExtend(): this;
+    /**
+     * Add a `TenureExtend` step. Defaults to `cause: 'Extended'` (full
+     * cost reset) — equivalent in server-side behavior to the legacy
+     * zero-arg call.
+     *
+     * Pass an explicit `TenureExtendCause` to reset only one SIP-034
+     * dimension (`ExtendedRuntime` / `ExtendedReadCount` / etc.).
+     *
+     * On the wire SDK 0.8.0 emits the modern `{ TenureExtend: { cause } }`
+     * shape. The server still parses the legacy `[]` shape for any
+     * caller emitting raw step objects.
+     */
+    addTenureExtend(cause?: TenureExtendCause): this;
+    /**
+     * Synthesize bitcoin and stacks blocks on top of the simulation's
+     * pinned parent tip. Used to model burn-block / tenure boundaries
+     * (bridge contracts, time-locked redemptions, locked-STX unlock).
+     *
+     * The simulator validates the request shape; older simulator builds
+     * that don't yet support `AdvanceBlocks` reject this variant with
+     * HTTP 400.
+     *
+     * @example
+     * ```typescript
+     * builder.addAdvanceBlocks({
+     *   bitcoin_blocks: 1,
+     *   stacks_blocks_per_bitcoin: 1,
+     * });
+     * ```
+     */
+    addAdvanceBlocks(request: AdvanceBlocksRequest): this;
     private getBlockInfo;
     run(): Promise<string>;
     pipe(transform: (builder: SimulationBuilder) => SimulationBuilder): SimulationBuilder;
 }
+export interface CallContractResult {
+    /** Decoded Clarity result (e.g. `(ok true)`, `(err u100)`, `u5`). */
+    result: string;
+    /** Hex-encoded raw Clarity result (SIP-005). */
+    resultHex: string;
+    /** VM-level error message, if any (e.g. arithmetic overflow). */
+    vmError: string | null;
+    /** True when one or more post-conditions tripped. */
+    pcAborted: boolean;
+    /** Full upstream receipt for callers that need more detail. */
+    receipt: TransactionReceipt;
+}
+/**
+ * Build, submit, and decode a contract-call transaction. The caller
+ * supplies the principal to use as `tx-sender`; nonce is auto-fetched
+ * via {@link getNonce} unless `nonce` is explicitly provided.
+ */
+export declare function callContract(sessionId: string, args: Omit<ContractCallTxArgs, 'nonce'> & {
+    nonce?: number;
+    postConditionMode?: PostConditionMode;
+}, options?: SimulationApiOptions): Promise<CallContractResult>;
+/**
+ * Read the SIP-010 / hBTC-style `(get-balance principal)` value.
+ * Returns 0n if the read returns `(err …)`. Throws on infra failures.
+ */
+export declare function getFtBalance(sessionId: string, contractId: string, principal: string, options?: SimulationApiOptions): Promise<bigint>;
+/** Read a principal's STX balance (uSTX) from a simulation session. */
+export declare function getStxBalance(sessionId: string, principal: string, options?: SimulationApiOptions): Promise<bigint>;
+/** Read a principal's current nonce. Returns 0n if never seen. */
+export declare function getNonce(sessionId: string, principal: string, options?: SimulationApiOptions): Promise<bigint>;
+/**
+ * Read a Clarity data variable. Returns the decoded `ClarityValue`,
+ * or throws if the read failed.
+ */
+export declare function readDataVar(sessionId: string, contractId: string, varName: string, options?: SimulationApiOptions): Promise<ClarityValue>;
 export type { CreateSimulationRequest, ExecutionCost, InstantSimulationRequest, InstantSimulationResponse, ReadResult, ReadStep, SimulationMetadata, SimulationResult, SimulationStepInput, TransactionReceipt, } from './types';