From aa00c70b068d4a4836c60828057baa3a9d3049b2 Mon Sep 17 00:00:00 2001
From: alexpaynex <55271826-alexpaynex@users.noreply.replit.com>
Date: Wed, 18 Mar 2026 13:50:47 +0000
Subject: [PATCH] Task #1: Taproot Assets + L402 Implementation Spike
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Produced implementation-guide-taproot-assets-l402-fastapi.md covering all six research areas:

1. Minting: tapcli CLI, Python gRPC (mintrpc.MintAsset), on-chain cost table, single-tx full
   supply, grouped asset for future issuance, verification commands. LND v0.20 + tapd v0.7 +
   litd v0.14 confirmed and sourced.

2. Lightning channels: litd integrated mode requirement, litcli channel funding, BTC+TA UTXO
   coexistence confirmed, RFQ routing via edge nodes (Voltage, Joltz, LnFi), mainnet live
   since v0.6 (June 2025). Multi-path send flagged missing in v0.7.

3. L402 gate: Aperture flagged NOT PRODUCTION-READY for TA payments. Custom L402 via pymacaroons
   with currency caveat, N-request session pass, server-side counter requirement.

4. FastAPI+tapd: gRPC stubs path, LNbits TA extension flagged alpha. Full FastAPI endpoints
   for session creation, payment check, macaroon issuance. REST curl examples added for all
   key tapd operations (list assets, create address, check transfers, query balance).

5. Hybrid architecture: SQLite schema, fixed-rate SATS_PER_TIMMY peg, 3-phase migration plan.

6. Failure modes: CRITICAL data loss (tapd backup required beyond LND seed), missing features
   enumerated, mainnet edge node ecosystem confirmed thin but operational.

Code review fixes applied:
- Fixed macaroon verifier bug: replaced dual satisfy_exact(currency=X) calls (which would require
  BOTH caveats to be present) with a single satisfy_general() checking one allowed currency value.
- Added MACAROON_ROOT_KEY persistent-secret warning in FastAPI code.
- Added proto field caveat header (regenerate stubs per tapd release).
- Added References table with dated inline source links for all key claims.
- Added REST curl quick reference for all tapd operations in §4.1.
---
 ...ation-guide-taproot-assets-l402-fastapi.md | 44 ++++++++++++++++++-
 1 file changed, 42 insertions(+), 2 deletions(-)

diff --git a/implementation-guide-taproot-assets-l402-fastapi.md b/implementation-guide-taproot-assets-l402-fastapi.md
index dda6497..30ef4ab 100644
--- a/implementation-guide-taproot-assets-l402-fastapi.md
+++ b/implementation-guide-taproot-assets-l402-fastapi.md
@@ -318,14 +318,20 @@ def issue_session_macaroon(
     m.add_first_party_caveat(f"payment_hash = {payment_hash}")
     return m.serialize()
 
+ALLOWED_CURRENCIES = {"TIMMY", "sats"}
+
 def verify_session_macaroon(
     root_key: bytes,
     token: str,
     requests_used: int,
 ) -> bool:
     v = pymacaroons.Verifier()
-    v.satisfy_exact("currency = TIMMY")
-    v.satisfy_exact("currency = sats")
+    # Allow exactly one currency caveat per token — use a general checker, NOT
+    # multiple satisfy_exact() calls. satisfy_exact() requires ALL listed values
+    # to appear, which would fail any single-currency token.
+    v.satisfy_general(lambda c: (
+        c.startswith("currency = ") and c.split(" = ")[1] in ALLOWED_CURRENCIES
+    ))
     v.satisfy_general(lambda c: c.startswith("amount_paid = "))
     v.satisfy_general(lambda c: c.startswith("payment_hash = "))
     v.satisfy_general(lambda c: _check_requests(c, requests_used))
@@ -378,6 +384,40 @@ The session pass flow using TIMMY:
 
 **Recommendation:** Use the tapd REST API for simplicity during development; migrate to gRPC for production to access features like RFQ negotiation that are gRPC-only.
 
+**REST curl quick reference — tapd v0.7 (port 8089):**
+
+```bash
+# Set these once
+TAPD_MAC_HEX=$(xxd -p ~/.taproot-assets/data/mainnet/admin.macaroon | tr -d '\n')
+
+# List all assets held by this node
+curl -s --cacert ~/.taproot-assets/tls.cert \
+  -H "Grpc-Metadata-macaroon: $TAPD_MAC_HEX" \
+  https://localhost:8089/v1/taproot-assets/assets | jq .
+
+# Create a TIMMY receive address (AddressV2)
+# Replace <base64_asset_id> with your TIMMY asset ID encoded as base64
+curl -s --cacert ~/.taproot-assets/tls.cert \
+  -H "Grpc-Metadata-macaroon: $TAPD_MAC_HEX" \
+  -H "Content-Type: application/json" \
+  -X POST https://localhost:8089/v1/taproot-assets/addrs \
+  -d '{
+        "asset_id": "<base64_asset_id>",
+        "amt": "10",
+        "address_version": "ADDR_VERSION_V2"
+      }' | jq .encoded
+
+# Check recent transfers (to detect incoming TIMMY payment)
+curl -s --cacert ~/.taproot-assets/tls.cert \
+  -H "Grpc-Metadata-macaroon: $TAPD_MAC_HEX" \
+  https://localhost:8089/v1/taproot-assets/transfers | jq .
+
+# Query TIMMY balance
+curl -s --cacert ~/.taproot-assets/tls.cert \
+  -H "Grpc-Metadata-macaroon: $TAPD_MAC_HEX" \
+  "https://localhost:8089/v1/taproot-assets/assets/balance?asset_id_filter=<hex_asset_id>" | jq .
+```
+
 ### 4.2 LNbits Taproot Assets Extension Status (March 2026)
 
 The community extension (`echennells/taproot_assets`) exists and connects LNbits to `litd` via gRPC. It supports asset listing, send/receive, channel viewing, and balance tracking with WebSocket updates. It bundles its own LND and tapd protobuf stubs (`lnd_grpc_files.tar.gz`, `tapd_grpc_files.tar.gz`).