@secretkeylabs/stacks-tools 0.6.0 → 0.7.0-73ae437

package/README.md

@@ -4,13 +4,13 @@ A collection of methods for calling the Stacks API and managing Stacks pools.
 
 ## Quickstart
 
-Install dependencies with
+Install dependencies with:
 
 ```shell
 bun install
 ```
 
-and build the package with
+and build the package with:
 
 ```shell
 bun run build

package/dist/index.cjs

@@ -28,38 +28,65 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
-var src_exports = {};
-__export(src_exports, {
+var index_exports = {};
+__export(index_exports, {
   callRateLimitedApi: () => callRateLimitedApi,
   error: () => error,
+  flatResults: () => flatResults,
   pox4Api: () => pox4Api,
   queries: () => queries,
+  safeBackOff: () => safeBackOff,
   safeCall: () => safeCall,
   safeCallRateLimitedApi: () => safeCallRateLimitedApi,
+  safeExtractResponseBody: () => safeExtractResponseBody,
   safePromise: () => safePromise,
   stacksApi: () => stacksApi,
   stacksRpcApi: () => stacksRpcApi,
   success: () => success
 });
-module.exports = __toCommonJS(src_exports);
+module.exports = __toCommonJS(index_exports);
 
 // src/utils/safe.ts
+var import_exponential_backoff = require("exponential-backoff");
 function success(data) {
   return [null, data];
 }
-function error(error2) {
-  return [error2, null];
+function error(errorArg) {
+  return [errorArg, null];
 }
 async function safePromise(promise) {
   try {
     return success(await promise);
   } catch (e) {
+    return error({ name: "SafeError", message: "Promise rejected.", data: e });
+  }
+}
+var defaultStartingDelay = 15e3;
+var defaultNumOfAttempts = 5;
+async function safeBackOff(promise, options) {
+  const [backoffError, data] = await safePromise(
+    (0, import_exponential_backoff.backOff)(
+      async () => {
+        const [error2, data2] = await promise;
+        if (error2) {
+          throw error2;
+        }
+        return data2;
+      },
+      {
+        startingDelay: options?.startingDelay ?? defaultStartingDelay,
+        numOfAttempts: options?.numOfAttempts ?? defaultNumOfAttempts
+      }
+    )
+  );
+  if (backoffError) {
     return error({
-      name: "SafePromiseError",
-      message: "Safe promise rejected.",
-      data: e
+      name: "BackoffError",
+      message: "Retries exceeded.",
+      data: backoffError.data
     });
   }
+  return success(data);
 }
 function safeCall(fn) {
   try {
@@ -72,6 +99,29 @@ function safeCall(fn) {
     });
   }
 }
+function flatResults(results) {
+  const errors = results.map((r) => r[0]).filter((maybeError) => maybeError !== null);
+  if (errors.length !== 0)
+    return error({
+      name: "FlatResultsError",
+      message: `Found ${errors.length} errors in result array of length ${results.length}.`,
+      data: errors.slice(0, 10)
+      // Only show first 10 errors to avoid spamming logs
+    });
+  const values = results.map((r) => r[1]);
+  return [null, values];
+}
+async function safeExtractResponseBody(response) {
+  try {
+    return await response.json();
+  } catch {
+    try {
+      return await response.text();
+    } catch {
+      return void 0;
+    }
+  }
+}
 
 // src/stacks-api/accounts/balances.ts
 async function balances(opts) {
@@ -93,7 +143,7 @@ async function balances(opts) {
       data: {
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -134,7 +184,7 @@ async function latestNonce(opts) {
         endpoint,
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -213,7 +263,7 @@ async function getBlock(opts) {
       data: {
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -262,7 +312,7 @@ async function stx(opts) {
       data: {
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -315,7 +365,7 @@ async function coreApi(apiOpts) {
       data: {
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -370,7 +420,7 @@ async function cycle(opts) {
         endpoint,
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -428,7 +478,7 @@ async function cycles(args) {
         endpoint,
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -545,7 +595,7 @@ async function signersInCycle(args) {
         endpoint,
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -556,7 +606,7 @@ async function signersInCycle(args) {
       message: "Failed to parse response body as JSON.",
       data: {
         endpoint,
-        bodyParseResult: data
+        body: data
       }
     });
   }
@@ -572,18 +622,6 @@ async function signersInCycle(args) {
 }
 
 // src/stacks-api/proof-of-transfer/stackers-for-signer-in-cycle.ts
-var v9 = __toESM(require("valibot"), 1);
-var stackerInfoSchema = v9.object({
-  stacker_address: v9.string(),
-  stacked_amount: v9.string(),
-  pox_address: v9.string(),
-  stacker_type: v9.union([v9.literal("pooled"), v9.literal("solo")])
-});
-var resultsSchema3 = v9.array(stackerInfoSchema);
-var stackersForSignerInCycleResponseSchema = v9.object({
-  ...baseListResponseSchema.entries,
-  results: resultsSchema3
-});
 async function stackersForSignerInCycle(opts) {
   const search = new URLSearchParams();
   if (opts.limit) search.append("limit", opts.limit.toString());
@@ -605,7 +643,7 @@ async function stackersForSignerInCycle(opts) {
         endpoint,
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -617,18 +655,7 @@ async function stackersForSignerInCycle(opts) {
       data: jsonError
     });
   }
-  const validationResult = v9.safeParse(
-    stackersForSignerInCycleResponseSchema,
-    data
-  );
-  if (!validationResult.success) {
-    return error({
-      name: "ValidateDataError",
-      message: "Failed to validate response data.",
-      data: validationResult
-    });
-  }
-  return success(validationResult.output);
+  return success(data);
 }
 
 // src/stacks-api/proof-of-transfer/index.ts
@@ -641,21 +668,6 @@ var proofOfTransfer = {
 };
 
 // src/stacks-api/stacking-pool/members.ts
-var v10 = __toESM(require("valibot"), 1);
-var memberSchema = v10.object({
-  stacker: v10.string(),
-  pox_addr: v10.optional(v10.string()),
-  amount_ustx: v10.string(),
-  burn_block_unlock_height: v10.optional(v10.number()),
-  block_height: v10.number(),
-  tx_id: v10.string()
-});
-var membersResponseSchema = v10.object({
-  limit: v10.number(),
-  offset: v10.number(),
-  total: v10.number(),
-  results: v10.array(memberSchema)
-});
 async function members(args) {
   const search = new URLSearchParams();
   if (args.afterBlock) search.append("after_block", args.afterBlock.toString());
@@ -677,7 +689,7 @@ async function members(args) {
       data: {
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -689,15 +701,7 @@ async function members(args) {
       data: jsonParseError
     });
   }
-  const validationResult = v10.safeParse(membersResponseSchema, data);
-  if (!validationResult.success) {
-    return error({
-      name: "ValidateDataError",
-      message: "Failed to validate data.",
-      data: validationResult
-    });
-  }
-  return success(validationResult.output);
+  return success(data);
 }
 
 // src/stacks-api/stacking-pool/index.ts
@@ -705,124 +709,7 @@ var stackingPool = {
   members
 };
 
-// src/stacks-api/transactions/schemas.ts
-var v11 = __toESM(require("valibot"), 1);
-var baseTransactionSchema = v11.object({
-  tx_id: v11.string(),
-  nonce: v11.number(),
-  fee_rate: v11.string(),
-  sender_address: v11.string(),
-  sponsored: v11.boolean(),
-  post_condition_mode: v11.string(),
-  post_conditions: v11.array(v11.unknown()),
-  anchor_mode: v11.string(),
-  is_unanchored: v11.boolean(),
-  block_hash: v11.string(),
-  parent_block_hash: v11.string(),
-  block_height: v11.number(),
-  block_time: v11.number(),
-  block_time_iso: v11.string(),
-  burn_block_height: v11.number(),
-  burn_block_time: v11.number(),
-  burn_block_time_iso: v11.string(),
-  parent_burn_block_time: v11.number(),
-  parent_burn_block_time_iso: v11.string(),
-  canonical: v11.boolean(),
-  tx_index: v11.number(),
-  tx_status: v11.union([
-    v11.literal("success"),
-    v11.literal("abort_by_response"),
-    v11.literal("abort_by_post_condition")
-  ]),
-  tx_result: v11.object({
-    hex: v11.string(),
-    repr: v11.string()
-  }),
-  microblock_hash: v11.string(),
-  microblock_sequence: v11.number(),
-  microblock_canonical: v11.boolean(),
-  event_count: v11.number(),
-  events: v11.array(v11.unknown()),
-  execution_cost_read_count: v11.number(),
-  execution_cost_read_length: v11.number(),
-  execution_cost_runtime: v11.number(),
-  execution_cost_write_count: v11.number(),
-  execution_cost_write_length: v11.number()
-});
-var contractCallTransactionSchema = v11.object({
-  tx_type: v11.literal("contract_call"),
-  contract_call: v11.object({
-    contract_id: v11.string(),
-    function_name: v11.string(),
-    function_signature: v11.string(),
-    function_args: v11.array(
-      v11.object({
-        hex: v11.string(),
-        repr: v11.string(),
-        name: v11.string(),
-        type: v11.string()
-      })
-    )
-  }),
-  ...baseTransactionSchema.entries
-});
-var smartContractTransactionSchema = v11.object({
-  tx_type: v11.literal("smart_contract"),
-  smart_contract: v11.object({
-    /**
-     * NOTE: The types may be wrong, not sure what type of value is used when
-     * the version is not `null`.
-     */
-    clarity_version: v11.union([v11.null(), v11.number()]),
-    contract_id: v11.string(),
-    source_code: v11.string()
-  }),
-  ...baseTransactionSchema.entries
-});
-var tokenTransferSchema = v11.object({
-  tx_type: v11.literal("token_transfer"),
-  token_transfer: v11.object({
-    recipient_address: v11.string(),
-    amount: v11.string(),
-    memo: v11.string()
-  }),
-  ...baseTransactionSchema.entries
-});
-var transactionSchema = v11.variant("tx_type", [
-  contractCallTransactionSchema,
-  smartContractTransactionSchema,
-  tokenTransferSchema
-]);
-
 // src/stacks-api/transactions/address-transactions.ts
-var v12 = __toESM(require("valibot"), 1);
-var resultSchema = v12.object({
-  tx: transactionSchema,
-  stx_sent: v12.string(),
-  stx_received: v12.string(),
-  events: v12.object({
-    stx: v12.object({
-      transfer: v12.number(),
-      mint: v12.number(),
-      burn: v12.number()
-    }),
-    ft: v12.object({
-      transfer: v12.number(),
-      mint: v12.number(),
-      burn: v12.number()
-    }),
-    nft: v12.object({
-      transfer: v12.number(),
-      mint: v12.number(),
-      burn: v12.number()
-    })
-  })
-});
-var resultsSchema4 = v12.array(resultSchema);
-var addressTransactionsResponseSchema = v12.object({
-  ...baseListResponseSchema.entries,
-  results: resultsSchema4
-});
 async function addressTransactions(args) {
   const search = new URLSearchParams();
   if (args.limit) search.append("limit", args.limit.toString());
@@ -844,7 +731,7 @@ async function addressTransactions(args) {
       data: {
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -856,19 +743,47 @@ async function addressTransactions(args) {
       data: jsonParseError
     });
   }
-  const validationResult = v12.safeParse(addressTransactionsResponseSchema, data);
-  if (!validationResult.success) {
+  return success(data);
+}
+
+// src/stacks-api/transactions/events-for-an-address-transaction.ts
+async function eventsForAnAddressTransaction(args) {
+  const search = new URLSearchParams();
+  if (args.limit) search.append("limit", args.limit.toString());
+  if (args.offset) search.append("offset", args.offset.toString());
+  const init = {};
+  if (args.apiKeyConfig) {
+    init.headers = {
+      [args.apiKeyConfig.header]: args.apiKeyConfig.key
+    };
+  }
+  const endpoint = `${args.baseUrl}/extended/v2/addresses/${args.address}/transactions/${args.transactionId}/events?${search}`;
+  const res = await fetch(endpoint, init);
+  if (!res.ok) {
     return error({
-      name: "ValidateDataError",
-      message: "Failed to validate data.",
-      data: validationResult
+      name: "FetchEventsForAnAddressTransactionError",
+      message: `Failed to fetch address transaction events.`,
+      data: {
+        address: args.address,
+        transactionId: args.transactionId,
+        status: res.status,
+        statusText: res.statusText,
+        body: await safeExtractResponseBody(res)
+      }
     });
   }
-  return success(validationResult.output);
+  const [jsonParseError, data] = await safePromise(res.json());
+  if (jsonParseError) {
+    return error({
+      name: "ParseBodyError",
+      message: "Failed to parse response body as JSON.",
+      error: jsonParseError
+    });
+  }
+  return success(data);
 }
 
 // src/stacks-api/transactions/get-transaction.ts
-var v13 = __toESM(require("valibot"), 1);
 async function getTransaction(args) {
   const init = {};
   if (args.apiKeyConfig) {
@@ -881,11 +796,12 @@ async function getTransaction(args) {
   if (!res.ok) {
     return error({
       name: "FetchTransactionError",
-      message: `Failed to fetch transaction ${args.transactionId}`,
-      response: {
+      message: `Failed to fetch transaction.`,
+      data: {
+        transactionId: args.transactionId,
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -897,15 +813,7 @@ async function getTransaction(args) {
       error: jsonParseError
     });
   }
-  const validationResult = v13.safeParse(transactionSchema, data);
-  if (!validationResult.success) {
-    return error({
-      name: "ValidateDataError",
-      message: "Failed to validate data.",
-      error: validationResult
-    });
-  }
-  return success(validationResult.output);
+  return success(data);
 }
 
 // src/stacks-api/transactions/mempool-transactions.ts
@@ -936,7 +844,7 @@ async function mempoolTransactions(args) {
       data: {
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -951,11 +859,46 @@ async function mempoolTransactions(args) {
   return success(data);
 }
 
+// src/stacks-api/transactions/get-raw-transaction.ts
+async function getRawTransaction(args) {
+  const init = {};
+  if (args.apiKeyConfig) {
+    init.headers = {
+      [args.apiKeyConfig.header]: args.apiKeyConfig.key
+    };
+  }
+  const endpoint = `${args.baseUrl}/extended/v1/tx/${args.transactionId}/raw`;
+  const res = await fetch(endpoint, init);
+  if (!res.ok) {
+    return error({
+      name: "RawTransactionFetchError",
+      message: `Failed to fetch raw transaction.`,
+      data: {
+        transactionId: args.transactionId,
+        status: res.status,
+        statusText: res.statusText,
+        body: await safeExtractResponseBody(res)
+      }
+    });
+  }
+  const [jsonParseError, data] = await safePromise(res.json());
+  if (jsonParseError) {
+    return error({
+      name: "ParseBodyError",
+      message: "Failed to parse response body as JSON.",
+      error: jsonParseError
+    });
+  }
+  return success(data);
+}
+
 // src/stacks-api/transactions/index.ts
 var transactions = {
   addressTransactions,
+  eventsForAnAddressTransaction,
   getTransaction,
-  mempoolTransactions
+  mempoolTransactions,
+  getRawTransaction
 };
 
 // src/stacks-api/mempool/transaction-fee-priorities.ts
@@ -975,7 +918,7 @@ async function transactionFeePriorities(opts) {
       data: {
         status: res.status,
         statusText: res.statusText,
-        bodyParseResult: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -1008,16 +951,16 @@ var stacksApi = {
 };
 
 // src/stacks-rpc-api/smart-contracts/map-entry.ts
-var v14 = __toESM(require("valibot"), 1);
-var mapEntryResponseSchema = v14.object({
+var v9 = __toESM(require("valibot"), 1);
+var mapEntryResponseSchema = v9.object({
   /**
    * Hex-encoded string of clarity value. It is always an optional tuple.
    */
-  data: v14.string(),
+  data: v9.string(),
   /**
    * Hex-encoded string of the MARF proof for the data
    */
-  proof: v14.optional(v14.string())
+  proof: v9.optional(v9.string())
 });
 async function mapEntry(args) {
   const search = new URLSearchParams();
@@ -1045,7 +988,7 @@ async function mapEntry(args) {
         status: res.status,
         statusText: res.statusText,
         endpoint,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -1057,7 +1000,7 @@ async function mapEntry(args) {
       data: jsonError
     });
   }
-  const validationResult = v14.safeParse(mapEntryResponseSchema, data);
+  const validationResult = v9.safeParse(mapEntryResponseSchema, data);
   if (!validationResult.success) {
     return error({
       name: "ValidateDataError",
@@ -1093,7 +1036,7 @@ async function readOnly(args) {
       data: {
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -1130,7 +1073,7 @@ async function contractInterface(args) {
         status: res.status,
         statusText: res.statusText,
         endpoint,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -1168,7 +1111,7 @@ async function poxDetails(args) {
       data: {
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -1195,18 +1138,18 @@ var stacksRpcApi = {
 };
 
 // src/utils/call-rate-limited-api.ts
-var import_exponential_backoff = require("exponential-backoff");
-var defaultStartingDelay = 15e3;
-var defaultNumOfAttempts = 5;
+var import_exponential_backoff2 = require("exponential-backoff");
+var defaultStartingDelay2 = 15e3;
+var defaultNumOfAttempts2 = 5;
 function callRateLimitedApi(fn, options) {
-  return (0, import_exponential_backoff.backOff)(fn, {
-    startingDelay: options?.startingDelay ?? defaultStartingDelay,
-    numOfAttempts: options?.numOfAttempts ?? defaultNumOfAttempts
+  return (0, import_exponential_backoff2.backOff)(fn, {
+    startingDelay: options?.startingDelay ?? defaultStartingDelay2,
+    numOfAttempts: options?.numOfAttempts ?? defaultNumOfAttempts2
   });
 }
 async function safeCallRateLimitedApi(fn, options) {
   try {
-    return await (0, import_exponential_backoff.backOff)(
+    return await (0, import_exponential_backoff2.backOff)(
       async () => {
         const [error2, data] = await fn();
         if (error2) {
@@ -1422,10 +1365,13 @@ var pox4Api = { maps, readOnly: readOnly2 };
 0 && (module.exports = {
   callRateLimitedApi,
   error,
+  flatResults,
   pox4Api,
   queries,
+  safeBackOff,
   safeCall,
   safeCallRateLimitedApi,
+  safeExtractResponseBody,
   safePromise,
   stacksApi,
   stacksRpcApi,