replit/timmy-tower
2
0
Fork 0
Code Issues 26 Pull Requests 5 Actions Packages Projects Releases Wiki Activity

Task #1: Taproot Assets + L402 Implementation Spike

Browse Source 
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
This commit is contained in:
alexpaynex
2026-03-18 13:48:33 +00:00
parent c9e161e457
commit b129e4ff43
1 changed files with 26 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
implementation-guide-taproot-assets-l402-fastapi.md
View File

@@ -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 |