Service Challenges

Overview

BTX service challenges allow any service operator to require computational proof-of-work from requesters, anchored to current network difficulty. Unlike fee gates, a service challenge proof cannot be prepaid in bulk — it requires fresh computation tied to present chain state.

Use Cases

• API rate limiting — gate endpoints behind proof-of-work (purpose=api_gate)
• Signup/comment spam — require work for account creation (purpose=rate_limit)
• AI inference gating — price access to model endpoints (purpose=ai_inference_gate)

getmatmulservicechallenge

Issue a domain-bound service challenge at a specific difficulty.

btx-cli getmatmulservicechallenge "api_gate" 120

Parameters

Name	Type	Description
purpose	string	Challenge domain: api_gate, rate_limit, ai_inference_gate
solve_time_target_secs	number	Target solve time in seconds (difficulty calibration)

Response

Field	Description
challenge_id	Unique challenge identifier
issued_at	ISO 8601 timestamp
expires_at	ISO 8601 expiry timestamp
header_context	Chain-anchored header for sigma reproduction
target	Difficulty target for this challenge

verifymatmulserviceproof

Stateless verification of a service challenge proof. Does not consume the proof.

btx-cli verifymatmulserviceproof '{
  "challenge_id": "...",
  "nonce64_hex": "...",
  "digest_hex": "..."
}'

redeemmatmulserviceproof

Atomic verify-and-consume. Rejects double-spend as already_redeemed.

btx-cli redeemmatmulserviceproof '{
  "challenge_id": "...",
  "nonce64_hex": "...",
  "digest_hex": "..."
}'

Batch Operations

verifymatmulserviceproofs

Batch verification for high-throughput gateways. Accepts an array of proof envelopes.

redeemmatmulserviceproofs

Batch verify-and-consume with sequential processing. Returns per-proof results with top-level reason summary counts. Suitable for queue workers and public API frontends.

Deployment Patterns

Single Node

For single-server deployments, all challenge issuance and redemption goes through one btxd instance. The service challenge store is in-process memory (10,000 challenge capacity).

Multi Node

For multi-node deployments, challenges must be redeemed on the same node that issued them. Use sticky routing (session affinity) or a shared challenge store.

The service challenge store is local process-memory only. If btxd restarts, all unredeemed challenges are lost.