feat: add sBTC testnet faucet endpoint

[rafa-stacks]

Description

As a developer building on Stacks testnet, I want a faucet that dispenses sBTC so I can test sBTC-dependent flows without manually acquiring tokens — mirroring the existing STX and regtest-BTC faucets.

This PR adds a new endpoint POST /extended/v1/faucets/sbtc that sends an sBTC SIP-010 token transfer to a requested testnet address.

What was changed:

• New route (src/api/routes/v1/faucets.ts): POST /extended/v1/faucets/sbtc?address=<ST...>. It performs a SIP-010 transfer contract call from the first key in FAUCET_PRIVATE_KEY to the recipient, with an exact-amount fungible-token post-condition. It reuses the STX faucet's nonce tracking, custom chain-ID detection, and fee-estimation fallback (fixed fee when the node can't estimate), and is rate-limited to 5 requests / 5 minutes per address.
• New env vars (src/env.ts):
  • TESTNET_SBTC_FAUCET_ENABLED — defaults to false (opt-in, since it requires the faucet account to actually hold sBTC).
  • TESTNET_SBTC_FAUCET_ASSET_IDENTIFIER — fully-qualified asset id {address}.{contract}::{asset}. Defaults to the official testnet sBTC deployment ST1F7QA2MDF17S807EPA36TSS8AMEFY4KA9TVGWXT.sbtc-token::sbtc-token.
  • TESTNET_SBTC_FAUCET_AMOUNT — sats per request, defaults to 10000 (0.0001 sBTC).
• Datastore: added DbFaucetRequestCurrency.SBTC and getSBTCFaucetRequests for rate-limit tracking. The faucet_requests.currency column is a plain string, so no migration is needed.
• Generated artifacts: regenerated openapi.yaml and client/src/generated/schema.d.ts. The diff also picks up the v3 principal balance endpoints from feat: materialized locked-STX table and v3 principal balance endpoints #2577, which were never regenerated when that PR merged.

How this impacts application developers:

A new opt-in testnet-only faucet endpoint is available. Existing behavior is unchanged; the endpoint returns 403 unless TESTNET_SBTC_FAUCET_ENABLED=true.

Example:

curl -X POST 'https://api.testnet.hiro.so/extended/v1/faucets/sbtc?address=ST3M7N9Q9HDRM7RVP1Q26P0EE69358PZZAZD7KMXQ'

{ "success": true, "txId": "0x...", "txRaw": "..." }

Type of Change

• New feature
• Bug fix
• API reference/documentation update
• Other

Does this introduce a breaking change?

No.

Are documentation updates required?

• Link to documentation updates: the new endpoint is documented via the OpenAPI spec (run_faucet_sbtc).

Testing information

Added tests/krypton/faucet-sbtc/faucet-sbtc.test.ts, which deploys a minimal sbtc-token contract from the faucet account on the krypton devnet, points the env at it, and asserts: the request succeeds, the tx mines as a transfer contract call, the recipient's FT balance matches the configured amount, and the 400 (missing address) / 403 (disabled) error paths. Run with npm run test:krypton:faucet-sbtc — all 5 tests pass locally against Docker.

Note: the krypton node image only accepts up to Clarity 2, so the test deploy pins clarityVersion: Clarity2. The CI matrix entry is added but commented out, matching the other krypton suites.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 35.14851% with 131 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/api/routes/v1/faucets.ts	29.65%	121 Missing ⚠️
src/datastore/pg-store.ts	16.66%	10 Missing ⚠️

📢 Thoughts on this report? Let us know!