diff --git a/docs/taproot-l402-spike.md b/docs/taproot-l402-spike.md new file mode 100644 index 0000000..e86668f --- /dev/null +++ b/docs/taproot-l402-spike.md @@ -0,0 +1,180 @@ +# Research Spike: Taproot Assets + L402 + +This document outlines the findings of a research spike into the feasibility of using Taproot Assets and L402 for the Timmy token. + +## Taproot Asset Minting + +This section details the process of minting Taproot Assets. + +### `tapd` Version Requirements + +`tapd` version `v0.3.0-alpha` or later is required. This version of `tapd` requires LND version `v0.16.2-beta` or later. + + +### LND Compile Flags + +To enable LND to work with Taproot Assets, LND must be compiled with the following tags: +`make install tags="signrpc walletrpc chainrpc invoicesrpc"` +These tags enable the RPC services that `tapd` requires to interact with LND. + + +### gRPC Mint Call + +The `tapd` gRPC API provides a `Mint` call to create new assets. The call takes a `MintAsset` request which includes details about the asset to be minted, such as the asset type, name, and supply. + +### On-chain Cost Estimate + +The on-chain cost for minting Taproot Assets is the fee for a single standard Taproot Bitcoin transaction. The cost depends on two factors: +1. **Transaction Size:** The size of the minting transaction in virtual bytes. A single transaction can mint a large number of assets. +2. **Bitcoin Network Fees:** The current network fee rate in satoshis per virtual byte (sats/vB). + +The witness data for the assets is stored off-chain, which minimizes the on-chain transaction size and therefore the cost. + + +### Single-transaction Full-supply Mint + +The Taproot Assets protocol supports minting the full supply of an asset in a single on-chain transaction. This is efficient as it minimizes on-chain fees. + +### Verification Commands + +Asset issuance and ownership can be verified using the `tapcli` command-line interface. Key commands include: + +* `tapcli assets balance --by_group`: Displays the cumulative balance for each asset. +* `tapcli addrs query`: Inspects a Taproot Asset address. + +Verification also relies on "universes," which act as repositories for asset information. A `tapd` node synchronizes with a universe to verify the authenticity of an asset. + +## TA Lightning Channels + +This section covers the use of Taproot Assets in Lightning Network channels. + +### LND v0.20+ Support Status + +LND version `v0.20.0-beta` and later supports Taproot Asset channels. This functionality is enabled through the `litd` (Lightning Terminal Daemon), which integrates `lnd` and `tapd`. + +### How TA channels are funded + +Taproot Asset channels are funded by depositing Taproot Assets into a Lightning channel. The funding transaction uses a MuSig2 2-of-2 multisig, where the two participants' keys are aggregated into a single key. A small amount of satoshis is also required to anchor the Taproot Asset in a Hashed Timelock Contract (HTLC). + + +### BTC/TA UTXO Coexistence + +Bitcoin and Taproot Asset UTXOs coexist on the Bitcoin blockchain. Taproot Assets are created by embedding asset metadata into an existing Bitcoin UTXO using the Taproot upgrade. The detailed asset metadata is stored off-chain, making Taproot Asset transactions appear as standard Bitcoin transactions on the blockchain. This enhances privacy and efficiency. + + +### Routing Behaviour When No TA Route Exists + +If a direct Lightning route for a Taproot Asset does not exist, the payment can be routed through the existing Bitcoin Lightning Network. This is facilitated by "edge nodes" that perform atomic swaps between the Taproot Asset and Bitcoin. The sender's wallet can use a Request for Quote (RFQ) service to get a price for the swap, which is then included in the invoice. + + +### Edge-node BTC Conversion + +Edge nodes are specialized Lightning routing nodes that facilitate the conversion between Taproot Assets and Bitcoin. They hold liquidity in both assets and can perform atomic swaps using Hashed Timelock Contracts (HTLCs). A Request for Quote (RFQ) service is used to determine the exchange rate for the swap. This allows a user with a Taproot Asset to pay any standard Bitcoin Lightning invoice. + +## L402 + TA Integration + +This section explores the integration of Taproot Assets with the L402 protocol. + +### Aperture Native Support + +Aperture is an L402 reverse proxy that was developed by Lightning Labs, the same team that developed the Taproot Assets protocol. It is designed to work with Taproot Assets, allowing for payment-gated API access using Taproot Assets as credentials. + +### Custom Code Path + +No custom code path is required to accept Taproot Assets as L402 credentials. The distinction between a Taproot Asset payment and a satoshi payment is handled at the Lightning Network layer. + +### Macaroon Encoding + +There is no special encoding required in the macaroon to differentiate between a TIMMY token payment and a satoshi payment. The L402 macaroon contains a `payment_hash` that corresponds to a Lightning invoice. This invoice can be settled with either satoshis or a Taproot Asset. The validation of the payment is done by verifying the `payment_hash`, regardless of the asset used for payment. + +## Python/FastAPI + tapd + +This section covers the integration of `tapd` with Python and FastAPI. + +### Production-ready Python Path + +The most production-ready path for interacting with `tapd` from Python is to use the gRPC API. Python gRPC client stubs can be generated from the `.proto` files provided by Lightning Labs. This provides a direct and strongly-typed interface to the `tapd` API. Alternatively, the REST API can be used with a standard Python HTTP client library like `requests`. + +### LNbits Extension Status + +As of March 2026, an LNbits extension for Taproot Assets is available and under active development. It provides a user interface for managing assets, sending and receiving invoices, and viewing channels. The extension requires an LNbits instance with access to a `tapd` instance. + + +### FastAPI Endpoint Draft + +This is a conceptual draft of a FastAPI endpoint for minting a Taproot Asset. It assumes that the gRPC client stubs have been generated and are available in the `taprootassets_pb2` and `taprootassets_pb2_grpc` modules. + +```python +import os +import grpc +import base64 +from fastapi import FastAPI, HTTPException +from pydantic import BaseModel + +# Load the macaroon and TLS cert +macaroon = base64.b64encode(open(os.path.expanduser('~/.tapd/data/regtest/admin.macaroon'), 'rb').read()).decode() +os.environ["GRPC_SSL_CIPHER_SUITES"] = 'HIGH+ECDSA' +cert = open(os.path.expanduser('~/.tapd/tls.cert'), 'rb').read() +ssl_creds = grpc.ssl_channel_credentials(cert) + +# Create the gRPC channel +channel = grpc.secure_channel('localhost:10029', ssl_creds) +stub = taprootassets_pb2_grpc.TaprootAssetsStub(channel) + +app = FastAPI() + +class MintRequest(BaseModel): + asset_name: str + supply: int + +@app.post("/mint") +async def mint_asset(mint_request: MintRequest): + """ + Mints a new Taproot Asset. + """ + try: + request = taprootassets_pb2.MintAsset( + asset=taprootassets_pb2.Asset( + asset_genesis=taprootassets_pb2.AssetGenesis( + name=mint_request.asset_name, + meta="", + asset_type=taprootassets_pb2.NORMAL, + ), + amount=mint_request.supply, + ), + ) + response = stub.Mint(request, metadata=[('macaroon', macaroon)]) + return {"status": "success", "response": str(response)} + except grpc.RpcError as e: + raise HTTPException(status_code=500, detail=f"gRPC error: {e.details()}") + +``` + +This draft shows how to connect to the `tapd` gRPC API, define a Pydantic model for the request body, and create a FastAPI endpoint that calls the `Mint` RPC. + +## Go/No-Go Recommendation + +**Recommendation: Go** + +The research indicates that using Taproot Assets and L402 for the Timmy token is feasible. The technology is available and well-documented, and the integration path is clear. + +### Risk Table + +| Risk | Mitigation | +|---|---| +| **Software immaturity:** `tapd` is still alpha software. | Use the latest stable versions and test thoroughly on testnet before deploying to mainnet. | +| **Liquidity:** Edge nodes require liquidity in both BTC and the TIMMY token. | Partner with existing liquidity providers or bootstrap liquidity with dedicated funds. | + +### Estimated Development Days + +| Task | Estimated Days | +|---|---| +| Setup and configuration of `lnd` and `tapd` | 3 | +| Minting of TIMMY token | 1 | +| Development of FastAPI API | 5 | +| Integration with L402 | 3 | +| **Total** | **12** | + + + +