diff --git a/package.json b/package.json index 0737afe..ada1887 100644 --- a/package.json +++ b/package.json @@ -6,7 +6,7 @@ "start": "hexo server" }, "hexo": { - "version": "3.2.0" + "version": "3.2.2" }, "dependencies": { "hexo": "^3.1.0", @@ -31,4 +31,4 @@ "type": "git", "url": "git+https://github.com/ElementsProject/elementsproject.org.git" } -} +} \ No newline at end of file diff --git a/source/elements/asset-issuance/confidential-assets.md b/source/elements/asset-issuance/confidential-assets.md new file mode 100644 index 0000000..1a400c4 --- /dev/null +++ b/source/elements/asset-issuance/confidential-assets.md @@ -0,0 +1,180 @@ +--- +title: Confidential Assets +description: Extend security to multiple asset types while obscuring which ones are in use in specific transactions. +--- + +## Summary + +*Principal Investigator: Andrew Poelstra* + +The security of any blockchain ledger comes down to public verifiability of +two properties of every transaction: that they are authorized by all required +parties, and that they do not affect the total currency supply. In Bitcoin, +the latter property is so simple to check that it often goes unremarked: add +up the total output amount and total input amount and compare them. With the +development of [Confidential Transactions (CT)](/confidential-transactions/), +however, this security property is front and center, as it must be preserved +despite all amounts being cryptographically blinded. + +Several blockchain technologies have gone beyond Bitcoin to support multiple +asset types on the same chain. This allows a wider set of users to share the +security properties of the same chain, and also enables new use cases, such +as multi-asset transactions which effect atomic exchanges. Enabling this is +as simple as labelling each transaction output with a publicly visible "asset +tag"; however, this would expose information about users' financial behavior, +undermining the privacy benefits of CT. **Confidential Assets (CA)** is a +technology to support for multiple asset types while blinding all asset tags, +preserving the privacy of CT while extending the power and expressibility of +blockchain transactions. + +As in CT, Confidential Assets allows anybody to cryptographically verify that +a transaction is secure: the transaction is authorized by all required parties +and no asset is created, destroyed or transmuted. However, only the +participants in the transaction are able to see which asset types were used +and in what amounts. + +In a multi-asset chain, it may make sense in some contexts for assets of a +specific type to be created or destroyed. This is accomplished by means of +*issuance transactions*, which create new asset tags and a specified amount +of this asset. Later reissuance or deissuance may be done by proving ownership +of *issuance tokens*, which are related (but distinct) assets. Issuance tokens +may be created alongside a given asset type, or not, if the asset should not +support reissuance. + +Issuance transactions are unique in that they are not required to balance to +zero. However, if they issue a public amount, it is still verifiable that +exactly this amount, no more and no less, was actually issued. + +## Technology Behind Confidential Assets + +### Asset Tags and Rangeproofs + +To describe the technology behind CA, we start with the (Pedersen commitments +that [form the basis of Confidential Transactions](/confidential-transactions/): +``` +commitment = xG + aH +``` +where `G` is a standard generator of an elliptic curve and `H` is a second +generator for which nobody knows the discrete log with respect to `G`. We call +such a generator nothing-up-my-sleeve, or NUMS. + +In CT, this was described as committing to `a` coins with a blinding factor of +`x`. We observe that if we refer to the generator `H` as a coin we can read the +term `aH` algebraically as "`a` coins". When `H` is our only generator this is +merely a semantic trick. But suppose we add another NUMS generator `I`, and +consider the two commitments +``` +commitment_1 = xG + aH +commitment_2 = xG + aI +``` +Now we can think of `H` and `I` as representing two distinct assets, and we see +that these two commitments, while committing to the same amount, are commitments +to different assets. + +Consider now a complete transaction with two inputs of distinct asset types +and two outputs, like so + +``` +in1 = xG + aH, H --\ /-- uG + cH, H = out1 + |---| +in2 = yG + bI, I --/ \-- vG + dI, I = out2 +``` +In CT, where we had only one generator, we required the equation +``` +out1 + out2 - in1 - in1 = 0 +``` +to hold, which it would if and only if the transaction balanced. As it turns +out, this same equation works even with multiple assets: +``` +0 = out1 + out2 - in1 - in1 + = (uG + cH) + (vG + dI) - (xG + aH) - (yG + bI) + = (u + v - x - y)G + (c - a)H + (d - b)I +``` +Since `H` and `I` are both NUMS points, the only way for this equation to hold +is if each individual term is 0, and in particular, if `c = a` and `b = d`. In +other words, this equation holds only if the total amount of asset `H` is the +same on the input side as on the output side **and** the total amount of asset +`I` is the same on the input and output side. + +This extends naturally to more than two asset tags; in fact, it is possible to +support an unlimited number of distinct asset types, as long as each one can +be assigned a unique NUMS generator. + +As in CT, this simple equation is insufficient because it is possible for amounts +to overflow, effectively allowing negative-valued outputs. As in CT, this can be +solved by attaching a rangeproof to each output, in exactly the same way. The only +difference is that the verifier must use the appropriate asset tag in place of +the fixed generator `H`. + +### Blinded Asset Tags and Asset Surjection Proofs + +The above discussion assumed every transaction output had a NUMS generator, or +asset tag, associated to it, and that outputs of the same asset type would use +the same tag. This does not satisfy our privacy goals because it is visible +what type of asset every output represents. + +This can be solved by replacing each asset tag with a _blinded asset tag_ of +the form +``` +A = H + rG +``` +Here `H` is an asset tag from above and `r` is a secret random value. Anybody +who knows `r` can tell what asset this tag represents, but to anyone else it +will appear to be a uniformly random elliptic curve point. We see that any +commitment to a value with `A` is also a commitment to the same value with +`H`, so our "outputs minus inputs equals zero" rule will continue to work +when validating transactions: +``` +commitment_A = xG + aA = xG + a(H + rG) = (x + ra)G + aH = commitment_H +``` +The introduction of this blinding factor does not affect the user's ability +to produce a rangeproof, though it does make the algebra slightly more +complicated when constructing the transaction to balance out to zero. + +However, since every blinded asset tag looks uniformly random, how can +verifiers be sure that the underlying asset tags are legitimate? It turns +out that the "sum to zero" rule is not sufficient to prevent abuse. For +example, consider the "blinded asset tag" +``` +A' = -H + rG +``` +Any amount of the blinded asset `A'` will actually correspond to a _negative_ +amount of asset `H`, which an attacker could use to offset an illegal +increase of the money supply. + +To solve this problem we introduce an _asset surjection proof_, which is a +cryptographic proof that within a transaction, every output asset type is +the same as some input asset type, while blinding which outputs correspond +to which inputs. + +The way this works is simple. If `A` and `B` are blinded asset tags which +commit to the same asset tag `H`, say, then +``` +A - B = (H + aG) - (H + bG) = (a - b)G +``` +will be a signature key with corresponding secret key `a - b`. So for a +transaction output `out1`, we can use a ring signature (proof that one of +several secret keys is known that keeps secret which one) with the keys +`out1 - in1`, `out1 - in2`, and so on for every input in the transaction. +If `out1` has the same asset tag as one of the inputs, the transaction +signer will know the secret key corresponding to one of these differences, +and be able to produce the ring signature. + +The asset surjection proof consists of this ring signature. + +### Future Work + +Because algebraically, Confidential Assets is such a straightforward +extension of Confidential Transactions, many of the tools developed for +use with CT can be used with few modifications with CA, giving them the +power to confidently and confidentially handle multi-asset transactions. +Examples of such technologies are + +- ValueShuffle (add link, also check with Tim if the name has changed) +- [MimbleWimble](http://diyhpl.us/~bryan/papers2/bitcoin/mimblewimble.txt) +- [Scriptless Scripts](https://download.wpsoftware.net/bitcoin/wizardry/mw-slides/2017-03-mit-bitcoin-expo/slides.pdf) + +We are looking forward to the future, as many exciting developments +continue to appear. + + diff --git a/source/elements/asset-issuance/index.md b/source/elements/asset-issuance/index.md index 5c5a67b..6028064 100644 --- a/source/elements/asset-issuance/index.md +++ b/source/elements/asset-issuance/index.md @@ -1,29 +1,99 @@ --- -title: Basic Asset Issuance -description: Create new assets on a sidechain by using Bitcoin as a bond. +title: Asset Issuance +description: Create new assets on a sidechain, with optional confidentiality. image: /img/asset-issuance.svg -branch: alpha-0.10-multi-asset +branch: elements-0.14.1 source: https://github.com/ElementsProject/elementsproject.github.io/blob/master/source/elements/asset-issuance/index.md edit: https://github.com/ElementsProject/elementsproject.github.io/edit/master/source/elements/asset-issuance/index.md --- -*Principal Investigator: Jorge Timón* - * [alpha-0.10-multi-asset](https://github.com/ElementsProject/elements/tree/alpha-0.10-multi-asset) - branch of ongoing assets dev +
+

Want the cryptographic breakdown?

+

Read Andrew Poelstra's deep dive on Confidential Assets.

+
-Users can issue their own assets which represent fungible ownership of the underlying asset type representing by the newly created units, which could theoretically represent any asset including vouchers, coupons, currencies, deposits, bonds, shares, etc (subject to the respective jurisdiction’s regulatory requirements. +Users can issue their own confidential assets which represent fungible ownership +of the underlying asset type representing by the newly created units, which +could theoretically represent any asset including vouchers, coupons, currencies, +deposits, bonds, shares, etc. (subject to the respective jurisdiction’s +regulatory requirements). -This opens the door for building trustless exchanges, options, and other advanced smart contracts involving those arbitrary assets and the “hostcoin” (a native asset whose ID is equal to the hash of the genesis block or chain ID; in Alpha’s case, it is the federated-peg coin which is backed by testnet coins, see “Deterministic peg” section). +These assets can optionally be "blinded", causing the data in the transactions +(including amount and asset type) to be cryptographically obfuscated in such a +way that only the participating parties can see. Participants may choose to +reveal a "blinding key", which grants visibility into the transaction. -All outputs are tagged with their asset identifier. Consensus rules are modified so that the total inputs and outputs are checked separately per asset. -A new transaction type is added for creating issued assets (asset definition transactions). Like coinbase transactions, asset definition transactions (the new transaction type) have a null input, but unlike coinbases, asset definition transactions have more inputs in addition to that first null input. This difference not only helps us distinguish between the two: it also guarantees a source of entropy for the asset id (which is the sha256d hash of the transaction). Within an asset definition transaction, any number of outputs with 0 as asset ID can be included with any amount and they will be treated as the initial unspent outputs for the newly created asset. +This opens the door for building trustless exchanges, options, and other +advanced smart contracts involving those arbitrary assets and a "hostcoin". -This technology is similar to colored coins in many ways, but explicit and consensus-enforced tagging has many advantages: +### Issuing Assets +Use the all-new `issueasset` RPC command. Here, we're issuing 1000 new tokens, +and creating 200 "reissuance" tokens. +``` +$ elements-cli issueasset 1000 200 +> { + "txid": "13a2357b0a51114fae92127f7afc74847acf07f87e1bb4849715d1c75dbc9a92", + "vin": "0", + "entropy": "4dcc890a6fc4f593c609ffaa295940acb244904c1439aa9cb9d8192440b41da4", + "asset": "8854427e5ffcb0b837e85832b901b1135cc4ac766f537e2a7f07b71a76c5b9cf", + "token": "ca270d5552e81d15e4f45e41ff2d9c7e456599a7678286b80f8b41cae179b26a" +} +``` + +You can add convenient names for these assets by passing `-assetdir` to Elements +Core, which accepts a `hexidstring:label` map of the assets to their labels. + +#### Re-issuance +Re-issuing an asset is effectively a provable inflation in the asset type. To +do this, use `reissueasset`. Let's issue 20 of our tokens: + +``` +elements-cli reissueasset 8854427e5ffcb0b837e85832b901b1135cc4ac766f537e2a7f07b71a76c5b9cf 20 +{ + "txid": "6b20c853521346d5bda3fe9e006292260cf409054224f920f3abf6297aca8176", + "vin": 1 +} + +$ elements-cli getwalletinfo +> { + "walletversion": 130000, + "balance": { + "funcoin": 1020.00000000 + }, + "unconfirmed_balance": { + }, + "immature_balance": { + }, + "txcount": 1117, + "keypoololdest": 1490389457, + "keypoolsize": 100, + "paytxfee": 0.00000000, + "hdmasterkeyid": "f5ff0a90ac04830fde2f952cae9e076f9c2b4d39" +} +``` + +### How it works +All outputs are tagged with an asset commitment. Like CT, the consensus rules +are such that instead of checking that amounts are balanced, the value +commitments are checked for balance. A new transaction type is added for +creating issued assets (asset definition transactions). Asset definition +transactions have explicit `assetIssuance` fields embedded within transaction +inputs, up to one issuance per input, which denote the issuance of both the +asset itself and the reissuance tokens if desired. Embedding issuances within an +input allows us to re-use the entropy as a NUMS for the asset type itself. + +This technology is similar to colored coins in many ways, but explicit and +consensus-enforced tagging has many advantages: * Supports SPV wallets much more efficiently. * Allows more complex consensus-enforced contracts. * Benefits from other consensus-enforced extensions (ie confidential transactions would not be compatible with colored coins on top of Alpha). * Opens the door for further consensus-enforced extensions that rely on the chain being able to operate with multiple assets. -Currently only the hostcoin can be used to pay fees, but it should be possible to pay fees of different asset types simultaneously. -In this first version all units of a given type must be issued within the asset definition transaction. In future versions it will be possible to define assets with a dynamic supply that can be increased after the definition, allowing the issuer to create new units. -Future versions can also implement consensus enforced interest that would be interesting for p2p lending and issuance of assets with built-in demurrage (negative interest) among other things. +Currently only the hostcoin can be used to pay fees, but it should be possible +to pay fees of different asset types simultaneously. + +
+

Looking for the original investigation?

+

Read Jorge Timon's original investigation to learn about the origins of this Element.

+
diff --git a/source/elements/asset-issuance/investigation.md b/source/elements/asset-issuance/investigation.md new file mode 100644 index 0000000..e14eb32 --- /dev/null +++ b/source/elements/asset-issuance/investigation.md @@ -0,0 +1,20 @@ +*Principal Investigator: Jorge Timón* + * [alpha-0.10-multi-asset](https://github.com/ElementsProject/elements/tree/alpha-0.10-multi-asset) - branch of ongoing assets dev + +Users can issue their own assets which represent fungible ownership of the underlying asset type representing by the newly created units, which could theoretically represent any asset including vouchers, coupons, currencies, deposits, bonds, shares, etc (subject to the respective jurisdiction’s regulatory requirements. + +This opens the door for building trustless exchanges, options, and other advanced smart contracts involving those arbitrary assets and the “hostcoin” (a native asset whose ID is equal to the hash of the genesis block or chain ID; in Alpha’s case, it is the federated-peg coin which is backed by testnet coins, see “Deterministic peg” section). + +All outputs are tagged with their asset identifier. Consensus rules are modified so that the total inputs and outputs are checked separately per asset. +A new transaction type is added for creating issued assets (asset definition transactions). Like coinbase transactions, asset definition transactions (the new transaction type) have a null input, but unlike coinbases, asset definition transactions have more inputs in addition to that first null input. This difference not only helps us distinguish between the two: it also guarantees a source of entropy for the asset id (which is the sha256d hash of the transaction). Within an asset definition transaction, any number of outputs with 0 as asset ID can be included with any amount and they will be treated as the initial unspent outputs for the newly created asset. + +This technology is similar to colored coins in many ways, but explicit and consensus-enforced tagging has many advantages: + +* Supports SPV wallets much more efficiently. +* Allows more complex consensus-enforced contracts. +* Benefits from other consensus-enforced extensions (ie confidential transactions would not be compatible with colored coins on top of Alpha). +* Opens the door for further consensus-enforced extensions that rely on the chain being able to operate with multiple assets. + +Currently only the hostcoin can be used to pay fees, but it should be possible to pay fees of different asset types simultaneously. +In this first version all units of a given type must be issued within the asset definition transaction. In future versions it will be possible to define assets with a dynamic supply that can be increased after the definition, allowing the issuer to create new units. +Future versions can also implement consensus enforced interest that would be interesting for p2p lending and issuance of assets with built-in demurrage (negative interest) among other things. \ No newline at end of file diff --git a/source/elements/confidential-transactions/addresses.md b/source/elements/confidential-transactions/addresses.md index 3a8b8d9..88711f6 100644 --- a/source/elements/confidential-transactions/addresses.md +++ b/source/elements/confidential-transactions/addresses.md @@ -2,5 +2,53 @@ title: Confidential Addresses --- +The most visible implication of Confidential Transactions is the introduction of +a new default address type, confidential addresses: -TODO: explain them. +``` +CTEwQjyErENrxo8dSQ6pq5atss7Ym9S7P6GGK4PiGAgQRgoh1iPUkLQ168Kqptfnwmpxr2Bf7ipQsagi +``` + +The most obvious differences are that it starts with ``CT`` and is longer than +usual. This is due to the inclusion of a public blinding key prepended to the +base address. In the Elements Wallet, the blinding key is derived by using the +wallet's master blinding key and unblinded P2PKH address. Therefore the receiver +alone can decrypt the sent amount, and can hand it to auditors if needed. On the +sender's side, ``sendtoaddress`` will use this pubkey to transmit the necessary +info to the receiver, encrypted, and inside the transaction itself. The sender's +wallet will also record the amount and hold this in the ``wallet.dat`` metadata +as well as the ``audit.log`` file. + +``` +$ elements-cli validateaddress CTEwQjyErENrxo8dSQ6pq5atss7Ym9S7P6GGK4PiGAgQRgoh1iPUkLQ168Kqptfnwmpxr2Bf7ipQsagi +> { + "isvalid": true, + "address": "CTEwQjyErENrxo8dSQ6pq5atss7Ym9S7P6GGK4PiGAgQRgoh1iPUkLQ168Kqptfnwmpxr2Bf7ipQsagi", + "scriptPubKey": "76a91448a67bbdaf57b6f55b50f02fcaacfa079900853588ac", + "confidential_key": "02483237addc73befdb9b851f948c1488cbb7cf1a59ba8af36be1c479e0f6e8bc7", + "unconfidential": "QTE8CaT6FcJEqkCR4ZGdoUJfas57eDqY6q", + "ismine": true, + "iswatchonly": false, + "isscript": false, + "pubkey": "0347b013d415f7dc964cfadd0bb0627c48ae6ae27a58cdd37d71990eaf8f38c60c", + "iscompressed": true, + "account": "" +} +``` + +As you can see the unconfidential P2PKH address starts with a `Q`. P2SH start +with `H`. Most RPC calls outside of ``getnewaddress`` (e.g., ``listunspent``) +will return the unblinded version of addresses. If you provide an unconfidential +address to ``validateaddress`` it will show the confidential address. + +You **must** use the confidential address in ``sendtoaddress``, ``sendfrom``, +``sendmany`` and ``createrawtransaction`` if you want to create confidential +transactions. Therefore, when you want to receive confidential transactions you +must give the *confidential* address to the sender. For all other RPC's except +``dumpblindingkey`` it does not matter whether the confidential or +unconfidential address is provided. + +
+

Did you know?

+

By sharing the blinding key used in the construction of a single confidential transaction, users can share access to the transaction's details. Read more about selective disclosure »

+
\ No newline at end of file diff --git a/source/elements/confidential-transactions/index.md b/source/elements/confidential-transactions/index.md index 6759042..eee10cd 100644 --- a/source/elements/confidential-transactions/index.md +++ b/source/elements/confidential-transactions/index.md @@ -7,8 +7,8 @@ edit: https://github.com/ElementsProject/elementsproject.github.io/edit/master/s --- One of the most powerful new features being explored in Elements is Confidential -Transactions. This keeps the amounts transferred visible only to participants in -the transaction (and those they designate), while still guaranteeing that no +Transactions. This keeps the amounts transferred visible only to participants +in the transaction (and those they designate), while still guaranteeing that no more coins can be spent than are available in a cryptographic way. This goes a step beyond the usual privacy offered by Bitcoin's blockchain, which @@ -19,369 +19,93 @@ protection, thieves and scammers can focus their efforts on known high-value targets, competitors can learn business details, and negotiating positions can be undermined. -The most visible implication of Confidential Transactions is the introduction of -a new address type, [confidential -addresses](/confidential-transactions/addresses). These are longer than usual as -they also includes a blinding key for the values. Several sidechains, including -[alpha](/sidechains/alpha), use this address type as the default. +Watch Blockstream CTO Gregory Maxwell explaining Confidential Transactions at Coinbase: -### Designated Access -By sharing the blinding key used in the construction of a single confidential -transaction, users can share access to the details of an individual transaction. +
---- - -### Investigation -*Principal Investigator: [Gregory Maxwell](/contributors/gmaxwell)* - -The security of the Bitcoin ledger is made possible by universal verification: -each participant individually and autonomously verifies that each transaction is -valid, without trusting any third party. An unfortunate side effect is that all -the transaction data must be conspicuously public so it can be verified, which -is at odds with the normal expectation of privacy for traditional monetary -instruments. - -Insufficient financial privacy can have serious security and privacy -implications for both commercial and personal transactions. Without adequate -protection, thieves and scammers can focus their efforts on known high-value -targets, competitors can learn business details, and negotiating positions can -be undermined. Since publishing often requires spending money, lack of privacy -can chill free speech. Insufficient privacy can also result in a loss of -fungibility--where some coins are treated as more acceptable than others--which -would further undermine Bitcoin's utility as money. - -Bitcoin partially addresses the privacy problem by using pseudonymous -addresses. If someone does not know which users own which addresses, -the privacy impact is reduced. But any time you transact with someone -you learn at least one of their addresses. From there, you can trace out -other connected addresses and estimate the values of their transactions -and holdings. For example, suppose your employer pays you with Bitcoin -and you later spend those coins on your rent and groceries. Your landlord -and the supermarket will both learn your income, and could charge you -higher prices as your income changes or target you for theft. - -There are existing deployed techniques that further improve privacy -in Bitcoin (such as CoinJoin, which merges the transaction history of -users by making joint payments), but the utility of these techniques is -reduced by the fact that it's possible to track amounts. - -There have been proposed cryptographic techniques to improve privacy -in Bitcoin-like systems, but so far all of them result in breaking -"pruning" (section 7 of Bitcoin.pdf) and result in participants -needing a perpetually growing database to verify new transactions, -because these systems prevent learning which coins have been spent. Most -proposed cryptographic privacy systems also have poor performance, high -overhead, and/or require new and very strong (and less well understood) -cryptographic assumptions. - -Confidential Transactions improves the situation by making the transaction -amounts private, while preserving the ability of the public network -to verify that the ledger entries still add up. It does this without -adding any new basic cryptographic assumptions to the Bitcoin system, -and with a manageable level of overhead. - -CT is possible due to the cryptographic technique of additively -homomorphic commitments. As a side-effect of its design, CT also enables -the additional exchange of private "memo" data (such as invoice numbers -or refund addresses) without any further increase in transaction size, -by reclaiming most of the overhead of the CT cryptographic proofs. - - -## The technology behind Confidential Transactions: A high level technical primer - - -This work was originally proposed by Adam Back on -Bitcointalk in his 2013 thread "[bitcoins with homomorphic value] -(https://bitcointalk.org/index.php?topic=305791.0)". To build CT I had to -implement several new cryptosystems which work in concert, and invented -a generalization of ring signatures and several novel optimizations to -make the result reasonably efficient. - -The basic tool that CT is based on is a Pedersen commitment. - -A commitment scheme lets you keep a piece of data secret but commit to -it so that you cannot change it later. A simple commitment scheme can -be constructed using a cryptographic hash: - -``` -commitment = SHA256( blinding_factor || data ) -``` - -If you tell someone only the commitment then they cannot determine -what data you are committing to (given certain assumptions about the -properties of the hash), but you can later reveal both the data and the -blinding factor and they can run the hash and verify that the data you -committed to matches. The blinding factor is present because without one, -someone could try guessing at the data; if your data is small and simple, -it might be easy to just guess it and compare the guess to the commitment. +Read on to see how Confidential Transactions can be used, or jump straight to the math. -A Pedersen commitment works like the above but with an additional -property: commitments can be added, and the sum of a set of commitments -is the same as a commitment to the sum of the data (with a blinding key -set as the sum of the blinding keys): +
+

Did you know?

+

By sharing the blinding key used in the construction of a single confidential transaction, users can share access to the transaction's details. Read more about selective disclosure »

+
-``` -C(BF1, data1) + C(BF2, data2) == C(BF1 + BF2, data1 + data2) -C(BF1, data1) - C(BF1, data1) == 0 -``` - -In other words, the commitment preserves addition and the commutative -property applies. - -If data_n = {1,1,2} and BF_n = {5,10,15} then: - -``` -C(BF1, data1) + C(BF2, data2) - C(BF3, data3) == 0 -``` - -and so on. - -Our specific Pedersen commitments are constructed using elliptic curve -points. [The reader need not understand elliptic curve cryptography, -beyond accepting the black box behaviors I describe here.] - -Normally an ECC pubkey is created by multiplying a generator for the group -(G) with the secret key (x): - -``` -Pub = xG -``` - -The result is usually serialized as a 33-byte array. +### Using Confidential Transactions +The payment flow when using the Confidential Transactions Element is nearly +identical to Bitcoin Core on the surface: -ECC public keys obey the additively homomorphic property mentioned before: - -``` -Pub1 + Pub2 = (x1 + x2 (mod n))G. ``` +$ elements-cli getnewaddress +> CTEwQjyErENrxo8dSQ6pq5atss7Ym9S7P6GGK4PiGAgQRgoh1iPUkLQ168Kqptfnwmpxr2Bf7ipQsagi -(This fact is used by the BIP32 HD wallet scheme to allow third parties -to generate fresh Bitcoin addresses for people.) - -The Pedersen commitment is created by picking an additional generator -for the group (which we'll call H) such that no one knows the discrete -log for H with respect to G (or vice versa), meaning no one knows an -x such that xG = H. We can accomplish this by using the cryptographic -hash of G to pick H: - -``` -H = to_point(SHA256(ENCODE(G))) +$ elements-cli sendtoaddress CTEwQjyErENrxo8dSQ6pq5atss7Ym9S7P6GGK4PiGAgQRgoh1iPUkLQ168Kqptfnwmpxr2Bf7ipQsagi 0.005 +> 82b2c5122207e5f33e7adadc6a4aab16a170e16028f0b0cf2c04f9d17d6f0321 +// ^ this is the transaction id ``` -Given our two generators we can build a commitment scheme like this: - -``` -commitment = xG + aH -``` +The key difference from Bitcoin is the addition of cryptographic privacy. These +transactions differ in that the the amounts transferred are kept visible only to +participants in the transaction (and those they designate). -Here x is our secret blinding factor, and a is the amount that we're -committing to. You can verify just using the commutative property of -addition that all the relationships given for an additively homomorphic -commitment scheme hold. +
+ +
+

Confidential Addresses

+

Confidential Addresses may be new to you. Learn about Confidential Addresses »

+
+
-The Pedersen commitments are information-theoretically private: for any -commitment you see, there exists some blinding factor which would make -any amount match the commitment. Even an attacker with infinite computing -power could not tell what amount you committed to, if your blinding factor -was truly random. They are computationally secure against fake commitment, -in that you can't actually compute that arbitrary mapping; if you can -it means you can find the discrete log of the generators with respect -to each other, which means that the security of the group is compromised. +The ``createrawtransaction`` API in Elements works similar to Bitcoin's raw +transactions with the following differences: -With this tool in hand we can go and replace the normal 8-byte integer -amounts in Bitcoin transactions with 33-byte Pedersen commitments. +1. The intent to create a confidential output is indicated by using a confidential address for the destination. +2. The ``createrawtransaction`` RPC has the additional key ``nValue`` per input which must be set to the value of the input. The value can be determined for example with the ``listunspent`` RPC. +3. After calling ``createrawtransaction`` the user must call ``blindrawtransaction`` on the transaction if a confidential input or output address is involved. +4. If at least one of the inputs is confidential, at least one of the outputs must be confidential. Note that it is perfectly fine to create a 0-valued confidential output if otherwise there would be no confidential output. +5. If all inputs are unconfidential, the number of confidential outputs must be ``0`` or ``>= 2``. Again, it's fine to create a 0-valued confidential output. -If the author of a transaction takes care in picking their blinding -factors so that they add up correctly, then the network can still verify -the transaction by checking that its commitments add up to zero: +The following example spends a confidential and an unconfidential output and +creates a confidential and unconfidential output. Due to the size of the +transaction it is not displayed here but saved in the variable ``TX`` ``` -(In1 + In2 + In3 + plaintext_input_amount*H...) - - (Out1 + Out2 + Out3 + ... fees*H) == 0. +TX=`elements-cli createrawtransaction '[{"txid": "421079661b117b659af3431096ce2118043396e3647e523e413cd626fa798df7", "vout": 0, "nValue": 0.001}, {"txid": "17aa26d29582a9a26f02033918aaf9823d33458239074a0d7ee638b247f1fa2c", "vout": 0, "nValue": 0.001}]' '{"XoRDiv9z12ECsYCNjtHjDvV1Nn4KSBa6xRfHT1c3nKY1CwDiz5rzSMZL7QCgvuF1T5Kq43o1fMqBxbWQ": 0.001, "QLsHc5DgnpMjPaDSuEF5gXt7ccgmLtgh2N": 0.0005}'` +TX=`elements-cli blindrawtransaction $TX` +TX=`elements-cli signrawtransaction $TX | jq -r '.hex'` +elements-cli sendrawtransaction $TX ``` -This requires making the fees in a transaction explicit, but that's -generally desirable. - -The commitment and its checking are quite simple. Unfortunately, without -additional measures this scheme is insecure. - -The problem is that the group is cyclic, and addition is mod P (a 256-bit -prime number that defines the order of the group). As a result, an addition -of large values can 'overflow' and behave like negative amounts. This -means that a sums-to-zero behavior still holds when some outputs are -negative, effectively allowing the creation of 5 coins from nothing: - -``` -(1 + 1) - (-5 + 7) == 0 -``` - -This would be interpreted as "someone spends two bitcoins, gets a '-5' -bitcoin out that they discard out, and a 7 bitcoin output". - -In order to prevent this, when there are multiple outputs we must prove -that each committed output is within a range which cannot overflow -(e.g. [0, 2^64)). - -We could just disclose the amounts and blinding factors so that the -network could check, but this would lose all of the privacy. So, -instead, we need to prove that a committed amount is within the range -but reveal nothing else about it: we need an additional cryptosystem -to prove the range of a Pedersen commitment. We use a scheme similar -to Schoenmakers' binary decomposition but with many optimizations -(including not using binary). - -To build this we start with a basic EC signature. If a signature is -constructed so that the 'message' is the hash of the pubkey, the signature -proves that the signer knew the private key, which is the discrete log -of the pubkey with respect to some generator. - -For a 'pubkey' like P = xG + aH, no one knows the discrete log of P -with respect to G because of the addition of H, because no one knows -an x for xG = H----_unless_ a is 0. If a is zero then P = xG and the -discrete log is just x; someone could sign for that pubkey. - -A pedersen commitment can be proven to be a commitment to a zero by -just signing a hash of the commitment with the commitment as the public -key. Using the public key in the signature is required to prevent setting -the signature to arbitrary values and solving for the commitment. The -private key used for the signature is just the blinding factor. - -Going further, let's say I want to prove C is a commitment to 1 without -telling you the blinding factor. All you do is compute - -``` -C' = C - 1H -``` - -and ask me to provide a signature (with respect to G) with pubkey C'. If -I can do that, the C must be a commitment to 1 (or else I've broken the -EC discrete log security). - -To avoid giving away the amount we need yet another cryptographic -construct: a ring signature. A ring signature is a signature scheme -where there are two (or more) pubkeys and the signature proves that the -signer knows the discrete log of at least one of the pubkeys. - -So with that we can construct a scheme where I prove a commitment that -C is either 0 or 1--we call this an "OR proof". - -First, I give you C, and you compute C': - -``` -C' = C - 1H -``` - - -Then I provide a ring signature over {C, C'}. - -If C was a commitment to 1 then I do not know its discrete log, but -C' becomes a commitment to 0 and I do know its discrete log (just the -blinding factor). If C was a commitment to 0 I know its discrete log, -and I don't for C'. If it was a commitment to any other amount, none -of the result will be zero and I won't be able to sign. - -This works for any pair of numbers, just by suitably pre-processing the -amounts that are put into the ring... or even for more than two numbers. - -Say I want to prove to you that C is in the range [0, 32). Now that we -have an OR proof, imagine I send you a collection of commitments and OR -proofs for each of them: - -``` -C1 is 0 or 1 C2 is 0 or 2 C3 is 0 or 4 C4 is 0 or 8 C5 is 0 or 16. -``` - -If I pick the blinding factors for C1..5 correctly then I can arrange -it so that C1 + C2 + C3 + C4 + C5 == C. Effectively I have built up -the number in binary, and a 5-bit number can only be in the range [0,32). - -Numerous optimizations are required to make this more efficient: - -First, I propose a new ring -signature formulation, a Borromean ring signature[*](https://github.com/Blockstream/borromean_paper/raw/master/borromean_draft_0.01_34241bb.pdf), which is especially -efficient: it requires only 32 bytes per pubkey, plus 32 bytes which -can be shared by many separate rings. This is has twice the asymptotic -efficiency of previously proposed constructions for this application. - -Instead of expressing the amount directly, CT amounts are expressed -using a decimal floating point where the digits are multiplied by a -base 10 exponent. This means that you can prove large amounts with -small proofs, so long as they have few significant digits in base 10: -e.g., 11.2345 and .0112345 can have the same size proof, even though -one number is a thousand times larger. - -There is also a non-private "minimum amount" sent, which allows a smaller -proof to cover a larger range if the user doesn't mind leaking some -information about the minimum amount (which might already be public for -external reasons); this also allows the least significant digits to be -non-zero when an exponent is used. Minimum amounts are supported by first -subtracting the minimum, then proving that the result is non-negative. - -The mantissa of the floating point is encoded using rings of size 4 (base -4) rather than binary, because this minimizes the number of commitments -sent while not using any more signature data than base 2. - -The final mantissa digit commitment can be skipped, backwards constructing -it from the value being proven and the other digits, etc. - -Finally, by careful use of derandomized signing in the prover, it's -possible for the receiver of the coins--who shares a secret with the -sender, due to ECDH key agreement with the receivers pubkey--to 'rewind' -the proof and use it to extract a message sent by the sender which is 80% -of the size of the proof. We use this to signal the value and blinding -factor to the receiver, but it could also be used to carry things like -reference numbers or refund addresses. - -The result is that a proof for a 32-bit value is 2564 bytes, and -simultaneously may convey 2048 bytes of message. A 32-bit proof can -cover a range of 42.94967296 BTC with 1e-8 precision, or 429.4967296 -BTC with 1e-7 precision, and so on. My implementation is able to verify -over 1300 32-bit range proofs per second on an i7-4770R, and there are -many performance optimizations still possible. - -The implementation supports proofs of any mantissa size or exponent, with -the parameters controlled by the sender. Performance and size are linear -in the number of mantissa bits, and odd numbers of bits are supported -(by switching to radix-2 for the last digit). - -In Elements, the range proofs are only required in cases where there are -multiple confidential value outputs (including fees). Transactions that -merge multiple confidential amounts into a single output do not need range -proofs since the fact that all the inputs were in range is sufficient. - -By sharing the scanning key used to establish the shared secret used by -the rewindable range proofs, this approach is completely compatible with -watching wallets; users can share these keys with auditors to enable -them to view their transaction amounts. - -Future work may use the fact that proofs can support a minimum value to -also allow skipping the range proofs when there is a single confidential -output even when fees are being paid, or allow nodes to skip or delay -verifying most range proofs by using fraud proofs. +### Limitations +The implementation of Confidential Transactions as it appears in Elements has +some important limitations to be aware of. -The system presented here depends on no new fundamental cryptographic -assumptions, only the hardness of the discrete log problem in the -secp256k1 group and a random oracle assumption, just like the normal -signatures in Bitcoin. +For example, the implementation only hides a certain number of the digits of the +amount of each transaction output, dependent on the range proof's "blinding +coverage" at a desired precision level. Subsequently, there is a 'minimum +confidential amount' that around 0.0001 BTC, and a 'maximum confidential amount' +that is 232 times the minimum amount. -While the size of the range proofs are non-trivial, they are still an -order of magnitude smaller and faster to verify than some alternatives -(like Zerocoin), and most of their space can be reclaimed to communicate -additional data between users, a feature which is often requested but -hard to justify in a public broadcast network. Similar to signatures, -the range proofs can be placed on separate tree branches in blocks to -allow clients that don't care about (e.g. historical ones) to skip -receiving them. +Digits smaller than the minimum will be revealed to observers; for example, if +the minimum is 0.0001 BTC, a transaction output of 123.456789 BTC will look like +"?.????89 BTC". The tiny amount of information about the value leaked in this +way is unlikely to be important, but be aware that this could allow observers to +'follow' coins by linking subsequent transactions with identical amounts. All +values can be rounded to the minimum to avoid revealing information in this way +if preferred. -Most importantly, this scheme is compatible with pruning and does not make -the verification state for Bitcoin grow forever. It is also compatible -with CoinJoin and CoinSwap, allowing for transaction graph privacy as -well while simultaneously fixing the most severe limitation of these -approaches to privacy (that transaction amounts compromise their privacy). +A transaction output larger than the maximum will reveal the order of magnitude +of the amount to observers, _and_ will reveal additional digits at the bottom of +the amount. -Unlike some other proposals, this system is not just speculation or pure -cryptography without integration with the Bitcoin system. +For example, if the maximum is 500k BTC, then all outputs under +that amount will look the same, but an output between 500k and 5M BTC will be +visible as such to observers (but not the exact amount within that range), and +will also reveal one additional digit of the low end of the amount. Revealing +the range in this way could be a very significant privacy leak; splitting such +extremely large transactions to keep them under the maximum confidential amount +is strongly recommended. -Confidential Transactions is enabled in Elements and used by default by -all ordinary transactions. +
+

Want to learn more?

+

Gregory Maxwell's original investigation into Confidential Transactions has the mathy details!

+
diff --git a/source/elements/confidential-transactions/investigation.md b/source/elements/confidential-transactions/investigation.md new file mode 100644 index 0000000..3824506 --- /dev/null +++ b/source/elements/confidential-transactions/investigation.md @@ -0,0 +1,359 @@ +--- +title: Confidential Transaction, the Initial Investigation +--- +### Investigation +Principal Investigator: [Gregory Maxwell](/contributors/gmaxwell) + +The security of the Bitcoin ledger is made possible by universal verification: +each participant individually and autonomously verifies that each transaction is +valid, without trusting any third party. An unfortunate side effect is that all +the transaction data must be conspicuously public so it can be verified, which +is at odds with the normal expectation of privacy for traditional monetary +instruments. + +Insufficient financial privacy can have serious security and privacy +implications for both commercial and personal transactions. Without adequate +protection, thieves and scammers can focus their efforts on known high-value +targets, competitors can learn business details, and negotiating positions can +be undermined. Since publishing often requires spending money, lack of privacy +can chill free speech. Insufficient privacy can also result in a loss of +fungibility--where some coins are treated as more acceptable than others--which +would further undermine Bitcoin's utility as money. + +Bitcoin partially addresses the privacy problem by using pseudonymous +addresses. If someone does not know which users own which addresses, +the privacy impact is reduced. But any time you transact with someone +you learn at least one of their addresses. From there, you can trace out +other connected addresses and estimate the values of their transactions +and holdings. For example, suppose your employer pays you with Bitcoin +and you later spend those coins on your rent and groceries. Your landlord +and the supermarket will both learn your income, and could charge you +higher prices as your income changes or target you for theft. + +There are existing deployed techniques that further improve privacy +in Bitcoin (such as CoinJoin, which merges the transaction history of +users by making joint payments), but the utility of these techniques is +reduced by the fact that it's possible to track amounts. + +There have been proposed cryptographic techniques to improve privacy +in Bitcoin-like systems, but so far all of them result in breaking +"pruning" (section 7 of Bitcoin.pdf) and result in participants +needing a perpetually growing database to verify new transactions, +because these systems prevent learning which coins have been spent. Most +proposed cryptographic privacy systems also have poor performance, high +overhead, and/or require new and very strong (and less well understood) +cryptographic assumptions. + +Confidential Transactions improves the situation by making the transaction +amounts private, while preserving the ability of the public network +to verify that the ledger entries still add up. It does this without +adding any new basic cryptographic assumptions to the Bitcoin system, +and with a manageable level of overhead. + +CT is possible due to the cryptographic technique of additively +homomorphic commitments. As a side-effect of its design, CT also enables +the additional exchange of private "memo" data (such as invoice numbers +or refund addresses) without any further increase in transaction size, +by reclaiming most of the overhead of the CT cryptographic proofs. + + +## The technology behind Confidential Transactions: A high level technical primer + + +This work was originally proposed by Adam Back on +Bitcointalk in his 2013 thread "[bitcoins with homomorphic value] +(https://bitcointalk.org/index.php?topic=305791.0)". To build CT I had to +implement several new cryptosystems which work in concert, and invented +a generalization of ring signatures and several novel optimizations to +make the result reasonably efficient. + +The basic tool that CT is based on is a Pedersen commitment. + +A commitment scheme lets you keep a piece of data secret but commit to +it so that you cannot change it later. A simple commitment scheme can +be constructed using a cryptographic hash: + +``` +commitment = SHA256( blinding_factor || data ) +``` + +If you tell someone only the commitment then they cannot determine +what data you are committing to (given certain assumptions about the +properties of the hash), but you can later reveal both the data and the +blinding factor and they can run the hash and verify that the data you +committed to matches. The blinding factor is present because without one, +someone could try guessing at the data; if your data is small and simple, +it might be easy to just guess it and compare the guess to the commitment. + +A Pedersen commitment works like the above but with an additional +property: commitments can be added, and the sum of a set of commitments +is the same as a commitment to the sum of the data (with a blinding key +set as the sum of the blinding keys): + +``` +C(BF1, data1) + C(BF2, data2) == C(BF1 + BF2, data1 + data2) +C(BF1, data1) - C(BF1, data1) == 0 +``` + +In other words, the commitment preserves addition and the commutative +property applies. + +If data_n = {1,1,2} and BF_n = {5,10,15} then: + +``` +C(BF1, data1) + C(BF2, data2) - C(BF3, data3) == 0 +``` + +and so on. + +Our specific Pedersen commitments are constructed using elliptic curve +points. [The reader need not understand elliptic curve cryptography, +beyond accepting the black box behaviors I describe here.] + +Normally an ECC pubkey is created by multiplying a generator for the group +(G) with the secret key (x): + +``` +Pub = xG +``` + +The result is usually serialized as a 33-byte array. + +ECC public keys obey the additively homomorphic property mentioned before: + +``` +Pub1 + Pub2 = (x1 + x2 (mod n))G. +``` + +(This fact is used by the BIP32 HD wallet scheme to allow third parties +to generate fresh Bitcoin addresses for people.) + +The Pedersen commitment is created by picking an additional generator +for the group (which we'll call H) such that no one knows the discrete +log for H with respect to G (or vice versa), meaning no one knows an +x such that xG = H. We can accomplish this by using the cryptographic +hash of G to pick H: + +``` +H = to_point(SHA256(ENCODE(G))) +``` + +Given our two generators we can build a commitment scheme like this: + +``` +commitment = xG + aH +``` + +Here x is our secret blinding factor, and a is the amount that we're +committing to. You can verify just using the commutative property of +addition that all the relationships given for an additively homomorphic +commitment scheme hold. + +The Pedersen commitments are information-theoretically private: for any +commitment you see, there exists some blinding factor which would make +any amount match the commitment. Even an attacker with infinite computing +power could not tell what amount you committed to, if your blinding factor +was truly random. They are computationally secure against fake commitment, +in that you can't actually compute that arbitrary mapping; if you can +it means you can find the discrete log of the generators with respect +to each other, which means that the security of the group is compromised. + +With this tool in hand we can go and replace the normal 8-byte integer +amounts in Bitcoin transactions with 33-byte Pedersen commitments. + +If the author of a transaction takes care in picking their blinding +factors so that they add up correctly, then the network can still verify +the transaction by checking that its commitments add up to zero: + +``` +(In1 + In2 + In3 + plaintext_input_amount*H...) - + (Out1 + Out2 + Out3 + ... fees*H) == 0. +``` + +This requires making the fees in a transaction explicit, but that's +generally desirable. + +The commitment and its checking are quite simple. Unfortunately, without +additional measures this scheme is insecure. + +The problem is that the group is cyclic, and addition is mod P (a 256-bit +prime number that defines the order of the group). As a result, an addition +of large values can 'overflow' and behave like negative amounts. This +means that a sums-to-zero behavior still holds when some outputs are +negative, effectively allowing the creation of 5 coins from nothing: + +``` +(1 + 1) - (-5 + 7) == 0 +``` + +This would be interpreted as "someone spends two bitcoins, gets a '-5' +bitcoin out that they discard out, and a 7 bitcoin output". + +In order to prevent this, when there are multiple outputs we must prove +that each committed output is within a range which cannot overflow +(e.g. [0, 2^64)). + +We could just disclose the amounts and blinding factors so that the +network could check, but this would lose all of the privacy. So, +instead, we need to prove that a committed amount is within the range +but reveal nothing else about it: we need an additional cryptosystem +to prove the range of a Pedersen commitment. We use a scheme similar +to Schoenmakers' binary decomposition but with many optimizations +(including not using binary). + +To build this we start with a basic EC signature. If a signature is +constructed so that the 'message' is the hash of the pubkey, the signature +proves that the signer knew the private key, which is the discrete log +of the pubkey with respect to some generator. + +For a 'pubkey' like P = xG + aH, no one knows the discrete log of P +with respect to G because of the addition of H, because no one knows +an x for xG = H----_unless_ a is 0. If a is zero then P = xG and the +discrete log is just x; someone could sign for that pubkey. + +A pedersen commitment can be proven to be a commitment to a zero by +just signing a hash of the commitment with the commitment as the public +key. Using the public key in the signature is required to prevent setting +the signature to arbitrary values and solving for the commitment. The +private key used for the signature is just the blinding factor. + +Going further, let's say I want to prove C is a commitment to 1 without +telling you the blinding factor. All you do is compute + +``` +C' = C - 1H +``` + +and ask me to provide a signature (with respect to G) with pubkey C'. If +I can do that, the C must be a commitment to 1 (or else I've broken the +EC discrete log security). + +To avoid giving away the amount we need yet another cryptographic +construct: a ring signature. A ring signature is a signature scheme +where there are two (or more) pubkeys and the signature proves that the +signer knows the discrete log of at least one of the pubkeys. + +So with that we can construct a scheme where I prove a commitment that +C is either 0 or 1--we call this an "OR proof". + +First, I give you C, and you compute C': + +``` +C' = C - 1H +``` + + +Then I provide a ring signature over {C, C'}. + +If C was a commitment to 1 then I do not know its discrete log, but +C' becomes a commitment to 0 and I do know its discrete log (just the +blinding factor). If C was a commitment to 0 I know its discrete log, +and I don't for C'. If it was a commitment to any other amount, none +of the result will be zero and I won't be able to sign. + +This works for any pair of numbers, just by suitably pre-processing the +amounts that are put into the ring... or even for more than two numbers. + +Say I want to prove to you that C is in the range [0, 32). Now that we +have an OR proof, imagine I send you a collection of commitments and OR +proofs for each of them: + +``` +C1 is 0 or 1 C2 is 0 or 2 C3 is 0 or 4 C4 is 0 or 8 C5 is 0 or 16. +``` + +If I pick the blinding factors for C1..5 correctly then I can arrange +it so that C1 + C2 + C3 + C4 + C5 == C. Effectively I have built up +the number in binary, and a 5-bit number can only be in the range [0,32). + +Numerous optimizations are required to make this more efficient: + +First, I propose a new ring +signature formulation, a Borromean ring signature[*](https://github.com/Blockstream/borromean_paper/raw/master/borromean_draft_0.01_34241bb.pdf), which is especially +efficient: it requires only 32 bytes per pubkey, plus 32 bytes which +can be shared by many separate rings. This is has twice the asymptotic +efficiency of previously proposed constructions for this application. + +Instead of expressing the amount directly, CT amounts are expressed +using a decimal floating point where the digits are multiplied by a +base 10 exponent. This means that you can prove large amounts with +small proofs, so long as they have few significant digits in base 10: +e.g., 11.2345 and .0112345 can have the same size proof, even though +one number is a thousand times larger. + +There is also a non-private "minimum amount" sent, which allows a smaller +proof to cover a larger range if the user doesn't mind leaking some +information about the minimum amount (which might already be public for +external reasons); this also allows the least significant digits to be +non-zero when an exponent is used. Minimum amounts are supported by first +subtracting the minimum, then proving that the result is non-negative. + +The mantissa of the floating point is encoded using rings of size 4 (base +4) rather than binary, because this minimizes the number of commitments +sent while not using any more signature data than base 2. + +The final mantissa digit commitment can be skipped, backwards constructing +it from the value being proven and the other digits, etc. + +Finally, by careful use of derandomized signing in the prover, it's +possible for the receiver of the coins--who shares a secret with the +sender, due to ECDH key agreement with the receivers pubkey--to 'rewind' +the proof and use it to extract a message sent by the sender which is 80% +of the size of the proof. We use this to signal the value and blinding +factor to the receiver, but it could also be used to carry things like +reference numbers or refund addresses. + +The result is that a proof for a 32-bit value is 2564 bytes, and +simultaneously may convey 2048 bytes of message. A 32-bit proof can +cover a range of 42.94967296 BTC with 1e-8 precision, or 429.4967296 +BTC with 1e-7 precision, and so on. My implementation is able to verify +over 1300 32-bit range proofs per second on an i7-4770R, and there are +many performance optimizations still possible. + +--- + +The implementation supports proofs of any mantissa size or exponent, with +the parameters controlled by the sender. Performance and size are linear +in the number of mantissa bits, and odd numbers of bits are supported +(by switching to radix-2 for the last digit). + +In Elements, the range proofs are only required in cases where there are +multiple confidential value outputs (including fees). Transactions that +merge multiple confidential amounts into a single output do not need range +proofs since the fact that all the inputs were in range is sufficient. + +By sharing the scanning key used to establish the shared secret used by +the rewindable range proofs, this approach is completely compatible with +watching wallets; users can share these keys with auditors to enable +them to view their transaction amounts. + +Future work may use the fact that proofs can support a minimum value to +also allow skipping the range proofs when there is a single confidential +output even when fees are being paid, or allow nodes to skip or delay +verifying most range proofs by using fraud proofs. + +The system presented here depends on no new fundamental cryptographic +assumptions, only the hardness of the discrete log problem in the +secp256k1 group and a random oracle assumption, just like the normal +signatures in Bitcoin. + +While the size of the range proofs are non-trivial, they are still an +order of magnitude smaller and faster to verify than some alternatives +(like Zerocoin), and most of their space can be reclaimed to communicate +additional data between users, a feature which is often requested but +hard to justify in a public broadcast network. Similar to signatures, +the range proofs can be placed on separate tree branches in blocks to +allow clients that don't care about (e.g. historical ones) to skip +receiving them. + +Most importantly, this scheme is compatible with pruning and does not make +the verification state for Bitcoin grow forever. It is also compatible +with CoinJoin and CoinSwap, allowing for transaction graph privacy as +well while simultaneously fixing the most severe limitation of these +approaches to privacy (that transaction amounts compromise their privacy). + +Unlike some other proposals, this system is not just speculation or pure +cryptography without integration with the Bitcoin system. + +Confidential Transactions is enabled in Elements and used by default by +all ordinary transactions. \ No newline at end of file diff --git a/source/elements/confidential-transactions/selective-disclosure.md b/source/elements/confidential-transactions/selective-disclosure.md new file mode 100644 index 0000000..d343d07 --- /dev/null +++ b/source/elements/confidential-transactions/selective-disclosure.md @@ -0,0 +1,79 @@ +--- +title: Using Confidential Transactions for Selective Disclosure +--- + +The [Confidential Transactions][confidential-transactions] element offers cryptographic privacy over the amounts of an asset used in +transactions on a sidechain. There are many use cases for selectively disclosure some parts of +a transaction, for example to an auditor. + +### The Blinding Key +The "Blinding Key" is a shared value between the participants that grants them +access to the cryptographically-concealed amount. By sharing this key (out of +band), external parties will have the ability to "decrypt" the transaction. + +In order to execute a third-party audit of transaction amounts, the blinding key +can be exported by the receiver and passed on to the auditor. + +#### Retrieving the Blinding Key for a Particular Address +``` +$ elements-cli dumpblindingkey CTEwQjyErENrxo8dSQ6pq5atss7Ym9S7P6GGK4PiGAgQRgoh1iPUkLQ168Kqptfnwmpxr2Bf7ipQsagi +> 5fd02f714d52b68bbbfef3b8e6d83be646fad1de5150e83d26a28496e00a2146 +``` + +An auditor may then import the address and blinding key with +``importblindingkey`` to observe watch-only amounts. + +``` +$ elements-cli importaddress CTEwQjyErENrxo8dSQ6pq5atss7Ym9S7P6GGK4PiGAgQRgoh1iPUkLQ168Kqptfnwmpxr2Bf7ipQsagi +$ elements-cli listtransactions "*" 1 0 true +> [] + +$ elements-cli importblindingkey CTEwQjyErENrxo8dSQ6pq5atss7Ym9S7P6GGK4PiGAgQRgoh1iPUkLQ168Kqptfnwmpxr2Bf7ipQsagi 5fd02f714d52b68bbbfef3b8e6d83be646fad1de5150e83d26a28496e00a2146 +$ elements-cli listtransactions "*" 1 0 true +> [ + { + "involvesWatchonly": true, + "account": "", + "address": "QTE8CaT6FcJEqkCR4ZGdoUJfas57eDqY6q", + "category": "receive", + "amount": 0.00500000, + "label": "", + "vout": 1, + "confirmations": 35, + "blockhash": "708f969b4fb1c705b82fa3ed309abc7a3d9b0e87aa6e5d17542bb7ee04c8e1f1", + "blockindex": 1, + "blocktime": 1488223140, + "txid": "82b2c5122207e5f33e7adadc6a4aab16a170e16028f0b0cf2c04f9d17d6f0321", + "walletconflicts": [ + ], + "time": 1488223140, + "timereceived": 1488225018, + "bip125-replaceable": "no", + "blindingfactors": "0000000000000000000000000000000000000000000000000000000000000000:71260137a80039dd8cee330d9f7bba625697dc53098cf54d625242946f26997b:" + } +] +``` + +You may also inspect an address in full: +``` +$ elements-cli validateaddress CTEwQjyErENrxo8dSQ6pq5atss7Ym9S7P6GGK4PiGAgQRgoh1iPUkLQ168Kqptfnwmpxr2Bf7ipQsagi +> { + "isvalid": true, + "address": "CTEwQjyErENrxo8dSQ6pq5atss7Ym9S7P6GGK4PiGAgQRgoh1iPUkLQ168Kqptfnwmpxr2Bf7ipQsagi", + "scriptPubKey": "76a91405d5c237c5f2d90cfa22a22b75a1d1c1ede021a088ac", + "confidential_key": "03b0f93d729839d3d96bfd7e20f11c7c6ae2016644d0d4cded6332dbfb61ed9067", + "unconfidential": "2dZxbqgzXvANyj9SmyRR9LX3R2k8hg4iUWa", + "ismine": true, + "iswatchonly": false, + "isscript": false, + "pubkey": "031f17ad1acce63acf2d04cc59cb24423ab30f9345dd17476fd2380b02f878295d", + "iscompressed": true, + "account": "", + "hdkeypath": "m/0'/0'/10'", + "hdmasterkeyid": "f5ff0a90ac04830fde2f952cae9e076f9c2b4d39" +} + +``` + +[confidential-transactions]: /elements/confidential-transactions + diff --git a/source/elements/deterministic-pegs/index.md b/source/elements/deterministic-pegs/index.md index 9498a31..40a52fe 100644 --- a/source/elements/deterministic-pegs/index.md +++ b/source/elements/deterministic-pegs/index.md @@ -12,4 +12,4 @@ Deterministic pegs allow Elements Alpha to carry redeemable testnet coins withou Sidechains, like other alternative chains, can also be secured by merge-mining. However during a bootstrap period of introduction of a new chain, unless the start of merge mining were very well synchronised, there will be a period of lower hashrate. During the early stages of this bootstrap the chain could have low enough hashrate to present a security risk even against a modest powered attacker. Given the challenges of synchronising something as organic and decentralised by design as bitcoin mining, we therefore need a mechanism to bootstrap chain security. We start in this release with a threshold of functionaries and are plan for a later version to phase in merge-mining. -A detailed explanation of the implementation in Elements Alpha can be found in the [blog](/posts/The-Federated-Peg-in-Elements-Alpha/). +A detailed explanation of the implementation in Elements Alpha can be found in the [blog](/posts/the-federated-peg-in-elements-alpha/). diff --git a/source/elements/index.md b/source/elements/index.md index 9ccec73..1030d6d 100644 --- a/source/elements/index.md +++ b/source/elements/index.md @@ -17,9 +17,30 @@ edit: https://github.com/ElementsProject/elementsproject.github.io/edit/master/s Elements is an open source collaborative project where we work on a collection of experiments to more rapidly bring technical innovation to Bitcoin. Elements are features that are proposed and developed in this technical community that in arbitrary combinations can be fashioned into sidechains. ## Current Elements -These are the features under currently under investigation as part of [the Alpha developer sidechain](/sidechains/alpha). +These are the features currently available in [Elements Core][github], the +open-source reference implementation for sidechains. For projects built with +the latest version of Elements, such as [Liquid][liquid], you can expect them to +support each of these features. -
+For a list of proposed Elements, see the bottom of this document. + +
+ +
+ +
+
+
+
Ai
+
Asset Issuance
+
+
+
+ + + +
+
@@ -32,7 +53,7 @@ These are the features under currently under investigation as part of [the Alpha
- +
@@ -48,7 +69,7 @@ These are the features under currently under investigation as part of [the Alpha
- + @@ -66,7 +87,7 @@ These are the features under currently under investigation as part of [the Alpha
- +
@@ -82,7 +103,7 @@ These are the features under currently under investigation as part of [the Alpha
- +
@@ -98,7 +119,7 @@ These are the features under currently under investigation as part of [the Alpha
- +
@@ -115,7 +136,7 @@ These are the features under currently under investigation as part of [the Alpha
- +
@@ -131,7 +152,7 @@ These are the features under currently under investigation as part of [the Alpha
- +
@@ -147,7 +168,7 @@ These are the features under currently under investigation as part of [the Alpha
- +
@@ -157,17 +178,6 @@ These are the features under currently under investigation as part of [the Alpha These are some of the features currently under development, but are not yet ready for deployment on a public sidechain.
- -
- -
-
-
-
Ai
-
Asset Issuance
-
-
-
@@ -191,3 +201,6 @@ These are some of the features currently under development, but are not yet read
+ +[github]: https://github.com/ElementsProject/elements +[liquid]: /sidechains/liquid diff --git a/source/elements/schnorr-signatures/index.md b/source/elements/schnorr-signatures/index.md index 75b4e2c..93b3b7d 100644 --- a/source/elements/schnorr-signatures/index.md +++ b/source/elements/schnorr-signatures/index.md @@ -15,3 +15,5 @@ Potential support for batch validation (up to a factor 2 speedup to verify group Stronger security proof. * Provably no inherent signature malleability, while ECDSA has a known malleability, and lacks a proof that no other forms exist. Note that Witness Segregation already makes signature malleability not result in transaction malleability, however. * Slightly faster to sign/verify than ECDSA. + +Andrew Poelstra lists more advantages on [the MimbleWimble mailing list](https://lists.launchpad.net/mimblewimble/msg00086.html). diff --git a/source/elements/signed-blocks/index.md b/source/elements/signed-blocks/index.md index c48a241..4aed712 100644 --- a/source/elements/signed-blocks/index.md +++ b/source/elements/signed-blocks/index.md @@ -2,7 +2,7 @@ title: Signed Blocks description: Blocks can be cryptographically signed, allowing the creator of the block to verify their identity in the future. image: /img/signed-blocks.svg -branch: block-signing-0.10 +branch: elements-0.14.1 source: https://github.com/ElementsProject/elementsproject.github.io/blob/master/source/elements/signed-blocks/index.md edit: https://github.com/ElementsProject/elementsproject.github.io/edit/master/source/elements/signed-blocks/index.md --- diff --git a/source/img/deterministic-pegs.svg b/source/img/deterministic-pegs.svg index 859969c..59a28c4 100644 --- a/source/img/deterministic-pegs.svg +++ b/source/img/deterministic-pegs.svg @@ -15,21 +15,21 @@ s10.8,2.7,10.8,6.1c0,1.2-0.9,2.2-1.8,3.3C61.7,41.7,61.3,46.8,61.3,51.7L61.3,51.7z"/> - + - + - - + - diff --git a/source/img/liquid-logo.png b/source/img/liquid-logo.png new file mode 100644 index 0000000..3330b9c Binary files /dev/null and b/source/img/liquid-logo.png differ diff --git a/source/img/time-lock.svg b/source/img/time-lock.svg index d05fdf9..2715a13 100644 --- a/source/img/time-lock.svg +++ b/source/img/time-lock.svg @@ -5,7 +5,7 @@ - + diff --git a/source/sidechains/alpha/getting-started.md b/source/sidechains/alpha/getting-started.md index 90a050c..e3e0697 100644 --- a/source/sidechains/alpha/getting-started.md +++ b/source/sidechains/alpha/getting-started.md @@ -303,5 +303,6 @@ see what you build! [presentation]: https://people.xiph.org/~greg/blockstream.gmaxwell.elements.talk.060815.pdf [elements]: http://elementsproject.github.io +[alpha]: /sidechains/alpha [testnet faucet]: https://testnet-faucet.elementsproject.org/ [elements github]: https://github.com/ElementsProject/elements diff --git a/source/sidechains/creating-your-own.md b/source/sidechains/creating-your-own.md index 4dabdf8..a352339 100644 --- a/source/sidechains/creating-your-own.md +++ b/source/sidechains/creating-your-own.md @@ -3,162 +3,112 @@ title: Building A New Sidechain with Elements edit: https://github.com/ElementsProject/elementsproject.github.io/blob/master/source/sidechains/creating-your-own.md source: https://github.com/ElementsProject/elementsproject.github.io/edit/master/source/sidechains/creating-your-own.md --- -This is a basic step-by-step guide to building your own sidechain and setting up -a federated peg mechanism. This configuration works to run a sidechain with -a 1-of-1 functionary/blocksigner. (Not tested on multiple nodes with more than 1 -signer). -There are several other ways of deriving consensus on a sidechain. See [the Deterministic Peg Element](/elements/deterministic-peg.html) for more details. +This step-by-step guide will walk you through building your own sidechain and +setting up a simple single-signer peg with a `regtest`-powered mainchain. This +configuration works to run a sidechain with a 1-of-1 functionary/blocksigner, +convenient for local development and testing. -#### Elements -Please look over [the Elements -Git Repository](https://github.com/ElementsProject/elements), if you haven't already. -Also read [Alpha -README](https://github.com/ElementsProject/elements/blob/alpha/alpha-README.md) -for building dependencies and to follow along. The instructions for building the -dependencies are pretty cut and clear, however, the building of a new fedpeg -isn't as detailed. Keep the Elements Project's Alpha-README open in a separate -tab for reference. +There are several other ways of deriving consensus on a sidechain. See [the +Deterministic Peg Element](/elements/deterministic-peg.html) for more details. #### Prerequisites -1. *Linux.* Building with Windows is possible - publish a guide if you know how as there isn't one publicly available! :) -2. *All dependencies for Elements Alpha.* See [Build Notes](https://github.com/bitcoin/bitcoin/blob/master/doc/build-unix.md) - -#### Build -Try to follow this order to avoid unneccessary recompilations. This is an extension of the instructions to "Run a fedpeg operator" in the Element's alpha README. - -Edit your `.bashrc`. We'll come back to this file later: -```shell -RPC_USER=your_username_here -RPC_PASSWORD=your_super_random_long_password_here -export RPC_USER -export RPC_PASS -``` - -Build bitcoin (mainchain): -```shell -git clone https://github.com/ElementsProject/elements -cd elements -git checkout mainchain -./autogen.sh && ./configure && make -mv src/bitcoin{d,-cli,-tx} ../ -``` - -Run testnet. If you get an error asking to rebuild the blockchain, replace `-txindex` with `-reindex`. If you have to rebuild it, continue these instructions while it syncs: -```shell -./bitcoind -rpcuser=$RPC_USER -rpcpassword=$RPC_PASS -testnet -txindex -daemon -``` - -Checkout the `alpha` branch. -```shell -git checkout alpha -``` - -With bitcoin testnet, generate an address and obtain the private/public key. -``` -bitcoin-cli -testnet getnewaddress -//returns some address -bitcoin-cli -testnet dumpprivkey [address] -//returns private key. Save this - we'll need it later for .bashrc file -bitcoin-cli -testnet validateaddress [address] -//returns JSON object. Copy the public key. -``` - -#### C++ -You should be on your sidechain branch (alpha). This is the part where we uniquely create your sidechain with the public keys of each functionary/blocksigner. Open `src/chainparams.cpp` and edit the public keys, ports, and seeds. [Line 132](https://github.com/ElementsProject/elements/blob/alpha/src/chainparams.cpp#L132) has the public keys for each functionary/blocksigner: -```c++ -scriptDestination = CScript() << OP_5 - << ParseHex("027d5d62861df77fc9a37dbe901a579d686d1423be5f56d6fc50bb9de3480871d1") - << ParseHex("03b41ea6ba73b94c901fdd43e782aaf70016cc124b72a086e77f6e9f4f942ca9bb") - << ParseHex("02be643c3350bade7c96f6f28d1750af2ef507bc1f08dd38f82749214ab90d9037") - << ParseHex("021df31471281d4478df85bfce08a10aab82601dca949a79950f8ddf7002bd915a") - << ParseHex("0320ea4fcf77b63e89094e681a5bd50355900bf961c10c9c82876cb3238979c0ed") - << ParseHex("021c4c92c8380659eb567b497b936b274424662909e1ffebc603672ed8433f4aa1") - << ParseHex("027841250cfadc06c603da8bc58f6cd91e62f369826c8718eb6bd114601dd0c5ac") - << OP_7 << OP_CHECKMULTISIG; -``` - -For simplicity, let's replace the current 5-of-7 multisig with a 1-of-1. Change to: -```c++ -scriptDestination = CScript() << OP_1 - << ParseHex("[paste public key we just generated]") - << OP_1 << OP_CHECKMULTISIG; -``` -[Line 139](https://github.com/ElementsProject/elements/blob/alpha/src/chainparams.cpp#L139) has the DNS seeds. If you have more than 1 functionary/blocksigner, you'll need to create a DNS of your own in order to communicate. Replace the current 5 seeds with the seeds of your signers. Also delete the testnet seed on [L198](https://github.com/ElementsProject/elements/blob/alpha/src/chainparams.cpp#L198). If you're creating a local 1-of-1 sidechain on your machine that won't be communicating on any port, you don't need to create any seeds or configure the protocol port. - -Still in `src/chainparams.cpp`, change the testnet port number on [L182](https://github.com/ElementsProject/elements/blob/alpha/src/chainparams.cpp#L182) - this is the unique channel of communication for your sidechain so don't just increase/decrease it by one. This is one of two ports we'll change. Call this one the protocol port. - -You need to duplicate what you did on L132 of `src/chainparams.cpp` on [L1451](https://github.com/ElementsProject/elements/blob/alpha/src/script/interpreter.cpp#L1451) of `src/script/interpreter.cpp`. -Replace this line -```c++ -CScript scriptDestination(CScript() << OP_5 - << ParseHex("0269992fb441ae56968e5b77d46a3e53b69f136444ae65a94041fc937bdb28d933") - << ParseHex("021df31471281d4478df85bfce08a10aab82601dca949a79950f8ddf7002bd915a") - << ParseHex("02174c82021492c2c6dfcbfa4187d10d38bed06afb7fdcd72c880179fddd641ea1") - << ParseHex("033f96e43d72c33327b6a4631ccaa6ea07f0b106c88b9dc71c9000bb6044d5e88a") - << ParseHex("0313d8748790f2a86fb524579b46ce3c68fedd58d2a738716249a9f7d5458a15c2") - << ParseHex("030b632eeb079eb83648886122a04c7bf6d98ab5dfb94cf353ee3e9382a4c2fab0") - << ParseHex("02fb54a7fcaa73c307cfd70f3fa66a2e4247a71858ca731396343ad30c7c4009ce") - << OP_7 << OP_CHECKMULTISIG); -``` -with - -```c++ -CScript scriptDestination(CScript() << OP_1 - << ParseHex("[paste public key we just generated]") - << OP_1 << OP_CHECKMULTISIG); -``` - -Open `src/chainparamsbase.cpp`, change the port on [L43](https://github.com/ElementsProject/elements/blob/alpha/src/chainparamsbase.cpp#L43). This is the RPC port - keep it different from the protocol port (i.e. alpha's ports are 4241 and 4242). On L44 of the same file, you can change the name of the data directory for your sidechain (where your blocks, .dat files, etc. will be stored). - -At this point, you can compile your sidechain in the same way we compiled the mainchain earlier. There are a few help/console string messages you can change in `main.cpp, init.cpp, bitcoind.cpp`, but it's not necessary for basic functional purposes. - -```shell -./autogen.sh && ./configure && make -``` - -If there's a error in your compilation, go back to the file the compilation failed on and fix the error. Make sure to run `make clean` before compilating again. You'll only need to recompile your sidechain branch, not the bitcoin testnet `mainchain` branch. - -Upon successful compilation: -```shell -mv src/alpha{d,-cli,-tx} ../ -./alphad -rpcuser=$RPC_USER -rpcpassword=$RPC_PASS -testnet -rpcconnect=127.0.0.1 -rpcconnectport=18332 -tracksidechain=all -txindex -blindtrust=false -daemon -``` - -####Python - -Once your sidechain server is running, we can edit the Python files with your unique details. - -Inside `contrib/fedpeg/constants.py`, change the port number on [L9](https://github.com/TomMcCabe/elements/blob/patch/contrib/fedpeg/constants.py) to the port number you specified above inside of your [src/chainparamsbase.cpp](https://github.com/ElementsProject/elements/blob/alpha/src/chainparamsbase.cpp#L43). You do NOT change the `bitcoin_url` port. - -We need to create a unique `redeem_script` and `redeem_script_address` for your sidechain. To do this, take the public key[s] in `chainparams.cpp` and use the `createmultisig` RPC, which will return an address and a redeem script. Adjust [L12-L13](https://github.com/Christewart/elements/blob/sidechain/contrib/fedpeg/constants.py#L12-L13) in `constants.py` with the values given by the following RPC command: - -```shell -alpha-cli -testnet createmultisig [sigs_required] "[\"public key\", ...]" -``` - -You can test this by decoding the redeem script (`alpha-cli -testnet decodescript [redeem script])`, which will return a JSON object with the public keys, signatures required and P2SH address. - -Replace the `nodes` with the network addresses (i.e. IPs) of your sidechain's blocksigners/functionaries. Add your network address to `my_node`. - -Open the `.bashrc` file we edited earlier and add this to the bottom: - -```shell -BLOCKSIGNING_PRIV_KEY=[private key generated earlier - associated to the public key in chainparmas.cpp] -FUNCTIONARY_PRIV_KEY=[some separate generated private key] -export BLOCKSIGNING_PRIV_KEY -export FUNCTIONARY_PRIV_KEY -``` - -Also be sure to import both private keys into your sidechain wallet using the RPC command: - -```shell -alpha-cli -testnet importprivkey [private key] -``` - -The default sidechain blocktimes are set at 60 seconds. You can adjust the time on [L58](https://github.com/ElementsProject/elements/blob/alpha/contrib/fedpeg/blocksign.py#L58) of `contrib/fedpeg/blocksign.py`. Be sure to change the port number in [blocksign.py](https://github.com/ElementsProject/elements/blob/alpha/contrib/fedpeg/blocksign.py#L14) if you have multiple functionaries/blocksigners. - -From here, you can follow [Step 6](https://github.com/ElementsProject/elements/blob/alpha/alpha-README.md#to-move-money-into-elements-alpha) of the Elements-Alpha README to move money into the sidechain. After the "claim-on-sidechain" part, run `blocksign.py` to run the blocksigning script(remember you can shorten block times): -```shell -./contrib/fedpeg/blocksign.py -``` +You'll need a working version of Elements. Follow [the Elements build +instructions](https://github.com/ElementsProject/elements/blob/elements-0.14.1/doc/build-unix.md) +to get set up. + +### Creating your own blockchain +Just like in Bitcoin, Elements can be started in `regtest` mode which allows to +easily create test chains and networks. + +1. Start Elements: + > `elementsd -regtest -daemon` +2. Create an alias for the RPC client: + > `alias ec="elements-cli -regtest"` +
+ In Elements, blocks have to be signed by a quorum of the federation. However, just like in Bitcoin the conditions in regtest modes are not enforced, so you can simply create a block with `ec generate 1`. +
+3. Create a chain where we predetermine who is allowed to sign blocks. We start with creating a fresh keypair. + > ADDR=`ec getnewaddress` + > PUBKEY=`ec validateaddress $ADDR | jq -r '.pubkey'` + > PRIVKEY=`ec dumpprivkey $ADDR` +4. Create a 1-of-1 multisig script to use as a block requirement. + > SIGNBLOCKSCRIPT=`ec createmultisig 1 \[\"$PUBKEY\"\] | jq -r '.redeemScript'` +5. Stop the daemon and create a new chain using the blocksigner script + > ec stop + > rm -rf ~/.bitcoin/elementsregtest + > elementsd -regtest -daemon -signblockscript=$SIGNBLOCKSCRIPT + > ec importprivkey $PRIVKEY + > NEW_BLOCK=`ec getnewblockhex` + > BLOCKSIG=`ec signblock $NEW_BLOCK` +
+ If there were multiple blocksigners, you'd need to distribute `NEW_BLOCK`, collect signatures, then call `combineblocksigs`. We'll leave this as an excercise to the reader. +
+ > SIGNED_BLOCK=`ec combineblocksigs $NEW_BLOCK \[\"$BLOCKSIG\"\] | jq -r '.hex'` + * ensure that the output of combineblocksigs has "complete" true + > `ec getblockcount` + * check the current block count + > `ec submitblock $SIGNED_BLOCK` + > `ec getblockcount` + * check that the chain advanced by one block + +Block generation can be easily automated in a shell script. + +#### Congratulations! +Your chain is online and already accessible, just let other nodes connect to you: +``` +ec addnode +``` + +### Moving Bitcoin into your Sidechain +You might have figured out that while you are in `regtest` mode you own all +coins on the elements chain. Of course, in production you first have to use a +mechanism known as peg-in to move coins from the main chain to the elements +sidechain. Let's set up our own sidechain federation to handle the peg. + +1. Ensure that you have bitcoind 0.13.1 installed and elements as well as bitcoin are shut down. +2. Elements fully validates that peg-in transactions exists in Bitcoin. Therefore, it opens a RPC connection to bitcoind and checks that a particular block is in the chain and has the required confirmations. We need to ensure that the elements daemon is correctly talking to Bitcoin. + * The configuration of Elements is getting larger, so we best create a config file in a new data directory. + * `BETADATADIR=/tmp/elementsdatadir/` + * `mkdir $BETADATADIR` + * Put the following into $BETADATADIR/elements.conf + ``` + rpcuser=bitcoinrpc + rpcpassword=password + rpcport=8339 + daemon=1 + discover=0 + testnet=0 + regtest=1 + + mainchainrpchost=127.0.0.1 + mainchainrpcport=8338 + mainchainrpcuser=bitcoinrpc + mainchainrpcpassword=password + + validatepegin=1 + txindex=1 + ``` + * Now do the same for bitcoin + * `BITCOINDATADIR=/tmp/bitcoindatadir/` + * `mkdir $BITCOINDATADIR` + * put the following into $BITCOINDATADIR/bitcoin.conf + ``` + rpcuser=bitcoinrpc + rpcpassword=password + rpcport=8338 + daemon=1 + discover=0 + testnet=0 + regtest=1 + txindex=1 + ``` +* In the previous section we've used our own public key for the blocksigner script. We will use the same for the federation script. This is the script that owns the coins on the sidechain. +* Let's start bitcoin `bitcoind -datadir=$BITCOINDATADIR` and elements `elementsd -datadir=$BETADATADIR -signblockscript=$SIGNBLOCKSCRIPT -fedpegscript=$SIGNBLOCKSCRIPT` +* Let's update the elements-cli alias to use the new datadir + * `alias bc="elements-cli -datadir=$BETADATADIR"` + * `alias bitc="bitcoin-cli -datadir=$BITCOINDATADIR"` +* Create some coins on the main chain + * `bitc generate 101` +* We can't create a regular peg-in yet, because there are no WPV outputs in regtest mode. We first create them by `sendtomainchain `. Note that peg-outs don't work, because you have no pegoutwatcher running. +* Now you can perform the regular peg-in steps, by first calling `getpeginaddress` on elements then sending coins with bitcoin, then -- again on elements -- claiming coins with `claimpegin`. Ensure that both chains are mining all the time. diff --git a/source/sidechains/index.md b/source/sidechains/index.md index 59ec2e5..ad8e3be 100644 --- a/source/sidechains/index.md +++ b/source/sidechains/index.md @@ -26,7 +26,7 @@ edit: https://github.com/ElementsProject/elementsproject.github.io/edit/master/s # Featured -Sidechains with a working network can be listed here. +Sidechains with a working network can be listed here. Add Yours » ## Experimental Sidechains These sidechains are in development and testing, or are explicitly intended for non-production use. @@ -85,10 +85,10 @@ These sidechains are in development and testing, or are explicitly intended for ## Production Sidechains These sidechains are being used on the main Bitcoin network. -
-
-
- +
+
+
+

[Liquid](/sidechains/liquid)

diff --git a/themes/elements/layout/index.jade b/themes/elements/layout/index.jade index a2d80da..3313846 100644 --- a/themes/elements/layout/index.jade +++ b/themes/elements/layout/index.jade @@ -6,13 +6,13 @@ block masthead min-height: 700px; } - .ui.inverted.vertical.masthead.segment(style="background: url('/img/hero-image.png'); background-size: 100%;") + .ui.inverted.vertical.center.aligned.masthead.segment(style="background: url('/img/hero-image.png'); background-size: 100%;") .ui.container .ui.large.secondary.inverted.pointing.menu include partials/menu a.right.toc.item i.sidebar.icon - .ui.text.container + .ui.text.container(style="margin-top: -6em;") h1.ui.inverted.header The Elements Project h2 Extend Bitcoin with composable building blocks,
deployed to your very own sidechain. @@ -23,7 +23,7 @@ block masthead | Join the Community i.icon.right.chevron - a.ui.huge.primary.right.floated.button(href="/contributing/", style="margin-top: 1em;") + a.ui.huge.primary.button(href="/contributing/", style="margin-top: 2em; margin-bottom: -2em;") | Join the Community i.icon.right.chevron