stxer 0.7.0 → 0.8.0

package/dist/stxer.cjs.development.js

@@ -3,6 +3,7 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var transactions = require('@stacks/transactions');
+var sha2_js = require('@noble/hashes/sha2.js');
 var tsClarity = require('ts-clarity');
 var network = require('@stacks/network');
 var c32check = require('c32check');
@@ -37,6 +38,13 @@ function _asyncToGenerator(n) {
     });
   };
 }
+function _construct(t, e, r) {
+  if (_isNativeReflectConstruct()) return Reflect.construct.apply(null, arguments);
+  var o = [null];
+  o.push.apply(o, e);
+  var p = new (t.bind.apply(t, o))();
+  return r && _setPrototypeOf(p, r.prototype), p;
+}
 function _createForOfIteratorHelperLoose(r, e) {
   var t = "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"];
   if (t) return (t = t.call(r)).next.bind(t);
@@ -63,6 +71,29 @@ function _extends() {
     return n;
   }, _extends.apply(null, arguments);
 }
+function _getPrototypeOf(t) {
+  return _getPrototypeOf = Object.setPrototypeOf ? Object.getPrototypeOf.bind() : function (t) {
+    return t.__proto__ || Object.getPrototypeOf(t);
+  }, _getPrototypeOf(t);
+}
+function _inheritsLoose(t, o) {
+  t.prototype = Object.create(o.prototype), t.prototype.constructor = t, _setPrototypeOf(t, o);
+}
+function _isNativeFunction(t) {
+  try {
+    return -1 !== Function.toString.call(t).indexOf("[native code]");
+  } catch (n) {
+    return "function" == typeof t;
+  }
+}
+function _isNativeReflectConstruct() {
+  try {
+    var t = !Boolean.prototype.valueOf.call(Reflect.construct(Boolean, [], function () {}));
+  } catch (t) {}
+  return (_isNativeReflectConstruct = function () {
+    return !!t;
+  })();
+}
 function _regenerator() {
   /*! regenerator-runtime -- Copyright (c) 2014-present, Facebook, Inc. -- license (MIT): https://github.com/babel/babel/blob/main/packages/babel-helpers/LICENSE */
   var e,
@@ -171,6 +202,11 @@ function _regeneratorDefine(e, r, n, t) {
     }) : e[r] = n : (o("next", 0), o("throw", 1), o("return", 2));
   }, _regeneratorDefine(e, r, n, t);
 }
+function _setPrototypeOf(t, e) {
+  return _setPrototypeOf = Object.setPrototypeOf ? Object.setPrototypeOf.bind() : function (t, e) {
+    return t.__proto__ = e, t;
+  }, _setPrototypeOf(t, e);
+}
 function _unsupportedIterableToArray(r, a) {
   if (r) {
     if ("string" == typeof r) return _arrayLikeToArray(r, a);
@@ -178,6 +214,28 @@ function _unsupportedIterableToArray(r, a) {
     return "Object" === t && r.constructor && (t = r.constructor.name), "Map" === t || "Set" === t ? Array.from(r) : "Arguments" === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t) ? _arrayLikeToArray(r, a) : void 0;
   }
 }
+function _wrapNativeSuper(t) {
+  var r = "function" == typeof Map ? new Map() : void 0;
+  return _wrapNativeSuper = function (t) {
+    if (null === t || !_isNativeFunction(t)) return t;
+    if ("function" != typeof t) throw new TypeError("Super expression must either be null or a function");
+    if (void 0 !== r) {
+      if (r.has(t)) return r.get(t);
+      r.set(t, Wrapper);
+    }
+    function Wrapper() {
+      return _construct(t, arguments, _getPrototypeOf(this).constructor);
+    }
+    return Wrapper.prototype = Object.create(t.prototype, {
+      constructor: {
+        value: Wrapper,
+        enumerable: !1,
+        writable: !0,
+        configurable: !0
+      }
+    }), _setPrototypeOf(Wrapper, t);
+  }, _wrapNativeSuper(t);
+}
 
 /**
  * API endpoint constants
@@ -383,6 +441,273 @@ function _batchRead() {
   return _batchRead.apply(this, arguments);
 }
 
+// ============================================================================
+// Hashing primitives
+// ============================================================================
+/**
+ * SHA-256. Pure-JS via `@noble/hashes` so this module works in
+ * browsers, Node, and Bun without a polyfill.
+ */
+function sha256(data) {
+  return sha2_js.sha256(data);
+}
+/** Bitcoin-style double-sha256 used for txids, block hashes, and Merkle nodes. */
+function sha256d(data) {
+  return sha256(sha256(data));
+}
+// ============================================================================
+// Hex encoding
+// ============================================================================
+/** Decode a hex string (with or without `0x` prefix). */
+function hexToBytes(s) {
+  var t = s.toLowerCase().replace(/^0x/, '');
+  if (t.length % 2 !== 0) throw new Error('odd-length hex');
+  var out = new Uint8Array(t.length / 2);
+  for (var i = 0; i < out.length; i++) {
+    out[i] = Number.parseInt(t.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+/** Lower-case hex (no `0x` prefix). */
+function bytesToHex(b) {
+  return Array.from(b).map(function (x) {
+    return x.toString(16).padStart(2, '0');
+  }).join('');
+}
+// ============================================================================
+// Bitcoin script builders
+// ============================================================================
+/** P2WPKH output script: `OP_0 <20-byte pubkey-hash>`. */
+function p2wpkhScript(pubKeyHash20) {
+  if (pubKeyHash20.length !== 20) {
+    throw new Error('pubKeyHash must be 20 bytes');
+  }
+  var out = new Uint8Array(22);
+  out[0] = 0x00; // OP_0
+  out[1] = 0x14; // pushdata length 20
+  out.set(pubKeyHash20, 2);
+  return out;
+}
+/** P2PKH output script: `OP_DUP OP_HASH160 <hash> OP_EQUALVERIFY OP_CHECKSIG`. */
+function p2pkhScript(pubKeyHash20) {
+  if (pubKeyHash20.length !== 20) {
+    throw new Error('pubKeyHash must be 20 bytes');
+  }
+  var out = new Uint8Array(25);
+  out[0] = 0x76; // OP_DUP
+  out[1] = 0xa9; // OP_HASH160
+  out[2] = 0x14; // pushdata 20
+  out.set(pubKeyHash20, 3);
+  out[23] = 0x88; // OP_EQUALVERIFY
+  out[24] = 0xac; // OP_CHECKSIG
+  return out;
+}
+/**
+ * `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.
+ */
+function opReturnScript(data) {
+  if (data.length > 75) {
+    throw new Error("OP_RETURN data too long: " + data.length);
+  }
+  var out = new Uint8Array(2 + data.length);
+  out[0] = 0x6a; // OP_RETURN
+  out[1] = data.length; // direct push
+  out.set(data, 2);
+  return out;
+}
+/**
+ * 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)
+ * ```
+ */
+function forgeBitcoinTx(opts) {
+  var _opts$version, _opts$locktime;
+  var chunks = [];
+  var u32le = function u32le(n) {
+    var b = new Uint8Array(4);
+    new DataView(b.buffer).setUint32(0, n >>> 0, true);
+    return b;
+  };
+  var u64le = function u64le(n) {
+    var b = new Uint8Array(8);
+    var view = new DataView(b.buffer);
+    view.setUint32(0, Number(n & 0xffffffffn), true);
+    view.setUint32(4, Number(n >> 32n & 0xffffffffn), true);
+    return b;
+  };
+  var varint = function varint(n) {
+    if (n < 0xfd) return new Uint8Array([n]);
+    if (n <= 0xffff) {
+      var b = new Uint8Array(3);
+      b[0] = 0xfd;
+      new DataView(b.buffer).setUint16(1, n, true);
+      return b;
+    }
+    if (n <= 0xffffffff) {
+      var _b = new Uint8Array(5);
+      _b[0] = 0xfe;
+      new DataView(_b.buffer).setUint32(1, n, true);
+      return _b;
+    }
+    throw new Error("varint too large: " + n);
+  };
+  chunks.push(u32le((_opts$version = opts.version) != null ? _opts$version : 2));
+  chunks.push(varint(opts.inputs.length));
+  for (var _iterator = _createForOfIteratorHelperLoose(opts.inputs), _step; !(_step = _iterator()).done;) {
+    var _i$sequence;
+    var i = _step.value;
+    if (i.prevTxid.length !== 32) {
+      throw new Error('prevTxid must be 32 bytes');
+    }
+    chunks.push(i.prevTxid);
+    chunks.push(u32le(i.prevVout));
+    chunks.push(varint(i.scriptSig.length));
+    chunks.push(i.scriptSig);
+    chunks.push(u32le((_i$sequence = i.sequence) != null ? _i$sequence : 0xfffffffd));
+  }
+  chunks.push(varint(opts.outputs.length));
+  for (var _iterator2 = _createForOfIteratorHelperLoose(opts.outputs), _step2; !(_step2 = _iterator2()).done;) {
+    var o = _step2.value;
+    chunks.push(u64le(o.value));
+    chunks.push(varint(o.scriptPubKey.length));
+    chunks.push(o.scriptPubKey);
+  }
+  chunks.push(u32le((_opts$locktime = opts.locktime) != null ? _opts$locktime : 0));
+  var total = chunks.reduce(function (s, c) {
+    return s + c.length;
+  }, 0);
+  var bytes = new Uint8Array(total);
+  var off = 0;
+  for (var _i = 0, _chunks = chunks; _i < _chunks.length; _i++) {
+    var c = _chunks[_i];
+    bytes.set(c, off);
+    off += c.length;
+  }
+  var txid = sha256d(bytes);
+  var txidDisplay = reverseBytes(txid);
+  return {
+    bytes: bytes,
+    txid: txid,
+    txidDisplay: txidDisplay
+  };
+}
+/**
+ * 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.
+ */
+function buildBitcoinHeader(h) {
+  var _h$version, _h$prevHash, _h$timestamp, _h$bits, _h$nonce;
+  var out = new Uint8Array(80);
+  var view = new DataView(out.buffer);
+  view.setUint32(0, (_h$version = h.version) != null ? _h$version : 0x20000000, true);
+  out.set((_h$prevHash = h.prevHash) != null ? _h$prevHash : new Uint8Array(32), 4);
+  out.set(h.merkleRoot, 36);
+  view.setUint32(68, (_h$timestamp = h.timestamp) != null ? _h$timestamp : Math.floor(Date.now() / 1000), true);
+  view.setUint32(72, (_h$bits = h.bits) != null ? _h$bits : 0x1d00ffff, true);
+  view.setUint32(76, (_h$nonce = h.nonce) != null ? _h$nonce : 0, true);
+  var rawHash = sha256d(out);
+  return {
+    header: out,
+    hash: reverseBytes(rawHash),
+    rawHash: rawHash
+  };
+}
+// ============================================================================
+// Merkle proofs (Bitcoin convention)
+// ============================================================================
+/**
+ * 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.
+ */
+function singleTxMerkleRoot(txid) {
+  return new Uint8Array(txid);
+}
+/**
+ * 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.
+ */
+function merkleProof(txids, index) {
+  if (index < 0 || index >= txids.length) {
+    throw new Error("merkleProof: index " + index + " out of range " + txids.length);
+  }
+  var level = txids.map(function (t) {
+    return new Uint8Array(t);
+  });
+  var proof = [];
+  var i = index;
+  while (level.length > 1) {
+    if (level.length % 2 === 1) level.push(level[level.length - 1]);
+    var sibling = level[i ^ 1];
+    proof.push(sibling);
+    var next = [];
+    for (var j = 0; j < level.length; j += 2) {
+      next.push(sha256d(concatBytes(level[j], level[j + 1])));
+    }
+    level = next;
+    i = Math.floor(i / 2);
+  }
+  return {
+    proof: proof,
+    root: level[0]
+  };
+}
+/**
+ * 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.
+ */
+function verifyMerkleProof(txid, index, proof, root) {
+  var h = new Uint8Array(txid);
+  var i = index;
+  for (var _iterator3 = _createForOfIteratorHelperLoose(proof), _step3; !(_step3 = _iterator3()).done;) {
+    var sibling = _step3.value;
+    h = (i & 1) === 0 ? sha256d(concatBytes(h, sibling)) : sha256d(concatBytes(sibling, h));
+    i = Math.floor(i / 2);
+  }
+  return bytesEqual(h, root);
+}
+// ============================================================================
+// Internal byte helpers
+// ============================================================================
+function reverseBytes(a) {
+  var out = new Uint8Array(a.length);
+  for (var i = 0; i < a.length; i++) out[i] = a[a.length - 1 - i];
+  return out;
+}
+function concatBytes(a, b) {
+  var out = new Uint8Array(a.length + b.length);
+  out.set(a, 0);
+  out.set(b, a.length);
+  return out;
+}
+function bytesEqual(a, b) {
+  if (a.length !== b.length) return false;
+  for (var i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
 var BatchProcessor = /*#__PURE__*/function () {
   function BatchProcessor(options) {
     var _options$stxerAPIEndp;
@@ -696,6 +1021,43 @@ function _readVariable() {
   return _readVariable.apply(this, arguments);
 }
 
+/**
+ * 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.
+ */
+var SimulationError = /*#__PURE__*/function (_Error) {
+  function SimulationError(operation, status, body) {
+    var _this;
+    var marker = detectMarker(body);
+    _this = _Error.call(this, operation + " (HTTP " + status + "): " + body) || this;
+    _this.status = void 0;
+    _this.marker = void 0;
+    _this.body = void 0;
+    _this.name = 'SimulationError';
+    _this.status = status;
+    _this.marker = marker;
+    _this.body = body;
+    return _this;
+  }
+  _inheritsLoose(SimulationError, _Error);
+  return SimulationError;
+}(/*#__PURE__*/_wrapNativeSuper(Error));
+function detectMarker(body) {
+  if (body.includes('simulation_busy:')) return 'simulation_busy';
+  if (body.includes('simulation_outdated:')) return 'simulation_outdated';
+  return null;
+}
+function throwSimulationError(_x, _x2) {
+  return _throwSimulationError.apply(this, arguments);
+}
 /**
  * Instantly simulate a transaction
  *
@@ -722,7 +1084,25 @@ function _readVariable() {
  * console.log(result.receipt.result);
  * ```
  */
-function instantSimulation(_x, _x2) {
+function _throwSimulationError() {
+  _throwSimulationError = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee(operation, response) {
+    var text;
+    return _regenerator().w(function (_context) {
+      while (1) switch (_context.n) {
+        case 0:
+          _context.n = 1;
+          return response.text();
+        case 1:
+          text = _context.v;
+          throw new SimulationError(operation, response.status, text);
+        case 2:
+          return _context.a(2);
+      }
+    }, _callee);
+  }));
+  return _throwSimulationError.apply(this, arguments);
+}
+function instantSimulation(_x3, _x4) {
   return _instantSimulation.apply(this, arguments);
 }
 /**
@@ -745,17 +1125,17 @@ function instantSimulation(_x, _x2) {
  * ```
  */
 function _instantSimulation() {
-  _instantSimulation = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee(request, options) {
+  _instantSimulation = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee2(request, options) {
     var _options$stxerApi;
-    var apiEndpoint, response, text;
-    return _regenerator().w(function (_context) {
-      while (1) switch (_context.n) {
+    var apiEndpoint, response;
+    return _regenerator().w(function (_context2) {
+      while (1) switch (_context2.n) {
         case 0:
           if (options === void 0) {
             options = {};
           }
           apiEndpoint = (_options$stxerApi = options.stxerApi) != null ? _options$stxerApi : DEFAULT_STXER_API$1;
-          _context.n = 1;
+          _context2.n = 1;
           return fetch(apiEndpoint + "/devtools/v2/simulations:instant", {
             method: 'POST',
             body: JSON.stringify(request),
@@ -765,24 +1145,21 @@ function _instantSimulation() {
             }
           });
         case 1:
-          response = _context.v;
+          response = _context2.v;
           if (response.ok) {
-            _context.n = 3;
+            _context2.n = 2;
             break;
           }
-          _context.n = 2;
-          return response.text();
+          _context2.n = 2;
+          return throwSimulationError('Instant simulation failed', response);
         case 2:
-          text = _context.v;
-          throw new Error("Instant simulation failed: " + text);
-        case 3:
-          return _context.a(2, response.json());
+          return _context2.a(2, response.json());
       }
-    }, _callee);
+    }, _callee2);
   }));
   return _instantSimulation.apply(this, arguments);
 }
-function createSimulationSession(_x3, _x4) {
+function createSimulationSession(_x5, _x6) {
   return _createSimulationSession.apply(this, arguments);
 }
 /**
@@ -809,11 +1186,11 @@ function createSimulationSession(_x3, _x4) {
  * ```
  */
 function _createSimulationSession() {
-  _createSimulationSession = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee2(options, apiOptions) {
+  _createSimulationSession = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee3(options, apiOptions) {
     var _apiOptions$stxerApi;
-    var apiEndpoint, response, text, result;
-    return _regenerator().w(function (_context2) {
-      while (1) switch (_context2.n) {
+    var apiEndpoint, response, result;
+    return _regenerator().w(function (_context3) {
+      while (1) switch (_context3.n) {
         case 0:
           if (options === void 0) {
             options = {};
@@ -822,7 +1199,7 @@ function _createSimulationSession() {
             apiOptions = {};
           }
           apiEndpoint = (_apiOptions$stxerApi = apiOptions.stxerApi) != null ? _apiOptions$stxerApi : DEFAULT_STXER_API$1;
-          _context2.n = 1;
+          _context3.n = 1;
           return fetch(apiEndpoint + "/devtools/v2/simulations", {
             method: 'POST',
             body: JSON.stringify(options),
@@ -832,28 +1209,25 @@ function _createSimulationSession() {
             }
           });
         case 1:
-          response = _context2.v;
+          response = _context3.v;
           if (response.ok) {
-            _context2.n = 3;
+            _context3.n = 2;
             break;
           }
-          _context2.n = 2;
-          return response.text();
+          _context3.n = 2;
+          return throwSimulationError('Failed to create simulation session', response);
         case 2:
-          text = _context2.v;
-          throw new Error("Failed to create simulation session: " + text);
-        case 3:
-          _context2.n = 4;
+          _context3.n = 3;
           return response.json();
-        case 4:
-          result = _context2.v;
-          return _context2.a(2, result.id);
+        case 3:
+          result = _context3.v;
+          return _context3.a(2, result.id);
       }
-    }, _callee2);
+    }, _callee3);
   }));
   return _createSimulationSession.apply(this, arguments);
 }
-function submitSimulationSteps(_x5, _x6, _x7) {
+function submitSimulationSteps(_x7, _x8, _x9) {
   return _submitSimulationSteps.apply(this, arguments);
 }
 /**
@@ -875,17 +1249,17 @@ function submitSimulationSteps(_x5, _x6, _x7) {
  * ```
  */
 function _submitSimulationSteps() {
-  _submitSimulationSteps = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee3(sessionId, request, options) {
+  _submitSimulationSteps = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee4(sessionId, request, options) {
     var _options$stxerApi2;
-    var apiEndpoint, response, text;
-    return _regenerator().w(function (_context3) {
-      while (1) switch (_context3.n) {
+    var apiEndpoint, response;
+    return _regenerator().w(function (_context4) {
+      while (1) switch (_context4.n) {
         case 0:
           if (options === void 0) {
             options = {};
           }
           apiEndpoint = (_options$stxerApi2 = options.stxerApi) != null ? _options$stxerApi2 : DEFAULT_STXER_API$1;
-          _context3.n = 1;
+          _context4.n = 1;
           return fetch(apiEndpoint + "/devtools/v2/simulations/" + sessionId, {
             method: 'POST',
             body: JSON.stringify(request),
@@ -895,26 +1269,81 @@ function _submitSimulationSteps() {
             }
           });
         case 1:
-          response = _context3.v;
+          response = _context4.v;
           if (response.ok) {
-            _context3.n = 3;
+            _context4.n = 2;
             break;
           }
-          _context3.n = 2;
-          return response.text();
+          _context4.n = 2;
+          return throwSimulationError('Failed to submit simulation steps', response);
         case 2:
-          text = _context3.v;
-          throw new Error("Failed to submit simulation steps: " + text);
-        case 3:
-          return _context3.a(2, response.json());
+          return _context4.a(2, response.json());
       }
-    }, _callee3);
+    }, _callee4);
   }));
   return _submitSimulationSteps.apply(this, arguments);
 }
-function getSimulationResult(_x8, _x9) {
+function getSimulationResult(_x0, _x1) {
   return _getSimulationResult.apply(this, arguments);
 }
+/**
+ * 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);
+ * }
+ * ```
+ */
+function _getSimulationResult() {
+  _getSimulationResult = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee5(sessionId, options) {
+    var _options$stxerApi3;
+    var apiEndpoint, response;
+    return _regenerator().w(function (_context5) {
+      while (1) switch (_context5.n) {
+        case 0:
+          if (options === void 0) {
+            options = {};
+          }
+          apiEndpoint = (_options$stxerApi3 = options.stxerApi) != null ? _options$stxerApi3 : DEFAULT_STXER_API$1;
+          _context5.n = 1;
+          return fetch(apiEndpoint + "/devtools/v2/simulations/" + sessionId, {
+            method: 'GET',
+            headers: {
+              Accept: 'application/json'
+            }
+          });
+        case 1:
+          response = _context5.v;
+          if (response.ok) {
+            _context5.n = 2;
+            break;
+          }
+          _context5.n = 2;
+          return throwSimulationError('Failed to get simulation result', response);
+        case 2:
+          return _context5.a(2, response.json());
+      }
+    }, _callee5);
+  }));
+  return _getSimulationResult.apply(this, arguments);
+}
+function getSimulationTip(_x10, _x11) {
+  return _getSimulationTip.apply(this, arguments);
+}
 /**
  * Batch reads from a simulation session
  *
@@ -937,57 +1366,54 @@ function getSimulationResult(_x8, _x9) {
  * console.log(results.vars);
  * ```
  */
-function _getSimulationResult() {
-  _getSimulationResult = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee4(sessionId, options) {
-    var _options$stxerApi3;
-    var apiEndpoint, response, text;
-    return _regenerator().w(function (_context4) {
-      while (1) switch (_context4.n) {
+function _getSimulationTip() {
+  _getSimulationTip = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee6(sessionId, options) {
+    var _options$stxerApi4;
+    var apiEndpoint, response;
+    return _regenerator().w(function (_context6) {
+      while (1) switch (_context6.n) {
         case 0:
           if (options === void 0) {
             options = {};
           }
-          apiEndpoint = (_options$stxerApi3 = options.stxerApi) != null ? _options$stxerApi3 : DEFAULT_STXER_API$1;
-          _context4.n = 1;
-          return fetch(apiEndpoint + "/devtools/v2/simulations/" + sessionId, {
+          apiEndpoint = (_options$stxerApi4 = options.stxerApi) != null ? _options$stxerApi4 : DEFAULT_STXER_API$1;
+          _context6.n = 1;
+          return fetch(apiEndpoint + "/devtools/v2/simulations/" + sessionId + "/tip", {
             method: 'GET',
             headers: {
               Accept: 'application/json'
             }
           });
         case 1:
-          response = _context4.v;
+          response = _context6.v;
           if (response.ok) {
-            _context4.n = 3;
+            _context6.n = 2;
             break;
           }
-          _context4.n = 2;
-          return response.text();
+          _context6.n = 2;
+          return throwSimulationError('Failed to get simulation tip', response);
         case 2:
-          text = _context4.v;
-          throw new Error("Failed to get simulation result: " + text);
-        case 3:
-          return _context4.a(2, response.json());
+          return _context6.a(2, response.json());
       }
-    }, _callee4);
+    }, _callee6);
   }));
-  return _getSimulationResult.apply(this, arguments);
+  return _getSimulationTip.apply(this, arguments);
 }
-function simulationBatchReads(_x0, _x1, _x10) {
+function simulationBatchReads(_x12, _x13, _x14) {
   return _simulationBatchReads.apply(this, arguments);
 }
 function _simulationBatchReads() {
-  _simulationBatchReads = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee5(sessionId, request, options) {
-    var _options$stxerApi4;
-    var apiEndpoint, response, text;
-    return _regenerator().w(function (_context5) {
-      while (1) switch (_context5.n) {
+  _simulationBatchReads = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee7(sessionId, request, options) {
+    var _options$stxerApi5;
+    var apiEndpoint, response;
+    return _regenerator().w(function (_context7) {
+      while (1) switch (_context7.n) {
         case 0:
           if (options === void 0) {
             options = {};
           }
-          apiEndpoint = (_options$stxerApi4 = options.stxerApi) != null ? _options$stxerApi4 : DEFAULT_STXER_API$1;
-          _context5.n = 1;
+          apiEndpoint = (_options$stxerApi5 = options.stxerApi) != null ? _options$stxerApi5 : DEFAULT_STXER_API$1;
+          _context7.n = 1;
           return fetch(apiEndpoint + "/devtools/v2/simulations/" + sessionId + "/reads", {
             method: 'POST',
             body: JSON.stringify(request),
@@ -997,24 +1423,29 @@ function _simulationBatchReads() {
             }
           });
         case 1:
-          response = _context5.v;
+          response = _context7.v;
           if (response.ok) {
-            _context5.n = 3;
+            _context7.n = 2;
             break;
           }
-          _context5.n = 2;
-          return response.text();
+          _context7.n = 2;
+          return throwSimulationError('Failed to batch reads from simulation', response);
         case 2:
-          text = _context5.v;
-          throw new Error("Failed to batch reads from simulation: " + text);
-        case 3:
-          return _context5.a(2, response.json());
+          return _context7.a(2, response.json());
       }
-    }, _callee5);
+    }, _callee7);
   }));
   return _simulationBatchReads.apply(this, arguments);
 }
 
+/**
+ * Override the spending condition's `signer` (and `hashMode`) so the
+ * simulator treats `tx-sender` as `sender`.
+ *
+ * Single-sig and multi-sig flavours are both handled — the multi-sig
+ * spending condition is rebuilt with empty signature fields because
+ * the simulator never validates signatures.
+ */
 function setSender(tx, sender) {
   var _c32addressDecode = c32check.c32addressDecode(sender),
     addressVersion = _c32addressDecode[0],
@@ -1039,9 +1470,86 @@ function setSender(tx, sender) {
         };
         break;
       }
+    default:
+      throw new Error("unsupported address version: " + addressVersion);
   }
   return tx;
 }
+/**
+ * Build an unsigned contract-call transaction with `sender` patched
+ * in via {@link setSender}, then return the serialized hex (no `0x`
+ * prefix). Drop the result directly into `{ Transaction: <hex> }`.
+ *
+ * @example
+ * ```typescript
+ * import { Cl } from '@stacks/transactions';
+ * import { buildUnsignedContractCallHex } from 'stxer';
+ *
+ * const txHex = await buildUnsignedContractCallHex({
+ *   sender: 'SP3573...',
+ *   contract: 'SM3VDXK...sbtc-deposit',
+ *   functionName: 'complete-deposit-wrapper',
+ *   functionArgs: [Cl.bufferFromHex(txid), Cl.uint(0), Cl.uint(amount), ...],
+ *   nonce: 5,
+ * });
+ * await submitSimulationSteps(sim, { steps: [{ Transaction: txHex }] });
+ * ```
+ */
+function buildUnsignedContractCallHex(_x) {
+  return _buildUnsignedContractCallHex.apply(this, arguments);
+}
+/**
+ * Build a `Cl.contractPrincipal` from a `"SP….name"` id string.
+ * Trips on standard principals or malformed ids — those should use
+ * `Cl.principal` directly.
+ */
+function _buildUnsignedContractCallHex() {
+  _buildUnsignedContractCallHex = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee(args) {
+    var _args$fee, _args$network, _args$postConditionMo;
+    var _args$contract$split, contractAddress, contractName, tx;
+    return _regenerator().w(function (_context) {
+      while (1) switch (_context.n) {
+        case 0:
+          _args$contract$split = args.contract.split('.'), contractAddress = _args$contract$split[0], contractName = _args$contract$split[1];
+          if (contractName) {
+            _context.n = 1;
+            break;
+          }
+          throw new Error("bad contract id \"" + args.contract + "\" \u2014 expected SP\u2026.name");
+        case 1:
+          _context.n = 2;
+          return transactions.makeUnsignedContractCall({
+            contractAddress: contractAddress,
+            contractName: contractName,
+            functionName: args.functionName,
+            functionArgs: args.functionArgs,
+            fee: (_args$fee = args.fee) != null ? _args$fee : 1000,
+            nonce: args.nonce,
+            // Dummy 33-byte compressed pubkey. The simulator never validates
+            // the signature; setSender overwrites the derived signer hash.
+            publicKey: '0'.repeat(66),
+            network: (_args$network = args.network) != null ? _args$network : 'mainnet',
+            postConditionMode: (_args$postConditionMo = args.postConditionMode) != null ? _args$postConditionMo : transactions.PostConditionMode.Allow
+          });
+        case 2:
+          tx = _context.v;
+          setSender(tx, args.sender);
+          return _context.a(2, transactions.serializeTransaction(tx));
+      }
+    }, _callee);
+  }));
+  return _buildUnsignedContractCallHex.apply(this, arguments);
+}
+function ftPrincipal(contractId) {
+  var _contractId$split = contractId.split('.'),
+    addr = _contractId$split[0],
+    name = _contractId$split[1];
+  if (!name) {
+    throw new Error("bad contract id \"" + contractId + "\" \u2014 expected SP\u2026.name");
+  }
+  return transactions.Cl.contractPrincipal(addr, name);
+}
+
 var SimulationBuilder = /*#__PURE__*/function () {
   function SimulationBuilder(options) {
     var _options$network, _options$apiEndpoint, _options$stacksNodeAP, _options$skipTracing;
@@ -1052,8 +1560,7 @@ var SimulationBuilder = /*#__PURE__*/function () {
     this.stacksNodeAPI = void 0;
     this.network = void 0;
     this.skipTracing = void 0;
-    // biome-ignore lint/style/useNumberNamespace: ignore this
-    this.block = NaN;
+    this.block = Number.NaN;
     this.sender = '';
     this.steps = [];
     this.network = (_options$network = options.network) != null ? _options$network : 'mainnet';
@@ -1110,7 +1617,7 @@ var SimulationBuilder = /*#__PURE__*/function () {
     this.steps.push(_extends({}, params, {
       deployer: (_params$deployer = params.deployer) != null ? _params$deployer : this.sender,
       fee: (_params$fee3 = params.fee) != null ? _params$fee3 : 0,
-      clarity_version: (_params$clarity_versi = params.clarity_version) != null ? _params$clarity_versi : transactions.ClarityVersion.Clarity4
+      clarity_version: (_params$clarity_versi = params.clarity_version) != null ? _params$clarity_versi : transactions.ClarityVersion.Clarity5
     }));
     return this;
   };
@@ -1141,7 +1648,7 @@ var SimulationBuilder = /*#__PURE__*/function () {
       type: 'SetContractCode',
       contract_id: params.contract_id,
       source_code: params.source_code,
-      clarity_version: (_params$clarity_versi2 = params.clarity_version) != null ? _params$clarity_versi2 : transactions.ClarityVersion.Clarity4
+      clarity_version: (_params$clarity_versi2 = params.clarity_version) != null ? _params$clarity_versi2 : transactions.ClarityVersion.Clarity5
     });
     return this;
   };
@@ -1151,10 +1658,50 @@ var SimulationBuilder = /*#__PURE__*/function () {
       reads: reads
     });
     return this;
-  };
-  _proto.addTenureExtend = function addTenureExtend() {
+  }
+  /**
+   * 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.
+   */;
+  _proto.addTenureExtend = function addTenureExtend(cause) {
+    if (cause === void 0) {
+      cause = 'Extended';
+    }
     this.steps.push({
-      type: 'TenureExtend'
+      type: 'TenureExtend',
+      cause: cause
+    });
+    return 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,
+   * });
+   * ```
+   */;
+  _proto.addAdvanceBlocks = function addAdvanceBlocks(request) {
+    this.steps.push({
+      type: 'AdvanceBlocks',
+      request: request
     });
     return this;
   };
@@ -1369,9 +1916,17 @@ var SimulationBuilder = /*#__PURE__*/function () {
                 Reads: step.reads
               });
             } else if (step.type === 'TenureExtend') {
-              // TenureExtend - format: []
+              // TenureExtend - modern wire shape (legacy `[]` is still parsed
+              // server-side for direct-emit consumers, but the builder always
+              // emits the explicit cause).
               v2Steps.push({
-                TenureExtend: []
+                TenureExtend: {
+                  cause: step.cause
+                }
+              });
+            } else if (step.type === 'AdvanceBlocks') {
+              v2Steps.push({
+                AdvanceBlocks: step.request
               });
             } else {
               console.log("Invalid simulation step: " + step);
@@ -1412,12 +1967,6 @@ var SimulationBuilder = /*#__PURE__*/function () {
   };
   return SimulationBuilder;
 }();
-// Helper function to convert Uint8Array to hex string
-function bytesToHex(bytes) {
-  return Array.from(bytes).map(function (b) {
-    return b.toString(16).padStart(2, '0');
-  }).join('');
-}
 // Helper function to convert ClarityVersion to number
 function clarityVersionToNumber(version) {
   switch (version) {
@@ -1429,10 +1978,242 @@ function clarityVersionToNumber(version) {
       return 3;
     case transactions.ClarityVersion.Clarity4:
       return 4;
+    case transactions.ClarityVersion.Clarity5:
+      return 5;
     default:
-      return 4;
+      return 5;
   }
 }
+/**
+ * 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.
+ */
+function callContract(_x2, _x3, _x4) {
+  return _callContract.apply(this, arguments);
+}
+/**
+ * Read the SIP-010 / hBTC-style `(get-balance principal)` value.
+ * Returns 0n if the read returns `(err …)`. Throws on infra failures.
+ */
+function _callContract() {
+  _callContract = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee4(sessionId, args, options) {
+    var _args$nonce;
+    var nonce, txHex, r, step, receipt, _t, _t2;
+    return _regenerator().w(function (_context4) {
+      while (1) switch (_context4.n) {
+        case 0:
+          if (options === void 0) {
+            options = {};
+          }
+          if (!((_args$nonce = args.nonce) != null)) {
+            _context4.n = 1;
+            break;
+          }
+          _t = _args$nonce;
+          _context4.n = 3;
+          break;
+        case 1:
+          _t2 = Number;
+          _context4.n = 2;
+          return getNonce(sessionId, args.sender, options);
+        case 2:
+          _t = _t2(_context4.v);
+        case 3:
+          nonce = _t;
+          _context4.n = 4;
+          return buildUnsignedContractCallHex(_extends({}, args, {
+            nonce: nonce
+          }));
+        case 4:
+          txHex = _context4.v;
+          _context4.n = 5;
+          return submitSimulationSteps(sessionId, {
+            steps: [{
+              Transaction: txHex
+            }]
+          }, options);
+        case 5:
+          r = _context4.v;
+          step = r.steps[0];
+          if ('Transaction' in step) {
+            _context4.n = 6;
+            break;
+          }
+          throw new Error("expected Transaction step, got " + JSON.stringify(step).slice(0, 200));
+        case 6:
+          if (!('Err' in step.Transaction)) {
+            _context4.n = 7;
+            break;
+          }
+          throw new Error("Transaction Err: " + step.Transaction.Err);
+        case 7:
+          receipt = step.Transaction.Ok;
+          return _context4.a(2, {
+            result: transactions.cvToString(transactions.deserializeCV(receipt.result)),
+            resultHex: receipt.result,
+            vmError: receipt.vm_error,
+            pcAborted: receipt.post_condition_aborted,
+            receipt: receipt
+          });
+      }
+    }, _callee4);
+  }));
+  return _callContract.apply(this, arguments);
+}
+function getFtBalance(_x5, _x6, _x7, _x8) {
+  return _getFtBalance.apply(this, arguments);
+}
+/** Read a principal's STX balance (uSTX) from a simulation session. */
+function _getFtBalance() {
+  _getFtBalance = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee5(sessionId, contractId, principal, options) {
+    var _r$readonly;
+    var r, v, decoded;
+    return _regenerator().w(function (_context5) {
+      while (1) switch (_context5.n) {
+        case 0:
+          if (options === void 0) {
+            options = {};
+          }
+          _context5.n = 1;
+          return simulationBatchReads(sessionId, {
+            readonly: [[contractId, 'get-balance', transactions.serializeCV(transactions.Cl.principal(principal))]]
+          }, options);
+        case 1:
+          r = _context5.v;
+          v = (_r$readonly = r.readonly) == null ? void 0 : _r$readonly[0];
+          if (!(!v || !('Ok' in v))) {
+            _context5.n = 2;
+            break;
+          }
+          throw new Error("get-balance(" + contractId + ") failed: " + JSON.stringify(v));
+        case 2:
+          decoded = transactions.deserializeCV(v.Ok);
+          if (!(decoded.type === transactions.ClarityType.ResponseErr)) {
+            _context5.n = 3;
+            break;
+          }
+          return _context5.a(2, 0n);
+        case 3:
+          if (!(decoded.type !== transactions.ClarityType.ResponseOk)) {
+            _context5.n = 4;
+            break;
+          }
+          throw new Error("unexpected get-balance shape: " + transactions.cvToString(decoded));
+        case 4:
+          if (!(decoded.value.type !== transactions.ClarityType.UInt)) {
+            _context5.n = 5;
+            break;
+          }
+          throw new Error("expected uint inside (ok \u2026), got " + decoded.value.type);
+        case 5:
+          return _context5.a(2, BigInt(decoded.value.value));
+      }
+    }, _callee5);
+  }));
+  return _getFtBalance.apply(this, arguments);
+}
+function getStxBalance(_x9, _x0, _x1) {
+  return _getStxBalance.apply(this, arguments);
+}
+/** Read a principal's current nonce. Returns 0n if never seen. */
+function _getStxBalance() {
+  _getStxBalance = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee6(sessionId, principal, options) {
+    var _r$stx;
+    var r, v;
+    return _regenerator().w(function (_context6) {
+      while (1) switch (_context6.n) {
+        case 0:
+          if (options === void 0) {
+            options = {};
+          }
+          _context6.n = 1;
+          return simulationBatchReads(sessionId, {
+            stx: [principal]
+          }, options);
+        case 1:
+          r = _context6.v;
+          v = (_r$stx = r.stx) == null ? void 0 : _r$stx[0];
+          if (!(!v || !('Ok' in v))) {
+            _context6.n = 2;
+            break;
+          }
+          throw new Error("stx balance read for " + principal + " failed");
+        case 2:
+          return _context6.a(2, BigInt(v.Ok));
+      }
+    }, _callee6);
+  }));
+  return _getStxBalance.apply(this, arguments);
+}
+function getNonce(_x10, _x11, _x12) {
+  return _getNonce.apply(this, arguments);
+}
+/**
+ * Read a Clarity data variable. Returns the decoded `ClarityValue`,
+ * or throws if the read failed.
+ */
+function _getNonce() {
+  _getNonce = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee7(sessionId, principal, options) {
+    var _r$nonces;
+    var r, v;
+    return _regenerator().w(function (_context7) {
+      while (1) switch (_context7.n) {
+        case 0:
+          if (options === void 0) {
+            options = {};
+          }
+          _context7.n = 1;
+          return simulationBatchReads(sessionId, {
+            nonces: [principal]
+          }, options);
+        case 1:
+          r = _context7.v;
+          v = (_r$nonces = r.nonces) == null ? void 0 : _r$nonces[0];
+          if (!(!v || !('Ok' in v))) {
+            _context7.n = 2;
+            break;
+          }
+          return _context7.a(2, 0n);
+        case 2:
+          return _context7.a(2, BigInt(v.Ok));
+      }
+    }, _callee7);
+  }));
+  return _getNonce.apply(this, arguments);
+}
+function readDataVar(_x13, _x14, _x15, _x16) {
+  return _readDataVar.apply(this, arguments);
+}
+function _readDataVar() {
+  _readDataVar = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee8(sessionId, contractId, varName, options) {
+    var _r$vars;
+    var r, v;
+    return _regenerator().w(function (_context8) {
+      while (1) switch (_context8.n) {
+        case 0:
+          if (options === void 0) {
+            options = {};
+          }
+          _context8.n = 1;
+          return simulationBatchReads(sessionId, {
+            vars: [[contractId, varName]]
+          }, options);
+        case 1:
+          r = _context8.v;
+          v = (_r$vars = r.vars) == null ? void 0 : _r$vars[0];
+          if (!(!v || !('Ok' in v))) {
+            _context8.n = 2;
+            break;
+          }
+          throw new Error("var-get " + contractId + " " + varName + " failed: " + JSON.stringify(v));
+        case 2:
+          return _context8.a(2, transactions.deserializeCV(v.Ok));
+      }
+    }, _callee8);
+  }));
+  return _readDataVar.apply(this, arguments);
+}
 
 /**
  * Fetch the current tip information from the sidecar.
@@ -1498,17 +2279,39 @@ exports.DEFAULT_STXER_API = DEFAULT_STXER_API$1;
 exports.STXER_API_MAINNET = STXER_API_MAINNET;
 exports.STXER_API_TESTNET = STXER_API_TESTNET;
 exports.SimulationBuilder = SimulationBuilder;
+exports.SimulationError = SimulationError;
 exports.batchRead = batchRead;
+exports.buildBitcoinHeader = buildBitcoinHeader;
+exports.buildUnsignedContractCallHex = buildUnsignedContractCallHex;
+exports.bytesToHex = bytesToHex;
+exports.callContract = callContract;
 exports.callReadonly = callReadonly;
 exports.createSimulationSession = createSimulationSession;
+exports.forgeBitcoinTx = forgeBitcoinTx;
+exports.ftPrincipal = ftPrincipal;
 exports.getContractAST = getContractAST;
+exports.getFtBalance = getFtBalance;
+exports.getNonce = getNonce;
 exports.getSimulationResult = getSimulationResult;
+exports.getSimulationTip = getSimulationTip;
+exports.getStxBalance = getStxBalance;
 exports.getTip = getTip;
+exports.hexToBytes = hexToBytes;
 exports.instantSimulation = instantSimulation;
+exports.merkleProof = merkleProof;
+exports.opReturnScript = opReturnScript;
+exports.p2pkhScript = p2pkhScript;
+exports.p2wpkhScript = p2wpkhScript;
 exports.parseContract = parseContract;
 exports.parseSimulationEvent = parseSimulationEvent;
+exports.readDataVar = readDataVar;
 exports.readMap = readMap;
 exports.readVariable = readVariable;
+exports.setSender = setSender;
+exports.sha256 = sha256;
+exports.sha256d = sha256d;
 exports.simulationBatchReads = simulationBatchReads;
+exports.singleTxMerkleRoot = singleTxMerkleRoot;
 exports.submitSimulationSteps = submitSimulationSteps;
+exports.verifyMerkleProof = verifyMerkleProof;
 //# sourceMappingURL=stxer.cjs.development.js.map