stxer 0.7.0 → 0.8.0

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 * 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';