@secretkeylabs/stacks-tools 0.4.0 → 0.5.0

package/dist/index.cjs

@@ -32,10 +32,12 @@ var src_exports = {};
 __export(src_exports, {
   callRateLimitedApi: () => callRateLimitedApi,
   error: () => error,
+  queries: () => queries,
   safeCall: () => safeCall,
   safeCallRateLimitedApi: () => safeCallRateLimitedApi,
   safePromise: () => safePromise,
   stacksApi: () => stacksApi,
+  stacksRpcApi: () => stacksRpcApi,
   success: () => success
 });
 module.exports = __toCommonJS(src_exports);
@@ -193,6 +195,12 @@ async function latestNonce(opts) {
   return success(validationResult.output);
 }
 
+// src/stacks-api/accounts/index.ts
+var accounts = {
+  balances,
+  latestNonce
+};
+
 // src/stacks-api/types.ts
 var v3 = __toESM(require("valibot"), 1);
 var baseListResponseSchema = v3.object({
@@ -266,6 +274,52 @@ async function getBlock(opts) {
   return success(validationResult.output);
 }
 
+// src/stacks-api/blocks/index.ts
+var blocks = {
+  getBlock
+};
+
+// src/stacks-api/faucets/stx.ts
+async function stx(opts) {
+  const search = new URLSearchParams();
+  search.append("address", opts.address);
+  if (opts.stacking) search.append("stacking", "true");
+  const init = {};
+  if (opts.apiKeyConfig) {
+    init.headers = {
+      [opts.apiKeyConfig.header]: opts.apiKeyConfig.key
+    };
+  }
+  init.method = "POST";
+  const endpoint = `${opts.baseUrl}/extended/v1/faucets/stx?${search}`;
+  const res = await fetch(endpoint, init);
+  if (!res.ok) {
+    return error({
+      name: "FetchStxError",
+      message: "Failed to fetch STX.",
+      data: {
+        status: res.status,
+        statusText: res.statusText,
+        bodyParseResult: await safePromise(res.json())
+      }
+    });
+  }
+  const [jsonError, data] = await safePromise(res.json());
+  if (jsonError) {
+    return error({
+      name: "ParseBodyError",
+      message: "Failed to parse response body as JSON.",
+      data: jsonError
+    });
+  }
+  return success(data);
+}
+
+// src/stacks-api/faucets/index.ts
+var faucets = {
+  stx
+};
+
 // src/stacks-api/info/core-api.ts
 var v5 = __toESM(require("valibot"), 1);
 var CoreApiResponseSchema = v5.object({
@@ -418,6 +472,12 @@ async function poxDetails(args) {
   return success(validationResult.output);
 }
 
+// src/stacks-api/info/index.ts
+var info = {
+  coreApi,
+  poxDetails
+};
+
 // src/stacks-api/proof-of-transfer/cycle.ts
 var v7 = __toESM(require("valibot"), 1);
 var responseSchema4 = v7.object({
@@ -706,100 +766,45 @@ async function stackersForSignerInCycle(opts) {
   return success(validationResult.output);
 }
 
-// src/stacks-api/smart-contracts/read-only.ts
-var v12 = __toESM(require("valibot"), 1);
-var readOnlyResponseSchema = v12.variant("okay", [
-  v12.object({
-    okay: v12.literal(true),
-    /**
-     * A Clarity value as a hex-encoded string.
-     */
-    result: v12.string()
-  }),
-  v12.object({
-    okay: v12.literal(false),
-    cause: v12.unknown()
-  })
-]);
-async function readOnly(args) {
-  const headers = {
-    "Content-Type": "application/json"
-  };
-  if (args.apiKeyConfig) {
-    headers[args.apiKeyConfig.header] = args.apiKeyConfig.key;
-  }
-  const init = {
-    method: "POST",
-    body: JSON.stringify({
-      sender: args.sender,
-      arguments: args.arguments
-    }),
-    headers
-  };
-  const endpoint = `${args.baseUrl}/v2/contracts/call-read/${args.contractAddress}/${args.contractName}/${args.functionName}`;
-  const res = await fetch(endpoint, init);
-  if (!res.ok) {
-    return error({
-      name: "FetchReadOnlyError",
-      message: "Failed to fetch.",
-      data: {
-        status: res.status,
-        statusText: res.statusText,
-        bodyParseResult: await safePromise(res.json())
-      }
-    });
-  }
-  const [jsonError, data] = await safePromise(res.json());
-  if (jsonError) {
-    return error({
-      name: "ParseBodyError",
-      message: "Failed to parse response body as JSON.",
-      data: error
-    });
-  }
-  const validationResult = v12.safeParse(readOnlyResponseSchema, data);
-  if (!validationResult.success) {
-    return error({
-      name: "ValidateDataError",
-      message: "Failed to validate data.",
-      data: validationResult
-    });
-  }
-  return success(validationResult.output);
-}
+// src/stacks-api/proof-of-transfer/index.ts
+var proofOfTransfer = {
+  cycle,
+  cycles,
+  signerInCycle,
+  signersInCycle,
+  stackersForSignerInCycle
+};
 
 // src/stacks-api/stacking-pool/members.ts
-var v13 = __toESM(require("valibot"), 1);
-var memberSchema = v13.object({
-  stacker: v13.string(),
-  pox_addr: v13.optional(v13.string()),
-  amount_ustx: v13.string(),
-  burn_block_unlock_height: v13.optional(v13.number()),
-  block_height: v13.number(),
-  tx_id: v13.string()
+var v12 = __toESM(require("valibot"), 1);
+var memberSchema = v12.object({
+  stacker: v12.string(),
+  pox_addr: v12.optional(v12.string()),
+  amount_ustx: v12.string(),
+  burn_block_unlock_height: v12.optional(v12.number()),
+  block_height: v12.number(),
+  tx_id: v12.string()
 });
-var membersResponseSchema = v13.object({
-  limit: v13.number(),
-  offset: v13.number(),
-  total: v13.number(),
-  results: v13.array(memberSchema)
+var membersResponseSchema = v12.object({
+  limit: v12.number(),
+  offset: v12.number(),
+  total: v12.number(),
+  results: v12.array(memberSchema)
 });
-async function members(opts, apiOpts) {
+async function members(args) {
   const search = new URLSearchParams();
-  if (opts.afterBlock) search.append("after_block", opts.afterBlock.toString());
-  if (opts.unanchored) search.append("unanchored", "true");
-  if (opts.limit) search.append("limit", opts.limit.toString());
-  if (opts.offset) search.append("offset", opts.offset.toString());
+  if (args.afterBlock) search.append("after_block", args.afterBlock.toString());
+  if (args.unanchored) search.append("unanchored", "true");
+  if (args.limit) search.append("limit", args.limit.toString());
+  if (args.offset) search.append("offset", args.offset.toString());
   const init = {};
-  if (apiOpts.apiKeyConfig) {
+  if (args.apiKeyConfig) {
     init.headers = {
-      [apiOpts.apiKeyConfig.header]: apiOpts.apiKeyConfig.key
+      [args.apiKeyConfig.header]: args.apiKeyConfig.key
     };
   }
-  const res = await fetch(
-    `${apiOpts.baseUrl}/extended/beta/stacking/${opts.poolPrincipal}/delegations?${search}`,
-    init
-  );
+  const endpoint = `${args.baseUrl}/extended/v1/pox4/${args.poolPrincipal}/delegations?${search}`;
+  const res = await fetch(endpoint, init);
   if (!res.ok) {
     return error({
       name: "FetchMembersError",
@@ -819,7 +824,7 @@ async function members(opts, apiOpts) {
       data: jsonParseError
     });
   }
-  const validationResult = v13.safeParse(membersResponseSchema, data);
+  const validationResult = v12.safeParse(membersResponseSchema, data);
   if (!validationResult.success) {
     return error({
       name: "ValidateDataError",
@@ -830,121 +835,126 @@ async function members(opts, apiOpts) {
   return success(validationResult.output);
 }
 
+// src/stacks-api/stacking-pool/index.ts
+var stackingPool = {
+  members
+};
+
 // src/stacks-api/transactions/schemas.ts
-var v14 = __toESM(require("valibot"), 1);
-var baseTransactionSchema = v14.object({
-  tx_id: v14.string(),
-  nonce: v14.number(),
-  fee_rate: v14.string(),
-  sender_address: v14.string(),
-  sponsored: v14.boolean(),
-  post_condition_mode: v14.string(),
-  post_conditions: v14.array(v14.unknown()),
-  anchor_mode: v14.string(),
-  is_unanchored: v14.boolean(),
-  block_hash: v14.string(),
-  parent_block_hash: v14.string(),
-  block_height: v14.number(),
-  block_time: v14.number(),
-  block_time_iso: v14.string(),
-  burn_block_height: v14.number(),
-  burn_block_time: v14.number(),
-  burn_block_time_iso: v14.string(),
-  parent_burn_block_time: v14.number(),
-  parent_burn_block_time_iso: v14.string(),
-  canonical: v14.boolean(),
-  tx_index: v14.number(),
-  tx_status: v14.union([
-    v14.literal("success"),
-    v14.literal("abort_by_response"),
-    v14.literal("abort_by_post_condition")
+var v13 = __toESM(require("valibot"), 1);
+var baseTransactionSchema = v13.object({
+  tx_id: v13.string(),
+  nonce: v13.number(),
+  fee_rate: v13.string(),
+  sender_address: v13.string(),
+  sponsored: v13.boolean(),
+  post_condition_mode: v13.string(),
+  post_conditions: v13.array(v13.unknown()),
+  anchor_mode: v13.string(),
+  is_unanchored: v13.boolean(),
+  block_hash: v13.string(),
+  parent_block_hash: v13.string(),
+  block_height: v13.number(),
+  block_time: v13.number(),
+  block_time_iso: v13.string(),
+  burn_block_height: v13.number(),
+  burn_block_time: v13.number(),
+  burn_block_time_iso: v13.string(),
+  parent_burn_block_time: v13.number(),
+  parent_burn_block_time_iso: v13.string(),
+  canonical: v13.boolean(),
+  tx_index: v13.number(),
+  tx_status: v13.union([
+    v13.literal("success"),
+    v13.literal("abort_by_response"),
+    v13.literal("abort_by_post_condition")
   ]),
-  tx_result: v14.object({
-    hex: v14.string(),
-    repr: v14.string()
+  tx_result: v13.object({
+    hex: v13.string(),
+    repr: v13.string()
   }),
-  microblock_hash: v14.string(),
-  microblock_sequence: v14.number(),
-  microblock_canonical: v14.boolean(),
-  event_count: v14.number(),
-  events: v14.array(v14.unknown()),
-  execution_cost_read_count: v14.number(),
-  execution_cost_read_length: v14.number(),
-  execution_cost_runtime: v14.number(),
-  execution_cost_write_count: v14.number(),
-  execution_cost_write_length: v14.number()
+  microblock_hash: v13.string(),
+  microblock_sequence: v13.number(),
+  microblock_canonical: v13.boolean(),
+  event_count: v13.number(),
+  events: v13.array(v13.unknown()),
+  execution_cost_read_count: v13.number(),
+  execution_cost_read_length: v13.number(),
+  execution_cost_runtime: v13.number(),
+  execution_cost_write_count: v13.number(),
+  execution_cost_write_length: v13.number()
 });
-var contractCallTransactionSchema = v14.object({
-  tx_type: v14.literal("contract_call"),
-  contract_call: v14.object({
-    contract_id: v14.string(),
-    function_name: v14.string(),
-    function_signature: v14.string(),
-    function_args: v14.array(
-      v14.object({
-        hex: v14.string(),
-        repr: v14.string(),
-        name: v14.string(),
-        type: v14.string()
+var contractCallTransactionSchema = v13.object({
+  tx_type: v13.literal("contract_call"),
+  contract_call: v13.object({
+    contract_id: v13.string(),
+    function_name: v13.string(),
+    function_signature: v13.string(),
+    function_args: v13.array(
+      v13.object({
+        hex: v13.string(),
+        repr: v13.string(),
+        name: v13.string(),
+        type: v13.string()
       })
     )
   }),
   ...baseTransactionSchema.entries
 });
-var smartContractTransactionSchema = v14.object({
-  tx_type: v14.literal("smart_contract"),
-  smart_contract: v14.object({
+var smartContractTransactionSchema = v13.object({
+  tx_type: v13.literal("smart_contract"),
+  smart_contract: v13.object({
     /**
      * NOTE: The types may be wrong, not sure what type of value is used when
      * the version is not `null`.
      */
-    clarity_version: v14.union([v14.null(), v14.number()]),
-    contract_id: v14.string(),
-    source_code: v14.string()
+    clarity_version: v13.union([v13.null(), v13.number()]),
+    contract_id: v13.string(),
+    source_code: v13.string()
   }),
   ...baseTransactionSchema.entries
 });
-var tokenTransferSchema = v14.object({
-  tx_type: v14.literal("token_transfer"),
-  token_transfer: v14.object({
-    recipient_address: v14.string(),
-    amount: v14.string(),
-    memo: v14.string()
+var tokenTransferSchema = v13.object({
+  tx_type: v13.literal("token_transfer"),
+  token_transfer: v13.object({
+    recipient_address: v13.string(),
+    amount: v13.string(),
+    memo: v13.string()
   }),
   ...baseTransactionSchema.entries
 });
-var transactionSchema = v14.variant("tx_type", [
+var transactionSchema = v13.variant("tx_type", [
   contractCallTransactionSchema,
   smartContractTransactionSchema,
   tokenTransferSchema
 ]);
 
 // src/stacks-api/transactions/address-transactions.ts
-var v15 = __toESM(require("valibot"), 1);
-var resultSchema = v15.object({
+var v14 = __toESM(require("valibot"), 1);
+var resultSchema = v14.object({
   tx: transactionSchema,
-  stx_sent: v15.string(),
-  stx_received: v15.string(),
-  events: v15.object({
-    stx: v15.object({
-      transfer: v15.number(),
-      mint: v15.number(),
-      burn: v15.number()
+  stx_sent: v14.string(),
+  stx_received: v14.string(),
+  events: v14.object({
+    stx: v14.object({
+      transfer: v14.number(),
+      mint: v14.number(),
+      burn: v14.number()
     }),
-    ft: v15.object({
-      transfer: v15.number(),
-      mint: v15.number(),
-      burn: v15.number()
+    ft: v14.object({
+      transfer: v14.number(),
+      mint: v14.number(),
+      burn: v14.number()
     }),
-    nft: v15.object({
-      transfer: v15.number(),
-      mint: v15.number(),
-      burn: v15.number()
+    nft: v14.object({
+      transfer: v14.number(),
+      mint: v14.number(),
+      burn: v14.number()
     })
   })
 });
-var resultsSchema4 = v15.array(resultSchema);
-var addressTransactionsResponseSchema = v15.object({
+var resultsSchema4 = v14.array(resultSchema);
+var addressTransactionsResponseSchema = v14.object({
   ...baseListResponseSchema.entries,
   results: resultsSchema4
 });
@@ -981,7 +991,7 @@ async function addressTransactions(args) {
       data: jsonParseError
     });
   }
-  const validationResult = v15.safeParse(addressTransactionsResponseSchema, data);
+  const validationResult = v14.safeParse(addressTransactionsResponseSchema, data);
   if (!validationResult.success) {
     return error({
       name: "ValidateDataError",
@@ -993,7 +1003,7 @@ async function addressTransactions(args) {
 }
 
 // src/stacks-api/transactions/get-transaction.ts
-var v16 = __toESM(require("valibot"), 1);
+var v15 = __toESM(require("valibot"), 1);
 async function getTransaction(args) {
   const init = {};
   if (args.apiKeyConfig) {
@@ -1022,7 +1032,7 @@ async function getTransaction(args) {
       error: jsonParseError
     });
   }
-  const validationResult = v16.safeParse(transactionSchema, data);
+  const validationResult = v15.safeParse(transactionSchema, data);
   if (!validationResult.success) {
     return error({
       name: "ValidateDataError",
@@ -1033,20 +1043,156 @@ async function getTransaction(args) {
   return success(validationResult.output);
 }
 
+// src/stacks-api/transactions/index.ts
+var transactions = {
+  addressTransactions,
+  getTransaction
+};
+
 // src/stacks-api/index.ts
-var accounts = { balances, latestNonce };
-var blocks = { getBlock };
-var info = { coreApi, poxDetails };
-var proofOfTransfer = {
-  cycle,
-  cycles,
-  signerInCycle,
-  signersInCycle,
-  stackersForSignerInCycle
+var stacksApi = {
+  accounts,
+  blocks,
+  faucets,
+  info,
+  proofOfTransfer,
+  stackingPool,
+  transactions
+};
+
+// src/stacks-rpc-api/smart-contracts/map-entry.ts
+var v16 = __toESM(require("valibot"), 1);
+var mapEntryResponseSchema = v16.object({
+  /**
+   * Hex-encoded string of clarity value. It is always an optional tuple.
+   */
+  data: v16.string(),
+  /**
+   * Hex-encoded string of the MARF proof for the data
+   */
+  proof: v16.optional(v16.string())
+});
+async function mapEntry(args) {
+  const search = new URLSearchParams();
+  if (args.proof === 0) search.append("proof", "0");
+  if (args.tip) search.append("tip", args.tip);
+  const init = {};
+  if (args.apiKeyConfig) {
+    init.headers = {
+      [args.apiKeyConfig.header]: args.apiKeyConfig.key
+    };
+  }
+  init.method = "POST";
+  init.body = JSON.stringify(
+    args.mapKey.startsWith("0x") ? args.mapKey : `0x${args.mapKey}`
+  );
+  init.headers = { ...init.headers, "Content-Type": "application/json" };
+  const endpoint = `${args.baseUrl}/v2/map_entry/${args.contractAddress}/${args.contractName}/${args.mapName}?${search}`;
+  const res = await fetch(endpoint, init);
+  if (!res.ok) {
+    return error({
+      name: "FetchMapEntryError",
+      message: "Failed to fetch map entry.",
+      data: {
+        init,
+        status: res.status,
+        statusText: res.statusText,
+        endpoint,
+        bodyParseResult: await safePromise(res.text())
+      }
+    });
+  }
+  const [jsonError, data] = await safePromise(res.json());
+  if (jsonError) {
+    return error({
+      name: "ParseBodyError",
+      message: "Failed to parse response body as JSON.",
+      data: jsonError
+    });
+  }
+  const validationResult = v16.safeParse(mapEntryResponseSchema, data);
+  if (!validationResult.success) {
+    return error({
+      name: "ValidateDataError",
+      message: "Failed to validate response data.",
+      data: validationResult
+    });
+  }
+  return success(validationResult.output);
+}
+
+// src/stacks-rpc-api/smart-contracts/read-only.ts
+var v17 = __toESM(require("valibot"), 1);
+var readOnlyResponseSchema = v17.variant("okay", [
+  v17.object({
+    okay: v17.literal(true),
+    /**
+     * A Clarity value as a hex-encoded string.
+     */
+    result: v17.string()
+  }),
+  v17.object({
+    okay: v17.literal(false),
+    cause: v17.unknown()
+  })
+]);
+async function readOnly(args) {
+  const headers = {
+    "Content-Type": "application/json"
+  };
+  if (args.apiKeyConfig) {
+    headers[args.apiKeyConfig.header] = args.apiKeyConfig.key;
+  }
+  const init = {
+    method: "POST",
+    body: JSON.stringify({
+      sender: args.sender,
+      arguments: args.arguments
+    }),
+    headers
+  };
+  const endpoint = `${args.baseUrl}/v2/contracts/call-read/${args.contractAddress}/${args.contractName}/${args.functionName}`;
+  const res = await fetch(endpoint, init);
+  if (!res.ok) {
+    return error({
+      name: "FetchReadOnlyError",
+      message: "Failed to fetch.",
+      data: {
+        status: res.status,
+        statusText: res.statusText,
+        bodyParseResult: await safePromise(res.json())
+      }
+    });
+  }
+  const [jsonError, data] = await safePromise(res.json());
+  if (jsonError) {
+    return error({
+      name: "ParseBodyError",
+      message: "Failed to parse response body as JSON.",
+      data: error
+    });
+  }
+  const validationResult = v17.safeParse(readOnlyResponseSchema, data);
+  if (!validationResult.success) {
+    return error({
+      name: "ValidateDataError",
+      message: "Failed to validate data.",
+      data: validationResult
+    });
+  }
+  return success(validationResult.output);
+}
+
+// src/stacks-rpc-api/smart-contracts/index.ts
+var smartContracts = {
+  mapEntry,
+  readOnly
+};
+
+// src/stacks-rpc-api/index.ts
+var stacksRpcApi = {
+  smartContracts
 };
-var smartContracts = { readOnly };
-var stackingPool = { members };
-var transactions = { addressTransactions, getTransaction };
 
 // src/utils/call-rate-limited-api.ts
 var import_exponential_backoff = require("exponential-backoff");
@@ -1084,23 +1230,74 @@ async function safeCallRateLimitedApi(fn, options) {
   }
 }
 
-// src/index.ts
-var stacksApi = {
-  accounts,
-  blocks,
-  info,
-  proofOfTransfer,
-  smartContracts,
-  stackingPool,
-  transactions
+// src/queries/get-signer-stacked-amount.ts
+async function getSignerStackedAmount(args) {
+  let totalLocked = 0n;
+  const { identifier, ...rest } = args;
+  let hasMore = true;
+  let offset = 0;
+  let found = false;
+  const limit = 200;
+  while (hasMore && !found) {
+    const [error2, data] = await safeCallRateLimitedApi(
+      () => signersInCycle({
+        ...rest,
+        limit
+      })
+    );
+    if (error2) {
+      return error({
+        name: "GetSignerTotalLockedError",
+        message: "Failed to get signer total locked.",
+        data: {
+          error: error2
+        }
+      });
+    }
+    for (const signer of data.results) {
+      if (identifier.type === "address") {
+        if (signer.signer_address === identifier.signerAddress) {
+          totalLocked = BigInt(signer.stacked_amount);
+          found = true;
+          break;
+        }
+      } else {
+        if (signer.signing_key === identifier.signerPublicKey) {
+          totalLocked = BigInt(signer.stacked_amount);
+          found = true;
+          break;
+        }
+      }
+    }
+    offset += data.results.length;
+    hasMore = offset < data.total;
+  }
+  if (!found) {
+    return error({
+      name: "SignerNotFound",
+      message: "Signer not found.",
+      data: {
+        identifier,
+        cycle: args.cycleNumber
+      }
+    });
+  }
+  return success(totalLocked);
+}
+
+// src/queries/index.ts
+var queries = {
+  getSignerStackedAmount
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   callRateLimitedApi,
   error,
+  queries,
   safeCall,
   safeCallRateLimitedApi,
   safePromise,
   stacksApi,
+  stacksRpcApi,
   success
 });