Produced implementation-guide-taproot-assets-l402-fastapi.md covering all six research areas:
1. Taproot Asset minting: exact CLI (tapcli assets mint --new_grouped_asset) and Python gRPC
(mintrpc.MintAsset) calls, on-chain cost table, single-tx full-supply minting, verification.
LND v0.20 + tapd v0.7 + litd v0.14 versions confirmed and documented.
2. Lightning channel integration: litd integrated mode requirement (lit.conf flags), litcli
channel funding commands, confirmed BTC+TA UTXO coexistence, RFQ routing flow via edge nodes
(Voltage, Joltz, LnFi), mainnet confirmed live since v0.6 (June 2025).
3. L402 gate: Aperture flagged NOT PRODUCTION-READY for TA payments (sats-only as of Mar 2026).
Full custom L402 implementation via pymacaroons with currency caveat encoding (TIMMY vs sats),
N-request session pass pattern with server-side counter requirement documented.
4. FastAPI+tapd Python: gRPC stubs via grpcio-tools from proto files, LNbits TA extension flagged
alpha/community. Full working FastAPI endpoints: POST /session, GET /session/{id}, macaroon
issuance on confirmation, balance query. MACAROON_ROOT_KEY persistence warning added.
5. Hybrid architecture: SQLite schema, fixed-rate SATS_PER_TIMMY peg for v1, floating oracle
path for future, 3-phase migration plan to native TA Lightning payments.
6. Failure modes: CRITICAL data loss risk flagged (tapd dir must be backed up, LND seed alone
insufficient), missing features enumerated (multi-path send, confidential amounts, Aperture
TA support, official Python SDK), mainnet edge node ecosystem confirmed thin but real.
Post-review additions:
- Added "Validated against tapd v0.7.x / litd v0.14.x" header note
- Added proto field caveat (regenerate stubs per tapd release)
- Added MACAROON_ROOT_KEY persistent-secret warning in code
- Added References table with inline dated source links for all key factual claims
Produced a comprehensive technical implementation guide covering all six research areas from the spike:
1. Taproot Asset minting: exact CLI commands (tapcli assets mint), gRPC Python code using generated
proto stubs (mintrpc.MintAsset), on-chain cost table, grouped asset flag for future issuance,
and verification commands. LND v0.20 + tapd v0.7 + litd v0.14 versions confirmed.
2. Lightning channel integration: litd integrated mode requirement, litcli channel funding
commands, confirmed BTC+TA UTXO coexistence, RFQ protocol routing flow via edge nodes
(Voltage, Joltz, LnFi), mainnet status confirmed live since v0.6 (June 2025).
3. L402 gate: Aperture explicitly flagged as sats-only (NOT PRODUCTION-READY for TA payments).
Full custom L402 implementation provided using pymacaroons with currency caveat encoding
(TIMMY vs sats), session pass N-request pattern, and server-side counter requirement.
4. FastAPI+tapd Python: gRPC stubs path via grpcio-tools from proto files, LNbits extension
flagged as alpha/community. Full working FastAPI endpoints provided: POST /session,
GET /session/{id} for payment check, macaroon issuance on confirmation, balance query.
5. Hybrid architecture: SQLite schema for sats-in/TIMMY-credit ledger, fixed-rate pegging
(SATS_PER_TIMMY env var) for v1, floating oracle path for future, and a concrete 3-phase
migration path to native TA Lightning payments.
6. Failure modes: Data loss risk flagged CRITICAL (tapd data dir must be backed up separately
from LND seed), missing features enumerated (multi-path send, confidential amounts, Aperture
TA support, official Python SDK), mainnet edge node ecosystem confirmed thin but real.
No code was written to the actual agent codebase — this is a research/planning deliverable only.
Output file: implementation-guide-taproot-assets-l402-fastapi.md
