From b129e4ff43153facfd86986573f1b629677ff7fb Mon Sep 17 00:00:00 2001 From: alexpaynex <55271826-alexpaynex@users.noreply.replit.com> Date: Wed, 18 Mar 2026 13:48:33 +0000 Subject: [PATCH] Task #1: Taproot Assets + L402 Implementation Spike 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 --- ...ation-guide-taproot-assets-l402-fastapi.md | 27 ++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/implementation-guide-taproot-assets-l402-fastapi.md b/implementation-guide-taproot-assets-l402-fastapi.md index cd92a46..dda6497 100644 --- a/implementation-guide-taproot-assets-l402-fastapi.md +++ b/implementation-guide-taproot-assets-l402-fastapi.md @@ -2,9 +2,12 @@ **Project:** Timmy Agent **Date:** March 18, 2026 +**Validated against:** tapd v0.7.x / litd v0.14.x / LND v0.20.0-beta (December 2025 release cycle) **Scope:** Concrete architecture and code paths for TIMMY token minting, Lightning channel integration, L402 payment gating, and FastAPI/Python wiring **Convention:** `⚠️ NOT PRODUCTION-READY` marks anything that is alpha, testnet-only, or has a known breaking limitation. `✅ MAINNET` marks confirmed production-viable paths. +> **Proto field caveat:** gRPC stubs must be regenerated from the `.proto` files of each tapd release. Field names and message structures may change between minor versions. Always run `python -m grpc_tools.protoc` against the proto files from the exact tapd version you are running, and re-validate field names in the Python snippets below against your generated stubs before production use. + --- ## Prerequisites and Stack Versions @@ -410,6 +413,10 @@ TAPD_TLS = Path(os.getenv("TAPD_TLS_PATH", "~/.taproot-assets/tls.cert")).ex TAPD_MAC = Path(os.getenv("TAPD_MAC_PATH", "~/.taproot-assets/data/mainnet/admin.macaroon")).expanduser() TIMMY_ID = bytes.fromhex(os.getenv("TIMMY_ASSET_ID", "")) # 32-byte asset id hex MACAROON_ROOT_KEY = bytes.fromhex(os.getenv("MACAROON_ROOT_KEY", secrets.token_hex(32))) +# ⚠️ PRODUCTION REQUIREMENT: MACAROON_ROOT_KEY must be a stable, persistent secret stored in an +# environment variable or secrets manager. The default fallback (secrets.token_hex) generates a +# new random key on every process restart, which INVALIDATES ALL PREVIOUSLY ISSUED MACAROONS. +# Set MACAROON_ROOT_KEY once at deployment and never rotate it without invalidating active sessions. # ── tapd gRPC channel ──────────────────────────────────────────────────────── def _tapd_creds(): @@ -700,4 +707,22 @@ The Lightning Labs team declared **forward compatibility** starting with the v0. --- -*Sources: Lightning Labs official tapd documentation and API reference (lightning.engineering), tapd GitHub repository (v0.7), LND v0.20 release notes, Taproot Assets Builder's Guide, echennells/taproot_assets LNbits extension, pymacaroons library documentation, L402 specification (lightning.engineering/posts), Voltage/Joltz/LnFi edge node announcements.* +## References + +| Claim | Source | Date | +|-------|--------|------| +| LND v0.20 required for tapd v0.7 | [Lightning Labs API Docs — tapd](https://lightning.engineering/api-docs/api/taproot-assets/) | Dec 2025 | +| tapd v0.7 mainnet release | [tapd GitHub releases](https://github.com/lightninglabs/taproot-assets/releases) | Dec 2025 | +| TA Lightning channel support live mainnet v0.6 | [Lightning Labs blog — Taproot Assets v0.6](https://lightning.engineering/posts/2025-06-taproot-assets-v0-6/) | Jun 2025 | +| BTC + TA channels in same UTXO | [Taproot Assets Builder's Guide](https://docs.lightning.engineering/lightning-network-tools/taproot-assets) | 2025 | +| RFQ protocol mainnet, multi-path receive (20 channels) | tapd v0.6 release notes | Jun 2025 | +| AddressV2 static reusable addresses | tapd v0.7 release notes | Dec 2025 | +| Edge node operators: Voltage, Amboss, Joltz, Speed, LnFi | [Voltage blog](https://voltage.cloud), [Joltz docs](https://joltz.app) | 2025–2026 | +| Aperture L402 sats-only (no native TA payment support) | [Aperture GitHub](https://github.com/lightninglabs/aperture) — no TA payment backend | Mar 2026 | +| LNbits TA extension (echennells) | [echennells/taproot_assets GitHub](https://github.com/echennells/taproot_assets) | 2025 | +| Data loss warning — LND seed insufficient for TA restore | [tapd official docs safety warning](https://docs.lightning.engineering/lightning-network-tools/taproot-assets) | 2025 | +| Multi-path send not implemented in v0.7 | tapd v0.7 release notes / GitHub milestones | Dec 2025 | +| Alpha software warning, bugs and missing backup mechanisms | [tapd docs](https://docs.lightning.engineering/lightning-network-tools/taproot-assets) | 2025 | +| pymacaroons library | [pymacaroons PyPI](https://pypi.org/project/pymacaroons/) | — | +| L402 specification | [lightning.engineering/posts/2023-06-07-l402](https://lightning.engineering/posts/2023-06-07-l402/) | Jun 2023 | +| LangChainBitcoin L402 Python | [lightninglabs/LangChainBitcoin](https://github.com/lightninglabs/LangChainBitcoin) | 2023 |