@secondlayer/stacks 2.10.0 → 2.12.0

package/dist/src/tools/index.cjs

@@ -41,7 +41,7 @@ var __export = (target, all) => {
 var exports_tools = {};
 __export(exports_tools, {
   readContract: () => readContract2,
-  getTransaction: () => getTransaction,
+  getTransaction: () => getTransaction2,
   getStxBalance: () => getStxBalance,
   getNftHoldings: () => getNftHoldings,
   getMempoolStats: () => getMempoolStats,
@@ -748,7 +748,37 @@ class BytesReader {
   }
 }
 
+// src/utils/constants.ts
+var MAX_U128 = (1n << 128n) - 1n;
+var MAX_I128 = (1n << 127n) - 1n;
+var MIN_I128 = -(1n << 127n);
+var AddressVersion = {
+  MainnetSingleSig: 22,
+  MainnetMultiSig: 20,
+  TestnetSingleSig: 26,
+  TestnetMultiSig: 21
+};
+
+// src/utils/hash.ts
+var import_legacy = require("@noble/hashes/legacy.js");
+var import_sha22 = require("@noble/hashes/sha2.js");
+var import_sha23 = require("@noble/hashes/sha2.js");
+function hash160(input) {
+  return import_legacy.ripemd160(import_sha22.sha256(input));
+}
+function txidFromBytes(data) {
+  return bytesToHex(import_sha23.sha512_256(data));
+}
+function hashP2PKH(input) {
+  return bytesToHex(hash160(input));
+}
+
 // src/utils/address.ts
+function publicKeyToAddress(publicKey, network = "mainnet") {
+  const bytes = typeof publicKey === "string" ? hexToBytes(without0x(publicKey)) : publicKey;
+  const version = network === "mainnet" ? AddressVersion.MainnetSingleSig : AddressVersion.TestnetSingleSig;
+  return c32address(version, bytesToHex(hash160(bytes)));
+}
 function parseContractId(contractId) {
   const [address, name] = contractId.split(".");
   if (!address || !name)
@@ -761,9 +791,9 @@ function isClarityName(name) {
 }
 
 // src/clarity/values.ts
-var MAX_U128 = BigInt("0xffffffffffffffffffffffffffffffff");
-var MIN_I128 = BigInt("-170141183460469231731687303715884105728");
-var MAX_I128 = BigInt("0x7fffffffffffffffffffffffffffffff");
+var MAX_U1282 = BigInt("0xffffffffffffffffffffffffffffffff");
+var MIN_I1282 = BigInt("-170141183460469231731687303715884105728");
+var MAX_I1282 = BigInt("0x7fffffffffffffffffffffffffffffff");
 function intCV(value) {
   let v = value;
   if (typeof v === "string" && v.toLowerCase().startsWith("0x")) {
@@ -772,18 +802,18 @@ function intCV(value) {
   if (v instanceof Uint8Array)
     v = bytesToTwosBigInt(v);
   const n = intToBigInt(v);
-  if (n > MAX_I128)
-    throw new RangeError(`Int exceeds max i128: ${MAX_I128}`);
-  if (n < MIN_I128)
-    throw new RangeError(`Int below min i128: ${MIN_I128}`);
+  if (n > MAX_I1282)
+    throw new RangeError(`Int exceeds max i128: ${MAX_I1282}`);
+  if (n < MIN_I1282)
+    throw new RangeError(`Int below min i128: ${MIN_I1282}`);
   return { type: "int", value: n };
 }
 function uintCV(value) {
   const n = intToBigInt(value);
   if (n < 0n)
     throw new RangeError("Cannot construct unsigned int from negative value");
-  if (n > MAX_U128)
-    throw new RangeError(`UInt exceeds max u128: ${MAX_U128}`);
+  if (n > MAX_U1282)
+    throw new RangeError(`UInt exceeds max u128: ${MAX_U1282}`);
   return { type: "uint", value: n };
 }
 var trueCV = () => ({ type: "true" });
@@ -796,13 +826,13 @@ function bufferCV(buffer) {
   return { type: "buffer", value: bytesToHex(buffer) };
 }
 function standardPrincipalCV(address) {
-  const [version, hash160] = c32addressDecode(address);
-  const normalized = c32address(version, hash160);
+  const [version, hash1602] = c32addressDecode(address);
+  const normalized = c32address(version, hash1602);
   return { type: "address", value: normalized };
 }
 function contractPrincipalCV(address, contractName) {
-  const [version, hash160] = c32addressDecode(address);
-  const normalized = c32address(version, hash160);
+  const [version, hash1602] = c32addressDecode(address);
+  const normalized = c32address(version, hash1602);
   if (utf8ToBytes(contractName).byteLength >= 128) {
     throw new Error("Contract name must be less than 128 bytes");
   }
@@ -873,8 +903,8 @@ var Cl = {
 // src/clarity/deserialize.ts
 function readAddress(reader) {
   const version = reader.readUInt8();
-  const hash160 = bytesToHex(reader.readBytes(20));
-  return c32address(version, hash160);
+  const hash1602 = bytesToHex(reader.readBytes(20));
+  return c32address(version, hash1602);
 }
 function readLPString(reader, prefixBytes = 1) {
   let length = 0;
@@ -971,11 +1001,6 @@ function toCamelCase(str) {
   return str.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase()).replace(/-([A-Z])/g, (_, letter) => letter).replace(/-(\d)/g, (_, digit) => digit).replace(/-/g, "").replace(/^\d/, "_$&");
 }
 
-// src/utils/constants.ts
-var MAX_U1282 = (1n << 128n) - 1n;
-var MAX_I1282 = (1n << 127n) - 1n;
-var MIN_I1282 = -(1n << 127n);
-
 // src/clarity/abi/guards.ts
 function isAbiList(type) {
   return typeof type === "object" && type !== null && "list" in type;
@@ -1000,7 +1025,64 @@ function isAbiStringUtf8(type) {
 }
 
 // src/clarity/bridge.ts
+var CV_TYPE_TAGS = new Set([
+  "int",
+  "uint",
+  "true",
+  "false",
+  "address",
+  "contract",
+  "ascii",
+  "utf8",
+  "buffer",
+  "list",
+  "tuple",
+  "none",
+  "some",
+  "ok",
+  "err"
+]);
+function isClarityValue(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const type = value.type;
+  if (typeof type !== "string" || !CV_TYPE_TAGS.has(type))
+    return false;
+  if (type === "true" || type === "false" || type === "none")
+    return true;
+  return "value" in value;
+}
+var HEX_PAIRS_REGEX = /^(?:[0-9a-fA-F]{2})+$/;
+function coerceBuffer(value) {
+  if (value instanceof Uint8Array)
+    return bufferCV(value);
+  if (typeof value === "object" && value !== null && "type" in value) {
+    const tagged = value;
+    if (tagged.type === "buffer" && isClarityValue(value))
+      return value;
+    if (typeof tagged.value === "string") {
+      if (tagged.type === "ascii")
+        return Cl.bufferFromAscii(tagged.value);
+      if (tagged.type === "utf8")
+        return Cl.bufferFromUtf8(tagged.value);
+      if (tagged.type === "hex")
+        return Cl.bufferFromHex(tagged.value);
+    }
+    throw new Error(`Unsupported buffer input: ${JSON.stringify(value)}`);
+  }
+  if (typeof value === "string") {
+    const hex = value.startsWith("0x") ? value.slice(2) : value;
+    if (HEX_PAIRS_REGEX.test(hex))
+      return Cl.bufferFromHex(hex);
+    return Cl.bufferFromUtf8(value);
+  }
+  throw new Error("buffer arg expects Uint8Array, hex string, { type, value }, or BufferCV");
+}
 function jsToClarityValue(abiType, value) {
+  if (isAbiBuffer(abiType))
+    return coerceBuffer(value);
+  if (isClarityValue(value))
+    return value;
   if (abiType === "uint128")
     return uintCV(value);
   if (abiType === "int128")
@@ -1013,8 +1095,6 @@ function jsToClarityValue(abiType, value) {
     return stringAsciiCV(value);
   if (isAbiStringUtf8(abiType))
     return stringUtf8CV(value);
-  if (isAbiBuffer(abiType))
-    return bufferCV(value);
   if (isAbiList(abiType)) {
     const arr = value;
     return listCV(arr.map((item) => jsToClarityValue(abiType.list.type, item)));
@@ -1120,37 +1200,10 @@ function clarityValueToJSInner(abiType, cv) {
   throw new Error(`Unknown ABI type: ${JSON.stringify(abiType)}`);
 }
 
-// src/actions/public/getMapEntry.ts
-async function getMapEntry(client, params) {
-  const [address, name] = parseContractId(params.contract);
-  const serializedKey = with0x(bytesToHex(serializeCVBytes(params.key)));
-  const data = await client.request(`/v2/map_entry/${address}/${name}/${params.mapName}`, {
-    method: "POST",
-    body: serializedKey
-  });
-  return deserializeCVBytes(data.data);
-}
-
 // src/transactions/authorization.ts
 var import_hmac = require("@noble/hashes/hmac.js");
 var import_sha24 = require("@noble/hashes/sha2.js");
 var import_secp256k1 = require("@noble/secp256k1");
-
-// src/utils/hash.ts
-var import_legacy = require("@noble/hashes/legacy.js");
-var import_sha22 = require("@noble/hashes/sha2.js");
-var import_sha23 = require("@noble/hashes/sha2.js");
-function hash160(input) {
-  return import_legacy.ripemd160(import_sha22.sha256(input));
-}
-function txidFromBytes(data) {
-  return bytesToHex(import_sha23.sha512_256(data));
-}
-function hashP2PKH(input) {
-  return bytesToHex(hash160(input));
-}
-
-// src/transactions/authorization.ts
 import_secp256k1.etc.hmacSha256Sync = (key, ...msgs) => {
   const h = import_hmac.hmac.create(import_sha24.sha256, key);
   for (const msg of msgs)
@@ -1362,6 +1415,17 @@ function buildContractCall(options) {
   return tx;
 }
 
+// src/actions/public/getMapEntry.ts
+async function getMapEntry(client, params) {
+  const [address, name] = parseContractId(params.contract);
+  const serializedKey = with0x(bytesToHex(serializeCVBytes(params.key)));
+  const data = await client.request(`/v2/map_entry/${address}/${name}/${params.mapName}`, {
+    method: "POST",
+    body: serializedKey
+  });
+  return deserializeCVBytes(data.data);
+}
+
 // src/transactions/signer.ts
 function txid(tx) {
   return txidFromBytes(serializeTransaction(tx));
@@ -1425,10 +1489,39 @@ class BroadcastError extends BaseError {
   name = "BroadcastError";
   txid;
   reason;
+  reasonData;
   constructor(message, options) {
     super(message, options);
     this.txid = options?.txid;
     this.reason = options?.reason;
+    this.reasonData = options?.reasonData;
+  }
+}
+
+class TransactionAbortedError extends BaseError {
+  name = "TransactionAbortedError";
+  receipt;
+  constructor(message, options) {
+    super(message, options);
+    this.receipt = options.receipt;
+  }
+}
+
+class TransactionDroppedError extends BaseError {
+  name = "TransactionDroppedError";
+  txid;
+  constructor(message, options) {
+    super(message, options);
+    this.txid = options.txid;
+  }
+}
+
+class WaitForTransactionTimeoutError extends BaseError {
+  name = "WaitForTransactionTimeoutError";
+  txid;
+  constructor(message, options) {
+    super(message, options);
+    this.txid = options.txid;
   }
 }
 
@@ -1444,6 +1537,107 @@ async function getNonce(client, params) {
   return BigInt(nonce);
 }
 
+// src/actions/public/txSources.ts
+function normalizeTxid(txid2) {
+  return txid2.startsWith("0x") ? txid2 : `0x${txid2}`;
+}
+function decodeResultHex(hex) {
+  if (!hex)
+    return {};
+  try {
+    return { result: deserializeCVBytes(hex), resultHex: hex };
+  } catch {
+    return { resultHex: hex };
+  }
+}
+function normalizeStatus(txStatus) {
+  switch (txStatus) {
+    case "pending":
+    case "success":
+    case "abort_by_response":
+    case "abort_by_post_condition":
+      return txStatus;
+    default:
+      return txStatus.startsWith("dropped") ? "dropped" : undefined;
+  }
+}
+function extendedApiSource() {
+  return {
+    async get({ client, txid: txid2 }) {
+      const data = await client.request(`/extended/v1/tx/${normalizeTxid(txid2)}`, { method: "GET" });
+      const txStatus = typeof data?.tx_status === "string" ? data.tx_status : undefined;
+      if (!txStatus)
+        return { receipt: null };
+      const status = normalizeStatus(txStatus);
+      if (!status)
+        return { receipt: null };
+      return {
+        receipt: {
+          txid: normalizeTxid(txid2),
+          status,
+          blockHeight: typeof data.block_height === "number" && data.block_height > 0 ? data.block_height : undefined,
+          blockHash: data.block_hash ?? undefined,
+          ...decodeResultHex(data.tx_result?.hex),
+          events: Array.isArray(data.events) ? data.events : [],
+          raw: data
+        }
+      };
+    }
+  };
+}
+
+// src/actions/public/waitForTransactionReceipt.ts
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function waitForTransactionReceipt(client, params) {
+  const {
+    txid: txid2,
+    confirmations = 1,
+    timeout = 180000,
+    pollingInterval = 3000,
+    droppedGracePeriod = 30000
+  } = params;
+  const source = params.source ?? extendedApiSource();
+  const startedAt = Date.now();
+  let unknownSince = null;
+  let everPending = false;
+  while (true) {
+    const snapshot = await source.get({ client, txid: txid2 });
+    const receipt = snapshot.receipt;
+    if (receipt === null) {
+      unknownSince ??= Date.now();
+      if (Date.now() - unknownSince >= droppedGracePeriod) {
+        throw new TransactionDroppedError(everPending ? `Transaction ${txid2} left the mempool without being mined` : `Transaction ${txid2} was never observed by the status source`, { txid: txid2 });
+      }
+    } else {
+      unknownSince = null;
+      switch (receipt.status) {
+        case "dropped":
+          throw new TransactionDroppedError(`Transaction ${txid2} was dropped from the mempool`, { txid: txid2 });
+        case "abort_by_response":
+        case "abort_by_post_condition":
+          throw new TransactionAbortedError(`Transaction ${txid2} aborted (${receipt.status})`, { receipt });
+        case "pending":
+          everPending = true;
+          break;
+        case "success": {
+          if (confirmations <= 1)
+            return receipt;
+          if (receipt.blockHeight !== undefined) {
+            const tip = snapshot.tip ?? await getBlockHeight(client);
+            if (tip - receipt.blockHeight + 1 >= confirmations)
+              return receipt;
+          }
+          break;
+        }
+      }
+    }
+    if (Date.now() - startedAt >= timeout) {
+      throw new WaitForTransactionTimeoutError(`Timed out after ${timeout}ms waiting for transaction ${txid2}`, { txid: txid2 });
+    }
+    await sleep(pollingInterval);
+  }
+}
+
 // src/actions/wallet/sendTransaction.ts
 async function sendTransaction(client, params) {
   const hex = bytesToHex(serializeTransaction(params.transaction));
@@ -1457,10 +1651,20 @@ async function sendTransaction(client, params) {
   });
   if (data.error) {
     throw new BroadcastError(data.reason ?? data.error, {
-      reason: data.reason
+      reason: data.reason,
+      reasonData: data.reason_data,
+      txid: data.txid ?? getTransactionId(params.transaction)
     });
   }
   const txid2 = typeof data === "string" ? data.replace(/"/g, "") : data.txid ?? getTransactionId(params.transaction);
+  if (params.wait) {
+    const confirmations = params.wait === true ? 1 : params.wait;
+    const receipt = await waitForTransactionReceipt(client, {
+      txid: txid2,
+      confirmations
+    });
+    return { txid: txid2, receipt };
+  }
   return { txid: txid2 };
 }
 
@@ -1473,8 +1677,12 @@ async function resolveNonce(client, address) {
 function isNonceConflictError(error) {
   if (!(error instanceof BroadcastError))
     return false;
-  const haystack = `${error.reason ?? ""} ${error.message}`.toLowerCase();
-  return haystack.includes("nonce");
+  if (error.reason === "ConflictingNonceInMempool" || error.reason === "BadNonce") {
+    return true;
+  }
+  if (error.reason !== undefined)
+    return false;
+  return error.message.toLowerCase().includes("nonce");
 }
 async function broadcastWithNonceReset(client, params) {
   try {
@@ -1494,6 +1702,36 @@ async function broadcastWithNonceReset(client, params) {
 function isProviderAccount(account) {
   return account.type === "provider";
 }
+var FEE_TIERS = ["min", "low", "mid", "high"];
+var TIER_INDEX = { low: 0, mid: 1, high: 2 };
+function isFeeTier(fee) {
+  return typeof fee === "string" && FEE_TIERS.includes(fee);
+}
+function minimumFee(transaction) {
+  return BigInt(serializeTransaction(transaction).length);
+}
+async function resolveFee(client, transaction, fee) {
+  if (fee !== undefined && !isFeeTier(fee))
+    return intToBigInt(fee);
+  const tier = fee ?? "mid";
+  if (tier === "min")
+    return minimumFee(transaction);
+  try {
+    const estimates = await estimateFee(client, { transaction });
+    const pick = estimates[TIER_INDEX[tier]] ?? estimates[estimates.length - 1];
+    if (pick)
+      return BigInt(pick.fee);
+  } catch {}
+  return minimumFee(transaction);
+}
+function setUnsignedFee(transaction, fee) {
+  transaction.auth.spendingCondition.fee = fee;
+}
+function assertNoFeeTierForProvider(fee) {
+  if (isFeeTier(fee)) {
+    throw new Error(`Fee tier '${fee}' requires local signing; provider (wallet) accounts set their own fee`);
+  }
+}
 
 // src/actions/wallet/callContract.ts
 async function callContract(client, params) {
@@ -1502,6 +1740,7 @@ async function callContract(client, params) {
     throw new Error("Account required");
   const [contractAddress, contractName] = parseContractId(params.contract);
   if (isProviderAccount(account)) {
+    assertNoFeeTierForProvider(params.fee);
     const result = await account.provider.request("stx_callContract", {
       contract: params.contract,
       functionName: params.functionName,
@@ -1510,24 +1749,21 @@ async function callContract(client, params) {
     return result.txid;
   }
   const nonce = params.nonce ?? await resolveNonce(client, account.address);
+  const needsFeeResolution = params.fee === undefined || isFeeTier(params.fee);
   const unsigned = buildContractCall({
     contractAddress,
     contractName,
     functionName: params.functionName,
     functionArgs: params.functionArgs ?? [],
-    fee: params.fee ?? 0n,
+    fee: needsFeeResolution ? 0n : params.fee,
     nonce,
     publicKey: account.publicKey,
     chain: client.chain,
     postConditionMode: params.postConditionMode,
     postConditions: params.postConditions
   });
-  if (params.fee === undefined) {
-    const estimates = await estimateFee(client, { transaction: unsigned });
-    const mid = estimates[1] ?? estimates[0];
-    if (mid) {
-      unsigned.auth.spendingCondition.fee = BigInt(mid.fee);
-    }
+  if (needsFeeResolution) {
+    setUnsignedFee(unsigned, await resolveFee(client, unsigned, params.fee));
   }
   const signed = await signTransactionWithAccount(unsigned, account);
   return broadcastWithNonceReset(client, {
@@ -1600,6 +1836,46 @@ function getContract(params) {
       };
     }
   });
+  const buildCall = new Proxy({}, {
+    get(_target, prop) {
+      const fnName = camelToKebab.get(prop) ?? prop;
+      const fn = fnByName.get(fnName);
+      if (!fn || fn.access !== "public")
+        return;
+      return async (args, options) => {
+        const publicKey = options?.publicKey ?? client.account?.publicKey;
+        if (!publicKey) {
+          throw new Error("buildCall requires a publicKey (pass options.publicKey or configure a client account)");
+        }
+        const functionArgs = buildFunctionArgs(fn, args);
+        const network = client.chain?.network ?? "mainnet";
+        const nonce = options?.nonce ?? await resolveNonce(client, publicKeyToAddress(publicKey, network));
+        const unsigned = buildContractCall({
+          contractAddress: address,
+          contractName,
+          functionName: fn.name,
+          functionArgs,
+          fee: options?.fee ?? 0n,
+          nonce,
+          publicKey,
+          chain: client.chain,
+          postConditionMode: options?.postConditionMode,
+          postConditions: options?.postConditions,
+          sponsored: options?.sponsored
+        });
+        if (options?.fee === undefined) {
+          const estimates = await estimateFee(client, {
+            transaction: unsigned
+          });
+          const mid = estimates[1] ?? estimates[0];
+          if (mid) {
+            unsigned.auth.spendingCondition.fee = BigInt(mid.fee);
+          }
+        }
+        return unsigned;
+      };
+    }
+  });
   const maps = new Proxy({}, {
     get(_target, prop) {
       const mapName = camelToKebab.get(prop) ?? prop;
@@ -1622,7 +1898,7 @@ function getContract(params) {
       };
     }
   });
-  return { read, call, maps };
+  return { read, call, buildCall, maps };
 }
 function resolveNetworkContract(client, contracts) {
   if (!client.chain) {
@@ -2307,6 +2583,13 @@ async function getContractAbi(client, params) {
   });
 }
 
+// src/actions/public/getTransaction.ts
+async function getTransaction(client, params) {
+  const source = params.source ?? extendedApiSource();
+  const { receipt } = await source.get({ client, txid: params.txid });
+  return receipt;
+}
+
 // src/actions/public/multicall.ts
 async function multicall(client, params) {
   const { calls, allowFailure = true } = params;
@@ -2457,6 +2740,8 @@ function publicActions(client) {
     multicall: (params) => multicall(client, params),
     simulateCall: (params) => simulateCall(client, params),
     simulateTransaction: (params) => simulateTransaction(client, params),
+    getTransaction: (params) => getTransaction(client, params),
+    waitForTransactionReceipt: (params) => waitForTransactionReceipt(client, params),
     watchBlocks: (params) => watchBlocks(client, params),
     watchMempool: (params) => watchMempool(client, params),
     watchTransaction: (params) => watchTransaction(client, params),
@@ -2765,7 +3050,7 @@ var bnsReverse = import_ai.tool({
   inputSchema: import_zod.z.object({ principal: PRINCIPAL }),
   execute: ({ principal }) => bnsReverseImpl(getDefaultPublicClient(), principal)
 });
-var getTransaction = import_ai.tool({
+var getTransaction2 = import_ai.tool({
   description: "Fetch a confirmed Stacks transaction by txId (Hiro extended API).",
   inputSchema: import_zod.z.object({ txId: import_zod.z.string() }),
   execute: ({ txId }) => transactionByTxId(getDefaultPublicClient(), txId)
@@ -2792,5 +3077,5 @@ var getNftHoldings = import_ai.tool({
   execute: ({ principal, limit }) => nftHoldings(getDefaultPublicClient(), principal, limit)
 });
 
-//# debugId=F40D5D6D3BD59C9E64756E2164756E21
+//# debugId=E0CFA9E2C0C074CF64756E2164756E21
 //# sourceMappingURL=index.cjs.map