DenBridge Relayer

Backend helper service for the DenBridge Console. It watches EVM transaction confirmation and detects the corresponding USDCx mint on Stacks via Hiro API, then exposes status and receipt data to the frontend.

Responsibilities

• Track bridge sessions started from the web app
• Confirm EVM tx inclusion via Sepolia RPC
• Detect Stacks USDCx balance increases
• Provide receipt parsing for batch payroll txs

Endpoints

• GET /health -> service status + config snapshot
• POST /bridge/start -> initialize a bridge session
• GET /bridge/status?evmTxHash=0x... -> poll bridge state
• GET /receipt?txid=... -> parse and summarize Stacks tx events

Environment

Copy .env.example to .env and fill in values.

Required:

• SEPOLIA_RPC_URL
• EVM_CHAIN_ID (defaults to 11155111)
• EVM_USDC_ADDRESS
• EVM_XRESERVE_ADDRESS
• HIRO_STACKS_API_BASE
• RELAYER_PORT (defaults to 8787)
• STACKS_USDCX_TOKEN_CONTRACT (format: ST...contract::token-name)

Development

From repo root:

pnpm i
pnpm relayer

Or from this directory:

pnpm i
pnpm dev

Health check:

curl http://localhost:8787/health

Notes

• The relayer does not submit transactions; it only validates and reports status.
• Bridge sessions are stored in-memory; restart clears active sessions.