From 6ef2edd30a020ad749acf5132644081090fc39f9 Mon Sep 17 00:00:00 2001 From: unknown Date: Sat, 8 Mar 2025 17:25:43 -0500 Subject: [PATCH 1/3] Propose new BIP for Programmable Bitcoin Token Standard (PBTS) --- bip-pbst.md | 308 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 308 insertions(+) create mode 100644 bip-pbst.md diff --git a/bip-pbst.md b/bip-pbst.md new file mode 100644 index 0000000000..960438f30c --- /dev/null +++ b/bip-pbst.md @@ -0,0 +1,308 @@ +# BIP-XXXX: Programmable Bitcoin Token Standard (PBTS) + +``` +BIP: XXXX +Layer: Applications +Title: Programmable Bitcoin Token Standard (PBTS) +Author: Gobi Shanthan , Lee Raj. +Comments-Summary: No comments yet. +Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-XXXX +Status: Draft +Type: Standards Track +Created: 2025-02-11 +License: BSD-2-Clause +Discussions-To: bitcoin-dev@lists.linuxfoundation.org +Post-History: 2025-02-11 +Requires: 340, 341, 342 +``` + +## Abstract + +The **Programmable Bitcoin Token Standard (PBTS)** introduces a method to create, transfer, and validate native Bitcoin-based tokens using **Bitcoin Script** and **Taproot**. PBTS enhances Bitcoin's Layer 1 functionality by enabling **tokenized assets** with programmable conditions without compromising security, decentralization, or predictability. Unlike Ethereum or Solana, PBTS **does not introduce Turing-complete smart contracts** but leverages **structured pre-commitments** and **Taproot optimizations** to enable secure, efficient programmable tokens. + +PBTS is a **non-consensus-breaking, backward-compatible** standard that ensures tokens remain verifiable and transferable without requiring modifications to Bitcoin's core protocol. + +## Copyright + +This BIP is licensed under the BSD 2-clause license. + +## Motivation + +Bitcoin adheres to the principles of **minimalism and security**, which have made it the most robust and decentralized blockchain. PBTS aligns with this philosophy by introducing **programmability without complexity**, ensuring that Bitcoin's core remains unchanged while extending its utility in a predictable and efficient way. + +Bitcoin currently lacks a **native** token standard that enables **flexible** and **fully Layer 1** token issuance with programmable conditions. Existing solutions such as **Ordinals, RGB, and Runes** either rely on **external tracking mechanisms** or **Layer 2 solutions** that introduce centralization risks. PBTS provides a **UTXO-based**, predefined, and non-intrusive method for issuing tokens that remain completely **verifiable on Bitcoin's base layer** with advanced programmable features like time-locked vesting and milestone-based escrow. + +## Key Benefits + +1. **No Additional Layers** + * Execution happens directly in **Bitcoin transactions** + * Complete validation on **Layer 1** + * No external dependencies for validation + +2. **Predefined & Deterministic Execution** + * No infinite loops or dynamic state modifications + * Predictable execution paths + * Fixed state transitions + +3. **Minimal Impact** + * Utilizes existing **Taproot** and **Script** functionality + * No consensus changes required + * Standard transaction format + +4. **Scalability & Efficiency** + * **Merkle proof-based validation** + * Minimal transaction sizes through Taproot optimization + * Compatible with future Bitcoin scaling solutions + +5. **Security Model** + * No external validators required + * Fully **self-custodial** + * Bitcoin-native security + +6. **Programmable Conditions** + * Time-locked transfers (vesting) + * Milestone-based escrow with multiple release stages + * Multi-signature requirements + * Prepared for oracle integration + +## Comparison with Existing Bitcoin Token Standards + +| Feature | Ordinals | Runes | PBTS | +|----------------------------|--------------------------|-----------------|------------------------------| +| UTXO-Based | ❌ No (Inscriptions) | ✅ Yes | ✅ Yes | +| Requires External Indexer? | ✅ Yes | ✅ Yes | ❌ No | +| Efficient for Tokens? | ❌ No | ✅ Somewhat | ✅ Fully Optimized | +| Scalability Impact | ❌ High Blockchain Bloat | ⚠️ Medium | ✅ Minimal (Uses Taproot) | +| Bitcoin Script-Based? | ❌ No | ✅ Yes | ✅ Yes (Taproot-Optimized) | +| Consensus Changes Required?| ❌ No | ❌ No | ❌ No | +| Transaction Cost | ❌ Expensive | ⚠️ Medium | ✅ Efficient | +| Programmable Conditions | ❌ No | ⚠️ Limited | ✅ Yes | +| Fully On-Chain Validation | ❌ No | ❌ No | ✅ Yes | + +## Specification + +### Overview + +PBTS tokens are created, transferred, and validated directly on Bitcoin's Layer 1 using Taproot scripts to enable complex programmable conditions without requiring any modifications to the Bitcoin protocol. + +### Token Creation + +A **PBTS token** is created by locking a **UTXO** with a **Taproot script** that commits to a token issuance structure. The token metadata is encoded in the transaction output using a standardized format: + +1. **Token Issuance Format**: + * The output script is a Taproot output that contains: + * Token ID: A 32-byte identifier (Hash of Issuer's Public Key + Script Hash) + * Total Supply: Fixed integer representing the maximum possible supply + * Decimals: Integer representing the decimal places (typically 8 to match satoshis) + * Metadata Commitment: Optional hash of off-chain metadata (name, symbol, description) + +2. **Example Issuance Script**: +``` + OP_DROP + OP_CHECKSIG +``` + +### Token Contracts + +PBTS supports several programmable contract types that define how tokens can be transferred and under what conditions they can be spent: + +#### 1. Auto-Vest (Time-Locked) Contracts + +Time-locked transfers where tokens become available to the recipient only after a specific date, using Bitcoin's CHECKLOCKTIMEVERIFY opcode. + +**Script Pattern**: +``` +IF + OP_CHECKLOCKTIMEVERIFY OP_DROP + OP_CHECKSIG +ELSE + OP_CHECKSIG +ENDIF +``` + +#### 2. Milestone-Based Escrow + +Structured transfers with multiple release stages, each requiring specific conditions like time thresholds and multi-signature approvals. + +**Script Pattern**: +``` +IF + # Milestone 1 + OP_CHECKLOCKTIMEVERIFY OP_DROP + OP_CHECKMULTISIG +ELSEIF + # Milestone 2 + OP_CHECKLOCKTIMEVERIFY OP_DROP + OP_CHECKMULTISIG +ELSEIF + # Expiry condition (return to sender) + OP_CHECKLOCKTIMEVERIFY OP_DROP + OP_CHECKSIG +ENDIF +``` + +#### 3. Oracle-Ready Contracts + +Contracts designed to work with external data oracles, containing placeholder structures for future oracle implementation. + +**Script Pattern**: +``` +IF + # Oracle verification + OP_CHECKSIGVERIFY + OP_SHA256 OP_EQUALVERIFY + OP_CHECKSIG +ELSEIF + # Expiry condition (return to sender) + OP_CHECKLOCKTIMEVERIFY OP_DROP + OP_CHECKSIG +ENDIF +``` + +### Token Transfer + +PBTS token transfers involve creating transactions that spend from token-containing UTXOs and create new UTXOs with the appropriate scripts to maintain token properties and conditions. + +1. **Standard Transfer**: + * Spends from a token UTXO + * Creates new outputs with token metadata preserved + * May split tokens across multiple outputs (for partial transfers) + +2. **Conditional Transfer**: + * Creates outputs with Taproot scripts encoding the conditional logic + * Enables time-locked, multi-signature, or other programmable conditions + +3. **Transaction Validation**: + * Follows standard Bitcoin transaction validation rules + * Leverages Bitcoin's native UTXO model for tracking ownership + * Enables verification without external indexers or oracles + +### Implementation Details + +#### Taproot Integration + +PBTS leverages Taproot's script path spending to enable complex script execution while maintaining payment efficiency: + +1. **Key Path Spending**: + * Used for standard transfers with no conditions + * Minimizes transaction size and fees + +2. **Script Path Spending**: + * Used for conditional transfers (time locks, multi-sig, etc.) + * Reveals only the relevant script path when executing + +3. **Commitment Structure**: + * Main output key commits to all possible spending paths + * Each condition is a separate script leaf in the Taproot tree + +#### On-Chain Token State Tracking + +PBTS tokens maintain their state entirely on-chain: + +1. **Token Properties**: + * All token properties are verifiable through transaction outputs + * Token metadata is committed via hashes in the script structure + +2. **Ownership Tracking**: + * Token ownership is represented by control of the corresponding UTXOs + * Standard Bitcoin wallet functionality can be used to track and manage tokens + +### Security Considerations + +PBTS mitigates various attack vectors through: + +1. **Double Spending Prevention**: + * Each token is tied to a specific UTXO + * Standard Bitcoin consensus rules prevent double-spending + +2. **Replay Attack Protection**: + * Uses unique script conditions for each transfer + * Includes sequence numbers where appropriate + +3. **Fee Optimization**: + * Taproot implementation minimizes transaction sizes + +4. **Predictable Execution**: + * No dynamic loops or unpredictable execution paths + * All contract conditions are pre-defined at creation time + +5. **Time-Based Security**: + * Uses CHECKLOCKTIMEVERIFY to enforce time constraints + * Ensures time-locked funds cannot be spent prematurely + +## Reference Implementation + +A reference implementation is available at: https://github.com/gobishanthan/pbts + +### Prerequisites + +* Bitcoin Core v28.1.0+ with RPC enabled +* Go 1.16 or newer +* A Bitcoin testnet or mainnet wallet with funds + +### Basic Usage + +```bash +# Issue a new token +./pbts issue "Programmable Bitcoin Token" "PBTS" 8 1000000000 + +# List all tokens +./pbts list + +# Create a time-locked vesting contract +./pbts vest + +# Create a milestone-based escrow +./pbts milestone \ + \ + +``` + +## Examples + +### Time-Locked Vesting Contract + +A successful time-locked vesting contract implemented on Bitcoin testnet: + +```bash +./pbts vest 6ad138104a19ad3711a3ae6ec251f0c2 0234f63fb0b8acefb738a83f276ad6e5d18ec71613965c3f639f4158c3b07db1f4 03a7bd1d77432d2267813c908dca7ec7382a41a21a5da9e12d3726e63aae58bde3 10 2025-03-03 +``` + +Generated Output: +``` +🔄 Creating auto-vesting transfer of 10.000000 tokens (ID: 6ad138104a19ad3711a3ae6ec251f0c2) to 03a7bd1d77432d2267813c908dca7ec7382a41a21a5da9e12d3726e63aae58bde3 (unlocks at: 2025-03-03T00:00:00Z)... +Adjusting unlock time to ensure it's in the future: 2025-03-03T23:19:02-05:00 +Created Taproot address: tb1pkcvzu54pey9sjrj5qeu7xnvppe5k3w34spv7yhtfxxg56uyscsuq4uah44 +🏦 Auto-Vest Address: tb1pkcvzu54pey9sjrj5qeu7xnvppe5k3w34spv7yhtfxxg56uyscsuq4uah44 (unlocks at: 2025-03-03T23:19:02-05:00) +✅ Auto-vest transfer transaction broadcasted! TXID: 8c64767e003ed0b5786be07dac35b48eb32e53095af7802d5179808c36e7869d +``` + +This transaction (TXID: 8c64767e003ed0b5786be07dac35b48eb32e53095af7802d5179808c36e7869d) demonstrates a successful time-locked contract on Bitcoin testnet using Taproot functionality. + +## Backward Compatibility + +PBTS is fully backward compatible with the existing Bitcoin protocol. It: + +1. Uses standard Bitcoin transactions +2. Leverages existing opcode functionality +3. Does not require any consensus changes +4. Can coexist with other token standards + +## Test Vectors + +[To be added in future update] + +## References + +- **Bitcoin Improvement Proposals (BIPs):** + - [BIP-341: Taproot](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki) + - [BIP-342: Validation of Taproot Scripts](https://github.com/bitcoin/bips/blob/master/bip-0342.mediawiki) + - [BIP-340: Schnorr Signatures](https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki) +- **Technical Documentation:** + - [Bitcoin Script Reference](https://en.bitcoin.it/wiki/Script) + - [UTXO Model Specification](https://developer.bitcoin.org/devguide/transactions.html) +- **Related Research:** + - [RGB Protocol](https://rgb.tech/) + - [Ordinals Specification](https://docs.ordinals.com/) + - [Runes Documentation](https://runes.com/docs/) + From 6eb2eb7615392dc1bcedf2de10c4d585bb468416 Mon Sep 17 00:00:00 2001 From: unknown Date: Sat, 8 Mar 2025 17:45:28 -0500 Subject: [PATCH 2/3] removed implementation link until further notice --- bip-pbst.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/bip-pbst.md b/bip-pbst.md index 960438f30c..d26b6e32ff 100644 --- a/bip-pbst.md +++ b/bip-pbst.md @@ -230,9 +230,6 @@ PBTS mitigates various attack vectors through: * Uses CHECKLOCKTIMEVERIFY to enforce time constraints * Ensures time-locked funds cannot be spent prematurely -## Reference Implementation - -A reference implementation is available at: https://github.com/gobishanthan/pbts ### Prerequisites From 8e032140fcda56c85349bee8c63fe75bd08102dd Mon Sep 17 00:00:00 2001 From: unknown Date: Mon, 28 Apr 2025 01:15:03 -0400 Subject: [PATCH 3/3] new proposal --- bip-pbst.md | 305 ----------------------- bip-tbs-p.md | 684 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 684 insertions(+), 305 deletions(-) delete mode 100644 bip-pbst.md create mode 100644 bip-tbs-p.md diff --git a/bip-pbst.md b/bip-pbst.md deleted file mode 100644 index d26b6e32ff..0000000000 --- a/bip-pbst.md +++ /dev/null @@ -1,305 +0,0 @@ -# BIP-XXXX: Programmable Bitcoin Token Standard (PBTS) - -``` -BIP: XXXX -Layer: Applications -Title: Programmable Bitcoin Token Standard (PBTS) -Author: Gobi Shanthan , Lee Raj. -Comments-Summary: No comments yet. -Comments-URI: https://github.com/bitcoin/bips/wiki/Comments:BIP-XXXX -Status: Draft -Type: Standards Track -Created: 2025-02-11 -License: BSD-2-Clause -Discussions-To: bitcoin-dev@lists.linuxfoundation.org -Post-History: 2025-02-11 -Requires: 340, 341, 342 -``` - -## Abstract - -The **Programmable Bitcoin Token Standard (PBTS)** introduces a method to create, transfer, and validate native Bitcoin-based tokens using **Bitcoin Script** and **Taproot**. PBTS enhances Bitcoin's Layer 1 functionality by enabling **tokenized assets** with programmable conditions without compromising security, decentralization, or predictability. Unlike Ethereum or Solana, PBTS **does not introduce Turing-complete smart contracts** but leverages **structured pre-commitments** and **Taproot optimizations** to enable secure, efficient programmable tokens. - -PBTS is a **non-consensus-breaking, backward-compatible** standard that ensures tokens remain verifiable and transferable without requiring modifications to Bitcoin's core protocol. - -## Copyright - -This BIP is licensed under the BSD 2-clause license. - -## Motivation - -Bitcoin adheres to the principles of **minimalism and security**, which have made it the most robust and decentralized blockchain. PBTS aligns with this philosophy by introducing **programmability without complexity**, ensuring that Bitcoin's core remains unchanged while extending its utility in a predictable and efficient way. - -Bitcoin currently lacks a **native** token standard that enables **flexible** and **fully Layer 1** token issuance with programmable conditions. Existing solutions such as **Ordinals, RGB, and Runes** either rely on **external tracking mechanisms** or **Layer 2 solutions** that introduce centralization risks. PBTS provides a **UTXO-based**, predefined, and non-intrusive method for issuing tokens that remain completely **verifiable on Bitcoin's base layer** with advanced programmable features like time-locked vesting and milestone-based escrow. - -## Key Benefits - -1. **No Additional Layers** - * Execution happens directly in **Bitcoin transactions** - * Complete validation on **Layer 1** - * No external dependencies for validation - -2. **Predefined & Deterministic Execution** - * No infinite loops or dynamic state modifications - * Predictable execution paths - * Fixed state transitions - -3. **Minimal Impact** - * Utilizes existing **Taproot** and **Script** functionality - * No consensus changes required - * Standard transaction format - -4. **Scalability & Efficiency** - * **Merkle proof-based validation** - * Minimal transaction sizes through Taproot optimization - * Compatible with future Bitcoin scaling solutions - -5. **Security Model** - * No external validators required - * Fully **self-custodial** - * Bitcoin-native security - -6. **Programmable Conditions** - * Time-locked transfers (vesting) - * Milestone-based escrow with multiple release stages - * Multi-signature requirements - * Prepared for oracle integration - -## Comparison with Existing Bitcoin Token Standards - -| Feature | Ordinals | Runes | PBTS | -|----------------------------|--------------------------|-----------------|------------------------------| -| UTXO-Based | ❌ No (Inscriptions) | ✅ Yes | ✅ Yes | -| Requires External Indexer? | ✅ Yes | ✅ Yes | ❌ No | -| Efficient for Tokens? | ❌ No | ✅ Somewhat | ✅ Fully Optimized | -| Scalability Impact | ❌ High Blockchain Bloat | ⚠️ Medium | ✅ Minimal (Uses Taproot) | -| Bitcoin Script-Based? | ❌ No | ✅ Yes | ✅ Yes (Taproot-Optimized) | -| Consensus Changes Required?| ❌ No | ❌ No | ❌ No | -| Transaction Cost | ❌ Expensive | ⚠️ Medium | ✅ Efficient | -| Programmable Conditions | ❌ No | ⚠️ Limited | ✅ Yes | -| Fully On-Chain Validation | ❌ No | ❌ No | ✅ Yes | - -## Specification - -### Overview - -PBTS tokens are created, transferred, and validated directly on Bitcoin's Layer 1 using Taproot scripts to enable complex programmable conditions without requiring any modifications to the Bitcoin protocol. - -### Token Creation - -A **PBTS token** is created by locking a **UTXO** with a **Taproot script** that commits to a token issuance structure. The token metadata is encoded in the transaction output using a standardized format: - -1. **Token Issuance Format**: - * The output script is a Taproot output that contains: - * Token ID: A 32-byte identifier (Hash of Issuer's Public Key + Script Hash) - * Total Supply: Fixed integer representing the maximum possible supply - * Decimals: Integer representing the decimal places (typically 8 to match satoshis) - * Metadata Commitment: Optional hash of off-chain metadata (name, symbol, description) - -2. **Example Issuance Script**: -``` - OP_DROP - OP_CHECKSIG -``` - -### Token Contracts - -PBTS supports several programmable contract types that define how tokens can be transferred and under what conditions they can be spent: - -#### 1. Auto-Vest (Time-Locked) Contracts - -Time-locked transfers where tokens become available to the recipient only after a specific date, using Bitcoin's CHECKLOCKTIMEVERIFY opcode. - -**Script Pattern**: -``` -IF - OP_CHECKLOCKTIMEVERIFY OP_DROP - OP_CHECKSIG -ELSE - OP_CHECKSIG -ENDIF -``` - -#### 2. Milestone-Based Escrow - -Structured transfers with multiple release stages, each requiring specific conditions like time thresholds and multi-signature approvals. - -**Script Pattern**: -``` -IF - # Milestone 1 - OP_CHECKLOCKTIMEVERIFY OP_DROP - OP_CHECKMULTISIG -ELSEIF - # Milestone 2 - OP_CHECKLOCKTIMEVERIFY OP_DROP - OP_CHECKMULTISIG -ELSEIF - # Expiry condition (return to sender) - OP_CHECKLOCKTIMEVERIFY OP_DROP - OP_CHECKSIG -ENDIF -``` - -#### 3. Oracle-Ready Contracts - -Contracts designed to work with external data oracles, containing placeholder structures for future oracle implementation. - -**Script Pattern**: -``` -IF - # Oracle verification - OP_CHECKSIGVERIFY - OP_SHA256 OP_EQUALVERIFY - OP_CHECKSIG -ELSEIF - # Expiry condition (return to sender) - OP_CHECKLOCKTIMEVERIFY OP_DROP - OP_CHECKSIG -ENDIF -``` - -### Token Transfer - -PBTS token transfers involve creating transactions that spend from token-containing UTXOs and create new UTXOs with the appropriate scripts to maintain token properties and conditions. - -1. **Standard Transfer**: - * Spends from a token UTXO - * Creates new outputs with token metadata preserved - * May split tokens across multiple outputs (for partial transfers) - -2. **Conditional Transfer**: - * Creates outputs with Taproot scripts encoding the conditional logic - * Enables time-locked, multi-signature, or other programmable conditions - -3. **Transaction Validation**: - * Follows standard Bitcoin transaction validation rules - * Leverages Bitcoin's native UTXO model for tracking ownership - * Enables verification without external indexers or oracles - -### Implementation Details - -#### Taproot Integration - -PBTS leverages Taproot's script path spending to enable complex script execution while maintaining payment efficiency: - -1. **Key Path Spending**: - * Used for standard transfers with no conditions - * Minimizes transaction size and fees - -2. **Script Path Spending**: - * Used for conditional transfers (time locks, multi-sig, etc.) - * Reveals only the relevant script path when executing - -3. **Commitment Structure**: - * Main output key commits to all possible spending paths - * Each condition is a separate script leaf in the Taproot tree - -#### On-Chain Token State Tracking - -PBTS tokens maintain their state entirely on-chain: - -1. **Token Properties**: - * All token properties are verifiable through transaction outputs - * Token metadata is committed via hashes in the script structure - -2. **Ownership Tracking**: - * Token ownership is represented by control of the corresponding UTXOs - * Standard Bitcoin wallet functionality can be used to track and manage tokens - -### Security Considerations - -PBTS mitigates various attack vectors through: - -1. **Double Spending Prevention**: - * Each token is tied to a specific UTXO - * Standard Bitcoin consensus rules prevent double-spending - -2. **Replay Attack Protection**: - * Uses unique script conditions for each transfer - * Includes sequence numbers where appropriate - -3. **Fee Optimization**: - * Taproot implementation minimizes transaction sizes - -4. **Predictable Execution**: - * No dynamic loops or unpredictable execution paths - * All contract conditions are pre-defined at creation time - -5. **Time-Based Security**: - * Uses CHECKLOCKTIMEVERIFY to enforce time constraints - * Ensures time-locked funds cannot be spent prematurely - - -### Prerequisites - -* Bitcoin Core v28.1.0+ with RPC enabled -* Go 1.16 or newer -* A Bitcoin testnet or mainnet wallet with funds - -### Basic Usage - -```bash -# Issue a new token -./pbts issue "Programmable Bitcoin Token" "PBTS" 8 1000000000 - -# List all tokens -./pbts list - -# Create a time-locked vesting contract -./pbts vest - -# Create a milestone-based escrow -./pbts milestone \ - \ - -``` - -## Examples - -### Time-Locked Vesting Contract - -A successful time-locked vesting contract implemented on Bitcoin testnet: - -```bash -./pbts vest 6ad138104a19ad3711a3ae6ec251f0c2 0234f63fb0b8acefb738a83f276ad6e5d18ec71613965c3f639f4158c3b07db1f4 03a7bd1d77432d2267813c908dca7ec7382a41a21a5da9e12d3726e63aae58bde3 10 2025-03-03 -``` - -Generated Output: -``` -🔄 Creating auto-vesting transfer of 10.000000 tokens (ID: 6ad138104a19ad3711a3ae6ec251f0c2) to 03a7bd1d77432d2267813c908dca7ec7382a41a21a5da9e12d3726e63aae58bde3 (unlocks at: 2025-03-03T00:00:00Z)... -Adjusting unlock time to ensure it's in the future: 2025-03-03T23:19:02-05:00 -Created Taproot address: tb1pkcvzu54pey9sjrj5qeu7xnvppe5k3w34spv7yhtfxxg56uyscsuq4uah44 -🏦 Auto-Vest Address: tb1pkcvzu54pey9sjrj5qeu7xnvppe5k3w34spv7yhtfxxg56uyscsuq4uah44 (unlocks at: 2025-03-03T23:19:02-05:00) -✅ Auto-vest transfer transaction broadcasted! TXID: 8c64767e003ed0b5786be07dac35b48eb32e53095af7802d5179808c36e7869d -``` - -This transaction (TXID: 8c64767e003ed0b5786be07dac35b48eb32e53095af7802d5179808c36e7869d) demonstrates a successful time-locked contract on Bitcoin testnet using Taproot functionality. - -## Backward Compatibility - -PBTS is fully backward compatible with the existing Bitcoin protocol. It: - -1. Uses standard Bitcoin transactions -2. Leverages existing opcode functionality -3. Does not require any consensus changes -4. Can coexist with other token standards - -## Test Vectors - -[To be added in future update] - -## References - -- **Bitcoin Improvement Proposals (BIPs):** - - [BIP-341: Taproot](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki) - - [BIP-342: Validation of Taproot Scripts](https://github.com/bitcoin/bips/blob/master/bip-0342.mediawiki) - - [BIP-340: Schnorr Signatures](https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki) -- **Technical Documentation:** - - [Bitcoin Script Reference](https://en.bitcoin.it/wiki/Script) - - [UTXO Model Specification](https://developer.bitcoin.org/devguide/transactions.html) -- **Related Research:** - - [RGB Protocol](https://rgb.tech/) - - [Ordinals Specification](https://docs.ordinals.com/) - - [Runes Documentation](https://runes.com/docs/) - diff --git a/bip-tbs-p.md b/bip-tbs-p.md new file mode 100644 index 0000000000..5c42f6ebea --- /dev/null +++ b/bip-tbs-p.md @@ -0,0 +1,684 @@ +BIP: XXX + +Layer: Applications + +Title: Wallet Recognition Standard for Taproot Token (TSB-P) + +Author: Gobi Shanthan \, Lee Raj. \ + +Comments-Summary: A standard for wallet interoperability in token pattern recognition + +Status: Draft + +Type: Informational + +Created: 2025-04-20 + +License: BSD-2-Clause + +Discussions-To: [[bitcoin-dev@lists.linuxfoundation.org](mailto:bitcoin-dev@lists.linuxfoundation.org)] + +# Abstract + +This document proposes a wallet interoperability standard for recognizing and interpreting token patterns in Taproot transactions, similar to how BIP39 standardized seed phrases without modifying consensus rules. The Token Standard on Bitcoin - Programmable (TSB-P) defines a structured format within Taproot leaf scripts that allows wallets to consistently identify, display, and interpret token information embedded in standard Bitcoin transactions. + +By creating a "BIP39 for token recognition," this specification aims to improve user experience, reduce implementation fragmentation, and standardize representation of token-related activities on Bitcoin without requiring consensus changes or modifying Bitcoin's primary purpose as a currency. + +# Motivation + +## The Need for Wallet Interoperability + +Bitcoin wallets currently lack a standardized approach to recognizing and displaying token-related transactions, resulting in several challenges: + +1. **Inconsistent User Experience**: The same token-representing UTXO may appear differently across wallets or not be recognized at all +2. **Implementation Fragmentation**: Wallet developers must create custom token detection logic +3. **Excessive Blockchain Usage**: Some token approaches create unnecessary data bloat +4. **User Confusion**: Difficult to distinguish between token types and behaviors + +## Relationship to Other Standards + +This proposal draws inspiration from several successful Bitcoin standards: + +- **BIP39**: Standardized seed phrases for wallets without changing consensus rules +- **BIP21**: Standardized payment request URIs for consistent wallet handling +- **BIP329**: Standardized wallet labels for better interoperability + +Each of these standards improved Bitcoin's usability through wallet interoperability without requiring protocol modifications. TSB-P follows this pattern by standardizing how wallets recognize token-related patterns. + +## Benefits of Standardization + +A standardized wallet recognition pattern for token-representing UTXOs would: + +1. **Improve User Experience**: Tokens are displayed consistently across compatible wallets +2. **Simplify Wallet Development**: Standard patterns are easier to implement +3. **Reduce Blockchain Impact**: Efficient representation using Taproot's advantages +4. **Enable Advanced Features**: Support for time-locks, multisig, and other Bitcoin Script features + +Importantly, this standard does not seek to modify Bitcoin's consensus rules or create new token validation systems. It simply standardizes how wallets interpret specific Taproot script patterns, similar to how BIP39 standardized seed phrase interpretation. + +# Specification + +## Wallet Recognition Pattern Structure + +This BIP defines a standardized Taproot leaf script pattern that compatible wallets should recognize and interpret: + +``` +OP_TRUE +OP_IF + <"TSB"> # 3-byte marker + # 16 bytes identifier + # 8 bytes (uint64 big-endian) + # 1 byte token type + OP_DROP # Drop markers from stack + OP_DROP + OP_DROP + OP_DROP + # Variable length user data + # 8 bytes (uint64 big-endian) + OP_DROP # Drop optional fields + OP_DROP + # Spending conditions +OP_ENDIF +``` + +### Example + +Here's a concrete example of a token with specific values: + +``` +OP_TRUE # Start conditional block +OP_IF + "TSB" # 3-byte marker + 0x6d79546f6b656e0000000000000000 # tokenID ("myToken" padded) + 0x00000000000f4240 # amount (1000000 tokens) + 0x02 # typeCode (vesting token) + OP_DROP # Remove fields from stack + OP_DROP + OP_DROP + OP_DROP + 0x54686973206973206120746573742074 # metadata ("This is a test token") + 0x000000006446e1fd # timestamp (2025-04-28 12:34:56) + OP_DROP # Remove optional fields + OP_DROP + OP_TRUE # Basic spending condition +OP_ENDIF # End conditional block +``` + +## Field Definitions + +| **Field** | **Format** | **Description** | +|---------------|---------------------|----------------------------------------| +| "TSB" | 3-byte ASCII string | Token marker for wallet scanning | +| tokenID | 16 bytes | Unique token identifier (padded) | +| amount | 8 bytes (uint64 BE) | Token quantity in smallest units | +| typeCode | 1 byte | Indicates token behavior type | +| metadata | Variable bytes | User-defined data | +| timestamp | 8 bytes (uint64 BE) | UNIX timestamp of token creation | +| OP_DROP x6 | 6 bytes | Remove marker fields from stack | +| logic section | Script | Bitcoin Script spending conditions | + +## Implementation Considerations + +This specification is intended for wallet-level implementation, with these key points: + +1. **No Consensus Changes**: This pattern works with existing Bitcoin Script interpreter rules +2. **Wallet Recognition Only**: The pattern serves as a marker for wallet software, not a consensus rule +3. **Standard Spending**: UTXOs with this pattern are spent using normal Bitcoin transaction validation +4. **Discoverability**: The "TSB" marker allows wallets to efficiently scan for relevant scripts +5. **Privacy**: Token data remains hidden until spent via Taproot script-path reveal + +## Transport Mechanism + +Each TSB-P pattern exists within a standard Bitcoin transaction that transfers actual satoshis to a Taproot address, ensuring: + +1. **Economic Validity**: Every UTXO must hold BTC to exist (typically 546 sats minimum) +2. **Standard Propagation**: Transactions propagate normally in the Bitcoin network +3. **Taproot Privacy**: Patterns are revealed only when spending via script path + +## Wallet Scanning Process + +Compatible wallets should implement this scanning process: + +1. Examine spent Taproot UTXOs for script paths in the witness data +2. Detect the "TSB" marker in the script +3. Parse tokenID, amount, typeCode, metadata, and timestamp fields +4. Present appropriate information to users based on the typeCode + +## Standard Token Types + +The typeCode field indicates how wallets should interpret the token pattern: + +| **Code** | **Name** | **Description** | +|----------|-----------------------------|-----------------------------------------| +| 0x00 | Fungible Token (FT) | Standard fungible asset | +| 0x01 | Non-Fungible Token (NFT) | Unique asset | +| 0x02 | Proof-of-Existence | Timestamped document or hash proof | +| 0x03 | Smart Contract Trigger | Triggers programmable conditions | +| 0x04 | Oracle-Verified Token | Requires external validation | +| 0x05 | Compliance-Bound Token | Enforces KYC/AML rules | +| 0x06 | Vesting Token | Subject to time-based vesting | +| 0x07 | Multi-Sig Restricted | Requires multiple signatures | +| 0x08 | DAO Governance Token | Used for voting or governance | +| 0x09-0xFE | Reserved | Reserved for future standard types | +| 0xFF | Custom | Application-specific logic | + +Wallets should present appropriate UI and functionality based on the typeCode. + +# Rationale + +## Design Principles + +This wallet recognition standard was designed following these principles: + +1. **Non-Invasive**: Uses existing Bitcoin functionality without protocol modifications +2. **Wallet Focused**: Improves interoperability without requesting consensus changes +3. **Efficient**: Minimizes additional data required for pattern recognition +4. **Clear Separation**: Distinguishes between consensus enforcement and wallet interpretation + +## Design Decisions + +### "TSB" Marker Selection + +The 3-byte marker "TSB" (0x545342) was chosen because: + +- It's short but distinctive enough for unambiguous detection +- It's human-readable for debugging purposes +- It has minimal collision probability with other script patterns + +### Fixed Field Sizes + +TokenID (16 bytes) and amount (8 bytes) use fixed sizes for: + +- Reliable parsing across implementations +- Deterministic script sizes for fee estimation +- Efficient storage in Taproot leaves + +### Type Code System + +The single-byte typeCode field enables: + +- Multiple token behavior patterns within the same standard +- Wallet-appropriate display of different token types +- Future extensibility without modifying the pattern format + +### Timestamp Inclusion + +The 8-byte timestamp field is a critical component that: + +- Prevents token ID collisions by ensuring each issuance has a unique temporal identifier +- Mitigates key reuse attacks where an issuer might attempt to create duplicate tokens +- Creates unique token identities even when the same key and script are used +- Provides chronological metadata useful for token provenance and history + +By combining (public key + script + timestamp) in the token's structure, each token issuance becomes cryptographically unique, even if the same issuer attempts to create multiple tokens with identical parameters. + +### Taproot Integration + +Taproot was chosen as the foundation because: + +- It provides script privacy by default until revealed +- It maintains compatibility with standard Bitcoin validation +- It supports complex spending conditions efficiently + +### Standard Satoshi Outputs + +TSB-P uses standard satoshi outputs because: + +- It maintains normal Bitcoin transaction validity rules +- It prevents dust outputs by ensuring economic value +- It avoids the blockchain impact of OP_RETURN-based approaches + +## OP_TRUE vs Other Spending Conditions + +The reference implementation uses OP_TRUE as the default spending condition for simplicity, but production implementations should use more restrictive conditions. The OP_TRUE is a placeholder that can be replaced with: + +- Public key signature checks +- Timelocks +- Hash preimage reveals +- Multi-signature schemes +- Any other valid Bitcoin Script condition + +# Compatibility + +## Bitcoin Protocol Compatibility + +This wallet recognition standard is fully compatible with the existing Bitcoin protocol: + +- **Standard Transactions**: Uses standard Pay-to-Taproot (P2TR) outputs +- **No Consensus Changes**: Relies only on existing Bitcoin Script opcodes +- **Normal Validation**: All transactions follow standard Bitcoin validation rules +- **PSBT Compatibility**: Works with Partially Signed Bitcoin Transaction workflows + +## Wallet Implementation Compatibility + +The TSB-P pattern has varying levels of compatibility with existing software: + +- **Non-Compatible Wallets**: Will treat TSB-P patterns as regular Bitcoin transactions +- **TSB-P Aware Wallets**: Can recognize and display token information to users +- **Existing Transactions**: Does not affect interpretation of existing transactions +- **Bitcoin Core**: No modifications to Bitcoin Core are required + +When a user with a non-compatible wallet receives a TSB-P token, they will see: +- A normal Bitcoin transaction in their wallet +- Standard transaction history +- No indication of embedded token data + +This ensures that users of non-compatible wallets can still receive and send Bitcoin associated with tokens, though they won't see the token-specific information. + +## Integration with Existing Standards + +TSB-P complements existing Bitcoin standards: + +- **BIP341 (Taproot)**: Leverages Taproot's script path capabilities +- **BIP174 (PSBT)**: Compatible with PSBT workflows for transaction signing +- **BIP329 (Wallet Labels)**: Can be used alongside wallet labels for context + +# Implementation + +## Reference Implementations + +Complete reference implementations are available in public GitHub repositories: + +### TSB-P Token Creator and Validator + +A full implementation of the TSB-P standard with token creation, spending, and validation capabilities is available at: +[github.com/GobiShanthan/TSB-P](https://github.com/GobiShanthan/TSB-P) + +This Go-based implementation includes: + +- **Token Creation**: Generate Taproot outputs with embedded token data +- **Script Compilation**: Create valid Bitcoin Script following the TSB-P format +- **Transaction Construction**: Build transactions that reveal token data +- **Pattern Extraction**: Parse and validate token data from on-chain transactions + +The implementation provides a complete CLI tool for creating, funding, spending, and revealing TSB-P tokens on Bitcoin regtest networks. + +### TSB-P Token Explorer + +A web-based token explorer for discovering and displaying TSB-P tokens is available at: +[github.com/GobiShanthan/bitcoin-token-scanner](https://github.com/GobiShanthan/bitcoin-token-scanner) + +This JavaScript implementation includes: + +- **Token Scanner**: Find tokens in blockchain transactions +- **Pattern Parser**: Extract and validate token data from witness scripts +- **Caching Layer**: Efficiently store and retrieve token data +- **Web Interface**: Display token information to users + +The explorer can scan Bitcoin regtest networks for TSB-P tokens and present them in a user-friendly interface, demonstrating how wallet providers could implement similar functionality. + +## JavaScript Token Parser + +The following JavaScript code illustrates a real-world implementation of a TSB-P token parser: + +```javascript +class TokenParser { + static parse(witnessHex) { + try { + const buffer = Buffer.from(witnessHex, 'hex'); + let offset = 0; + + // 1. Expect OP_TRUE (0x51) + if (buffer[offset++] !== 0x51) { + return null; + } + + // 2. Expect OP_IF (0x63) + if (buffer[offset++] !== 0x63) { + return null; + } + + // 3. Check marker push (0x03 and "TSB") + if (buffer[offset++] !== 0x03) { + return null; + } + const marker = buffer.slice(offset, offset + 3).toString(); + if (marker !== 'TSB') { + return null; + } + offset += 3; + + // 4. TokenID + if (buffer[offset++] !== 0x10) { // length 16 + return null; + } + const tokenIdRaw = buffer.slice(offset, offset + 16); + const tokenId = tokenIdRaw.toString().replace(/\0+$/, ''); + offset += 16; + + // 5. Amount + if (buffer[offset++] !== 0x08) { + return null; + } + const amountBuf = buffer.slice(offset, offset + 8); + const amount = amountBuf.readBigUInt64BE(0); + offset += 8; + + // 6. TypeCode + const typeCodeBuf = buffer[offset++]; + let typeCode = typeCodeBuf; + // Convert OP_N values to integers if needed + if (typeCode >= 0x51 && typeCode <= 0x60) { + typeCode = typeCode - 0x50; + } + + // 7. Expect 4x OP_DROP (0x75) + for (let i = 0; i < 4; i++) { + if (buffer[offset++] !== 0x75) { + return null; + } + } + + // 8. Metadata + const metadataLength = buffer[offset++]; + const metadataRaw = buffer.slice(offset, offset + metadataLength); + const metadata = metadataRaw.toString(); + offset += metadataLength; + + // 9. Timestamp + if (buffer[offset++] !== 0x08) { + return null; + } + const timestampBuf = buffer.slice(offset, offset + 8); + const timestamp = timestampBuf.readBigUInt64BE(0); + offset += 8; + + // 10. Expect 2x OP_DROP + if (buffer[offset++] !== 0x75 || buffer[offset++] !== 0x75) { + return null; + } + + // 11. Expect OP_TRUE (0x51) + if (buffer[offset++] !== 0x51) { + return null; + } + + return { + tokenId, + amount: Number(amount), + typeCode, + metadata, + timestamp: Number(timestamp), + isValid: true + }; + } catch (err) { + return null; + } + } +} +``` + +## Wallet Scanning Function + +For comprehensive token scanning in a wallet or explorer application, both unspent P2TR outputs and spent transactions need to be checked: + +```javascript +function scanForTSBPatterns(walletUTXOs, blockchainTxs) { + const tsbPatterns = []; + + // Part 1: Scan UTXOs for potential TSB-P outputs + for (const utxo of walletUTXOs) { + if (utxo.scriptPubKey && utxo.scriptPubKey.type === 'witness_v1_taproot') { + // Mark potential token UTXOs for the wallet to track + tsbPatterns.push({ + type: 'potential', + utxo, + status: 'unspent' + }); + } + } + + // Part 2: Scan witness data from spent transactions + for (const tx of blockchainTxs) { + for (const input of tx.vin) { + if (input.txinwitness && input.txinwitness.length >= 2) { + const witnessScript = input.txinwitness[0]; + + // Use TokenParser to extract token data + const tokenData = TokenParser.parse(witnessScript); + + if (tokenData) { + tsbPatterns.push({ + type: 'confirmed', + txid: tx.txid, + tokenId: tokenData.tokenId, + amount: tokenData.amount, + typeCode: tokenData.typeCode, + metadata: tokenData.metadata, + timestamp: tokenData.timestamp, + status: 'spent' + }); + } + } + } + } + + return tsbPatterns; +} +``` + +## Web Explorer Implementation + +The TSB-P token explorer uses a caching mechanism to efficiently retrieve token data: + +```javascript +class Token { + // Cache management for efficient token lookups + static async findAll(maxBlocks = config.scan.maxBlocks, forceRefresh = false) { + const now = Date.now(); + + // Return cached tokens if available and not expired + if (!forceRefresh && tokenCache.length > 0 && (now - lastScanTime) < config.cache.ttl) { + return tokenCache; + } + + // Scan for new tokens + const tokens = await Token.scanForTokens(maxBlocks); + + // Update cache + tokenCache = tokens; + lastScanTime = now; + + return tokens; + } + + // Look up token by transaction ID + static async findByTxid(txid) { + // Try to find in cache first + const cachedToken = tokenCache.find(token => token.txid === txid); + if (cachedToken) { + return cachedToken; + } + + // If not in cache, check the transaction + const tx = await BitcoinService.getRawTransaction(txid, true); + if (!tx) { + return null; + } + + // Check inputs for witness data + for (const vin of tx.vin) { + if (vin.txinwitness && vin.txinwitness.length >= 2) { + const witnessScript = vin.txinwitness[0]; + const tokenData = TokenParser.parse(witnessScript); + + if (tokenData) { + // Add blockchain metadata + tokenData.txid = txid; + tokenData.blockHash = tx.blockhash; + + // Get block info for more details + if (tx.blockhash) { + const block = await BitcoinService.getBlock(tx.blockhash); + tokenData.blockHeight = block.height; + tokenData.blockTime = block.time; + } + + return new Token(tokenData); + } + } + } + + return null; + } +} +``` + +## Test Vectors + +The following test vectors provide an example for implementation validation: + +### Standard Token Pattern (Type 0x00) + +Script (hex): +``` +5163035453421056657374696e670000000000000000000800000002540be40000537575757516457863 +6c75736976652076657374696e6720746573740800000000680f006a75755168 +``` + +Breakdown: +``` +51 # OP_TRUE +63 # OP_IF +03 # Push 3 bytes +545342 # "TSB" +10 # Push 16 bytes +56657374... # tokenID ("Vesting" padded with zeros) +08 # Push 8 bytes +0000000... # amount (10000000000) +01 # Push 1 byte +00 # typeCode (fungible token) +75 # OP_DROP +75 # OP_DROP +75 # OP_DROP +75 # OP_DROP +16 # Push metadata +457863... # "Exclusive vesting test" +08 # Push 8 bytes +0000000... # timestamp +75 # OP_DROP +75 # OP_DROP +51 # OP_TRUE (programmable logic) +68 # OP_ENDIF +``` + +## Implementation Guidelines + +When implementing TSB-P pattern recognition, wallet developers should consider: + +### Performance Considerations + +1. **Scanning Overhead**: + - Optimize by caching results and incremental scanning + - Consider background scanning to maintain UI responsiveness + +2. **Script Size Impact**: + - TSB-P patterns add approximately 100-150 bytes to transaction witness data + - Results in modest fee increases for token transactions + +3. **Database Indexing**: + - Maintain token indexes for quick lookups (tokenID, typeCode) + +### Error Handling + +1. **Validation**: Verify the "TSB" marker exactly before processing +2. **Field Sizes**: Ensure fields have correct lengths +3. **TypeCode**: Handle unknown typeCodes gracefully +4. **Parsing Errors**: Display fallback information if script parsing fails +5. **User Messaging**: Show "Unknown Token Type" for unrecognized typeCodes + +### Visual Representation + +Wallets should follow these UI guidelines for TSB-P tokens: + +1. **Token List View**: Display tokenID, amount, and type icon +2. **Token Detail View**: Show full token information, metadata, and timestamp +3. **Type-Specific UI**: Customize display based on token type (e.g., vesting progress) +4. **Transaction History**: Distinguish token transactions from regular Bitcoin transactions + +# Security Considerations + +## Wallet Recognition Model + +Users and developers should understand this standard's security model: + +- **Wallet-Level Recognition**: TSB-P is a wallet recognition standard, not a consensus rule +- **Transaction Security**: Security of the underlying transaction follows standard Bitcoin rules +- **Scriptable Conditions**: Any spending rules are enforced by Bitcoin consensus +- **Pattern Recognition Only**: The TSB-P pattern itself is not enforced by Bitcoin nodes + +## Pattern Security Properties + +The TSB-P pattern has these security properties: + +- **Unambiguous Detection**: Fixed field sizes and standardized format ensure reliable detection +- **Private by Default**: Tokens are initially indistinguishable from regular P2TR outputs +- **Revealed Only When Spent**: The pattern becomes visible only when spent via script path +- **Resistant to Tampering**: Changes to token data would invalidate the Taproot commitment + +## Limitations for User Awareness + +End-users should understand these limitations: + +- **Wallet Compatibility**: Tokens are visible only in compatible wallets +- **No Supply Enforcement**: Bitcoin consensus does not enforce token supply limits +- **No Double-Spend Protection**: For token balances beyond what Bitcoin natively provides +- **Reorg Risks**: Subject to the same reorganization risks as any Bitcoin transaction + +## Comparison to Other Standards + +TSB-P's security model is similar to other wallet standards: + +| **Standard** | **Security Model Comparison** | +|--------------|-------------------------------| +| BIP39 | Wallet interpretation of seed phrases | +| BIP21 | Wallet parsing of payment URIs | +| BIP329 | Wallet handling of metadata | +| TSB-P | Wallet recognition of token patterns | + +None of these standards modify Bitcoin's consensus rules—they standardize wallet behavior and interpretation. + +# Future Extensions + +## Additional Type Codes + +The typeCode field (1 byte) allows for future token behavior patterns: + +- **Dynamic Contracts** (Proposed Type 0x20): More complex programmable conditions +- **Federated Tokens** (Proposed Type 0x21): Multi-party governed tokens +- **Payment Channels** (Proposed Type 0x22): Token-aware Lightning Network integrations +- **Threshold Signatures** (Proposed Type 0x23): Advanced cryptographic access controls + +## Optional Registry Integration + +While not part of this specification, a token registry could complement TSB-P: + +- **Metadata Association**: Human-readable names, symbols, decimal places +- **Issuer Information**: Optional verification of token creators +- **Asset Discovery**: Easier discovery of compatible tokens +- **Indexing Service**: Efficient lookup of token-related transactions + +## Interoperability + +TSB-P could interoperate with other Bitcoin standards and systems: + +- **Lightning Network**: Potential for Lightning Channel integration +- **Ordinals**: Complementary to ordinal-based assets +- **DLCs (Discreet Log Contracts)**: Enhanced conditional logic +- **Statechains**: Movement of tokens across state transition boundaries + +# Acknowledgements + +This proposal draws inspiration from numerous Bitcoin standards and token approaches. Special thanks to the Bitcoin development community for feedback on earlier token standard proposals, particularly @murchandamus and @jonatack, whose technical review helped shape this wallet-focused approach. + +# References + +- [BIP341: Taproot](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki) +- [BIP342: Tapscript](https://github.com/bitcoin/bips/blob/master/bip-0342.mediawiki) +- [BIP39: Mnemonic code for generating deterministic keys](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) +- [BIP21: URI Scheme](https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki) +- [BIP329: Wallet Labels](https://github.com/bitcoin/bips/blob/master/bip-0329.mediawiki) + +# Copyright + +This document is licensed under the BSD 2-clause license. \ No newline at end of file