From 5337c7be2c848f8001730dcf4a5dcbb59c98ada7 Mon Sep 17 00:00:00 2001 From: ZmnSCPxj Date: Mon, 17 Jun 2019 14:46:28 +0000 Subject: [PATCH] 13-i-can-has-extension.md: I can has extension? --- .aspell.en.pws | 188 ++++++++++++++++--------------- 13-i-can-has-extension.md | 228 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 321 insertions(+), 95 deletions(-) create mode 100644 13-i-can-has-extension.md diff --git a/.aspell.en.pws b/.aspell.en.pws index b1a1ad307..668e0854d 100644 --- a/.aspell.en.pws +++ b/.aspell.en.pws @@ -1,15 +1,23 @@ -personal_ws-1.1 en 264 +personal_ws-1.1 en 329 +reblind secp sig unguessable +wildcard +APIs libsecp TCP DER +cli micropayments nhops retransmitted dev +CLTVs +javascript +Javascript tradeoff +BTC mixHeader uint hopsData @@ -24,20 +32,31 @@ yToX funder's IRATEMONK wpkh +checksum nextHmac basepoint +interoperate streamKey -localpubkey +versa +subdomain +deobfuscate +SQL paymentPath SPV +DOM +DNS +redemptions HopData CSV xFFFFFFFFFF plaintext EQUALVERIFY +SRV +Implementers AEAD secretkey TripleDH +mainnet addr CHECKMULTISIG decryptWithAD @@ -47,73 +66,109 @@ scriptpubkey mukey muKey sharedSecretSize +offerer DUP sharedSecrets +resolvers +TTL xFFFFFFFFFFFF +A +sanitization cryptographic generateSharedSecret instantiations deterministically +URI deduplication FIPS +UTC responder +remote's UTF blockchain +scalarMult +nano nSequence +htlcpubkey decrypt +pico flen incrementing +ecdhResult feerate affine CHECKSEQUENCEVERIFY nonces iff +prepending serializeCompressed +vbytes prepended roasbeef multisig +offerer's +icecream nodepk +ephemeralPrivKey remotesig hopBlindingFactors +remotepubkey ECDH +inline addrlen assocData +tuples ActOne ammag computeBlindingFactor wsh multiScalarMult -onionpacket +ratelimiting OnionPacket +onionpacket ikm +ZmnSCPxj +multi fillerSize txinput +regtest init reconnection milli revocationsig +smartphone +testnet NOTIF generateHeaderPadding -IPv +bitcoins +Bitcoins +bitcoin's +XSS ipv +IPv +aa satoshi delayedsig hopDataSize I'th segwit htlc -htlcs ChaCha len ciphertext endian +bech C'mon NewOnionPacket keypair +swiss +blindingFactor preimage +revocationpubkey MiTM mempool cltv +df localfeatures iteratively PrivateKey @@ -124,10 +179,11 @@ ee eg hopSize retransmit -retransmittal deobfuscating onchain +incentivize BADONION +ek rightShift protocolName hopEphemeralPubKeys @@ -144,14 +200,18 @@ calcMac privkey overpayment hopSharedSecrets +IP TimeLocked timelocked lc btcec localsig responder's +ephemeralPubKey ripemd +Versioning md +localhtlcsig ENDIF blockchains cleartext @@ -165,75 +225,94 @@ pubkey PubKey ok Retransmissions +lollypop numHops +localpubkey failuremsg +paymentkey +delayedpubkey fundee byteslen shortid se rk micropayment +zlib rn testbit unparsable sk RoutingInfo funder +other's Counterintuitively +basepoints decrypts sn +unlinkable generateFiller unrevoked ss that'd +metadata ack +hostnames deobfuscated gflen +Mul satoshis instantiation +permissionless HeaderMAC blindGroupElement +subdomains tx pubkeys CHECKLOCKTIMEVERIFY -CLTV -CLTVs +duplicative generateCipherStream XK +tuple lflen deobfuscates generateKey alice revocationprivkey +bitcoin PKH -remotepubkey HKDF ooo repo +BOLTs num +expiries +timestamp numStreamBytes txout -HTLCs HTLC's +HTLCs +htlcs retransmission decrypted -sessionKey sessionkey +sessionKey routingInfoSize hostname +AAAA rgb ciphertexts wscript +fundee's CHECKSIG pre numMaxHops HMACs +remotehtlcsig hmac BIP hmacSize ratelimit talkin -revocationpubkey msat func unencrypted @@ -242,91 +321,10 @@ priv sha TODO ChaChaPoly -delayedpubkey Diffie IETF +retransmittal xFFFFFFFFFFF FIXME -EphemeralKey -bitcoin -Bitcoin -smartphone -other's -remote's -multi -bitcoin's -IP -aa -df -versa -timestamp -metadata -Bitcoin's -Versioning -checksum -expiries -bech -Bech -nano -pico -mainnet -testnet -icecream -swiss -lollypop -UTC -inline -fundee's -BOLTs -DNS -subdomain -subdomains -wildcard -tuple -tuples -resolvers -hostnames -prepending -A -AAAA -SRV -TTL -URI -cli -paymentkey -htlcpubkey -remotehtlcsig -localhtlcsig -basepoints -Bitcoins -bitcoins -deobfuscate -offerer -offerer's -incentivize -redemptions -vbytes -BTC -XSS -SQL -DOM -Javascript -javascript -Implementers -sanitization -ek -reblind ephemeralKey -ephemeralPrivKey -ephemeralPubKey -ecdhResult -scalarMult -blindingFactor -Mul -unlinkable -regtest -ratelimiting -zlib -ZLIB -APIs -duplicative +EphemeralKey diff --git a/13-i-can-has-extension.md b/13-i-can-has-extension.md new file mode 100644 index 000000000..10b621bd6 --- /dev/null +++ b/13-i-can-has-extension.md @@ -0,0 +1,228 @@ +# BOLT #13: Protocol for Permissionless Feature Development + +A simple feature to allow new features to be developed experimentally +by individual implementations (and forks thereof), +without requiring a centralized location to allocate feature bits or +similar common resources. + +The intent is to allow node software to develop their own extensions +to the protocol, +to be later proposed to the BOLT spec once experience in live use +has ironed out any design problems. + +# Table of Contents + + * [Extension Encoding](#extension-encoding) + * [Message Type Reservation](#message-type-reservation) + * [Informing Extensions](#informing-extensions) + * [The `have_extensions` Message](#the-have_extensions-message) + * [Enabling Extensions](#enabling-extensions) + * [The `use_extension` Message](#the-use_extension-message) + * [Authors](#authors) + +# Extension Encoding + +Experimental features +("extensions" in the terminology of this document) +are identified by an extension code, a 20-byte vector of a +white noise random distribution. + +An extension code SHOULD be selected +by using RIPEMD160 on a vector generated by the concatenation of: + +* A human-readable UTF-8 description of the experimental feature. +* A version number for the feature protocol. +* A 20-byte salt from a white noise random distribution. + +By use of the above, developers of experimental features can +acquire a randomly-selected extension code +without permission from any central authority or group. + +An extension code MAY be selected by simply sampling twenty bytes +from a white noise random distribution. + +The extension code composed of 20 `0x00` bytes is reserved to mean +"no extension". + +# Message Type Reservation + +Message types 49152 (`0xC000`) to 65535 (`0xFFFF`) are reserved +by this BOLT specification for extension messages. +Two message types, `use_extension` (type 49152) and +`have_extensions` (type 49153) are used to inform about extensions +and enable an extension to be used over the peer protocol. + +Message types 49154 (`0xC002`) to 65535 (`0xFFFF`) are to be used +for extension messages. +These message types are _multiplexed_, +meaning that all extensions share the same message type numbers. +Messages for a specific extension are called _extension-specific_ +messages. +The selection of extension applies to one direction +of the communications channel only, +and is controlled solely by the sender in that direction. +The `use_extension` message is used by the sender +to change the "currently enabled extension" of the direction +in which it is sending. +Both directions of the communications channel +have independent senses of the "currently enabled extension". + +When a node receives a message of type 49154 to 65535, +that message will have a meaning and format +according to the "currently enabled extension" of the direction +where it is the receiver. + +For example, if we have two nodes A and B, +A controls the currently enabled extension used in the direction A to B, +while B controls that of the direction B to A. +A and B can be sending messages of different extensions simultaneously. +B will receive messages under the extension specified by A, +and vice versa. + +If the "currently enabled extension" is "no extension", +then message types 49154 to 65535 will result in undefined behavior. + +## Requirements + +Before sending an extension-specific message to the peer, +the sending node MUST ensure that +the "currently enabled extension" of the receiver is the extension +the sending node intends to use. + +A sending node MAY send `use_extension` before every +extension-specific message in order to ensure the above requirement. + +## Rationale + +By multiplexing, we allow a node to support multiple experimental +features in parallel. +Although messages are sent under one extension at a time only, +the peer may switch between extensions at any time. + +The underlying communications channel will reliably transmit messages +in one direction of communications in the same order as it is sent. +Otherwise, the encryption communications protocol would not work +(the nonce `sn` is incremented at each message in sending direction; +same with `rn` for the receiving direction). +However, the two peers execute asynchronously of each other, +and requiring a handshake so that both peers agree to be +communicating in the same extension would add +communications overhead. +Thus, each direction of communication has its own +"currently enabled extension". + +Sending nodes can send `use_extension` before every +extension-specific message so as to simplify implementations. +Implementations can simply always send this before every +extension-specific message so that they do not have to +keep track of the state of the peer. + +Nodes supporting only a single extension can always just recognize +the extension messages regardless of the purported +"currently enabled extension". +This is the reason for why "no extension" allows the +multiplexed message types to result in undefined behavior: +nodes that support only a single extension can simply not +multiplex the message types and recognize them at all times, +for simplicity. + +Both nodes over a connection have their own separate concepts of +"currently enabled extension", rather than having a single +"currently enabled extension" for both nodes. +This avoids issues where one node wants to change the "currently +enabled extension", +at the same time as the other node is sending a message +for the current extension. +Senders are responsible for setting the "currently enabled extension" +of the direction in which they are the sender, +and the receiver does not change this by itself. + +# Informing Extensions + +A node implementation informs its peer of supported extensions +by sending `have_extensions` message as soon as the +peer connection is established. + +## The `have_extensions` Message + +This message contains a set of extensions supported by a node. + +1. type: 49153 (`have_extensions`) +2. data: + * [`2` : `num_extensions`] + * [`num_extensions * 20` : `extensions`] + +### Requirements + +The sender: + - SHOULD send this message as soon as the connection is + established. + - MAY send this message zero or more times. + In case where it sends the message multiple times, + it sends the messages directly after the previous one + until it has indicated all extensions it supports. + - SHOULD send the minimum number of messages needed + to indicate its supported extensions. + - MUST NOT specify "no extension" (20 `0x00` bytes) as a + supported extension. + - MUST NOT specify an extension more than once. + - MAY send extensions in any order. + - MAY set `num_extensions` to 0. + +### Rationale + +As an odd-numbered message, older node software that do not +recognize this BOLT spec will ignore this message. +This allows node software that *does* support this BOLT spec +to interoperate seamlessly with node software that does not. + +Older node software will not send this message. +Thus, this message may be sent zero times. + +Lightning protocol messages have a maximum length, +implying a maximum number of extensions that can be specified +in a single message. +In case a node supports more than can fit in one message, +it is allowed to send multiple messages. + +# Enabling Extensions + +A node that wishes to utilize an extension supported by a peer +must first enable that extension by `use_extension`. +After sending `use_extension`, the sending node can +subsequently use message types 49154 to 65535 +as defined by the extension. + +## The `use_extension` Message + +1. type: 49152 (`use_extension`) +2. data: + * [`20` : `extension` ] + +### Requirements + +Before receiving this message, a node: + - MUST act as if the currently enabled extension for its + received messages is "no extension". + +The sender: + - MUST send this message before sending any extension-specific + message. + - MUST set `extension` to an extension that the receiver + has reported in `have_extensions`, or to the "no extension" + code (20 `0x00` bytes). + - MAY send an `extension` that is already the "currently enabled + extension" of the receiver. + - MUST ensure that this message is sent before it sends an + extension-specific message. + +The receiver: + - MUST fail the connection if `extension` is not "no extension" + and is not an extension it recognizes. + - MUST recognize future multiplexed message types (49154 to + 65535) as belonging to the specified extension, until the + next `use_extension`. + +# Authors + +* ZmnSCPxj