From: Alekos Filini Date: Wed, 29 Apr 2020 12:42:27 +0000 (+0200) Subject: Initial commit X-Git-Url: http://internal-gitweb-vhost/script/%22https:/struct.CommandStringError.html?a=commitdiff_plain;h=718061d28441abae06dae60c9806df33876d12fa;p=bitcoindevkit.org Initial commit --- 718061d28441abae06dae60c9806df33876d12fa diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000000..69d9321068 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +/public + +*.swp diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000000..6433a7d0e7 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "themes/learn"] + path = themes/learn + url = https://github.com/matcornic/hugo-theme-learn.git diff --git a/archetypes/default.md b/archetypes/default.md new file mode 100644 index 0000000000..00e77bd79b --- /dev/null +++ b/archetypes/default.md @@ -0,0 +1,6 @@ +--- +title: "{{ replace .Name "-" " " | title }}" +date: {{ .Date }} +draft: true +--- + diff --git a/config.toml b/config.toml new file mode 100644 index 0000000000..f9b2445190 --- /dev/null +++ b/config.toml @@ -0,0 +1,33 @@ +baseURL = "https://magicalbitcoin.org/" +languageCode = "en-us" +title = "Magical Bitcoin" +theme = "learn" + +[outputs] +home = [ "HTML", "RSS", "JSON"] + +[params] +# Prefix URL to edit current page. Will display an "Edit this page" button on top right hand corner of every page. +# Useful to give opportunity to people to create merge request for your doc. +# See the config.toml file from this documentation site to have an example. +editURL = "https://github.com/MagicalBitcoin/docs/edit/master/content/" +# Author of the site, will be used in meta information +author = "Alekos Filini - @afilini" +# Description of the site, will be used in meta information +description = "The Magical Bitcoin project aims to build a collection of tools and libraries that are designed to be a solid foundation for Bitcoin wallets." +# A title for shortcuts in menu is set by default. Set this to true to disable it. +# disableShortcutsTitle = false +# Hide breadcrumbs in the header and only show the current page title +disableBreadcrumb = true +# Hide Next and Previous page buttons normally displayed full height beside content +disableNextPrev = false +# Order sections in menu by "weight" or "title". Default to "weight" +ordersectionsby = "weight" +# Change default color scheme with a variant one. Can be "red", "blue", "green". +themeVariant = "blue" +# Provide a list of custom css files to load relative from the `static/` folder in the site root. +custom_css = ["css/style.css", "css/jsonview.css"] + +# render raw html +[markup.goldmark.renderer] +unsafe= true diff --git a/content/_index.md b/content/_index.md new file mode 100644 index 0000000000..a61a1c0021 --- /dev/null +++ b/content/_index.md @@ -0,0 +1,28 @@ +--- +title: "Home" +date: 2020-04-28T09:46:18+02:00 +draft: false +--- + +# 🧙 Magical Bitcoin 🧙 + +The Magical Bitcoin project aims to build a collection of tools and libraries that are designed to be a solid foundation for Bitcoin wallets, along with a fully working *reference implementation* wallet. +All of its components are designed to be lightweight and modular so that they can be adapted for virtually any use-case: from the single-sig mobile wallet to the multi-billion-dollar cold storage vault. + +The main long-term goal is to concentrate the development efforts of multiple people and companies into one open source and very well reviewed project, instead of dispersing them over multiple closed/semi-closed or +poorly designed projects. + +{{% notice info %}} +Keep in mind that this project is still in a very early phase of development. The APIs and the general architecture shouldn't be considered stable yet. At the moment most of the code is concentrated in the +[main repo](https://github.com/MagicalBitcoin/magical-bitcoin-wallet) and is slowly being refactored and taken out into separate, independent modules. +{{% /notice %}} + +## Descriptors + +The name of the project refers to the fact that when its components are built into a wallet, it can "almost magically" support very complex spending policies, without having to individually translate them into code. It may sound disappointing, but there isn't, in fact, +any real magic in this wallet: the generalization is achieved thanks to *descriptors*, that are now slowly starting to see adoption in a few other Bitcoin projects as well. + +The author of this project strongly believes descriptors will be a big part of the future generation of Bitcoin wallets, since they provide a very flexible scripting language that can also be extended as the +technology and tooling on Bitcoin evolve and change (Schnorr signatures, Taproot, etc). + +To learn more, check the specific [Descriptors section](/descriptors). diff --git a/content/descriptors/_index.md b/content/descriptors/_index.md new file mode 100644 index 0000000000..d92f5ef694 --- /dev/null +++ b/content/descriptors/_index.md @@ -0,0 +1,36 @@ +--- +title: "Descriptors" +date: 2020-04-28T14:40:12+02:00 +draft: false +weight: 5 +pre: ' ' +--- + +Magical Bitcoin extends the capabilities of [rust-miniscript](https://github.com/apoelstra/rust-miniscript) by introducing the concept of an *ExtendedDescriptor*: it represents a descriptor that contains one or more "derivable keys" like `xpubs` or `xprvs` +and can be "derived" to a normal Descriptor by deriving every single one of its keys. It is currently called "StringDescriptor" in the code, because it's implemented as a wrapped `miniscript::Descriptor`. + +ExtendedDescriptors are derived using a single index instead of a full derivation path: this is because normally most of the path is fixed and can be represented right after the xpub/xprv itself, and only the +final index changes for each address. This is what's normally called a *DescriptorExtendedKey* in codebase, and it's the represented with a similar syntax to Bitcoin Core's, such as: + +``` +[d34db33f/44'/0'/0']xpub6ERApfZwUNrhL.......rBGRjaDMzQLcgJvLJuZZvRcEL/0/* +``` + +For more details regarding this syntax, see [this document](https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md). On top of this, ExtendedDescriptors also support other formats for public and private keys, +like WIF and raw hexadecimal representation. + +Speaking of syntax, the general descriptor operators syntax is a bit different from what Core uses: the `multi()`/`sortedmulti()` are not available, and they are replaced by `thresh_m()`. Also the `combo()` operator is not +available, and doesn't currently have any replacement. For more informations, see [this page](http://bitcoin.sipa.be/miniscript). + +Some examples of valid descriptors are: + +
+ +| Spending Policy | Descriptor | Address 0 | Address 1 | +| --------------- | ---------- | --------- | --------- | +| Static P2PKH | `pkh(cSQPHDBwXGjVzWRqAHm6zfvQhaTuj1f2bFH58h55ghbjtFwvmeXR)` | mrkwtj5xpYQjHeJe5wsweNjVeTKkvR5fCr | mrkwtj5xpYQjHeJe5wsweNjVeTKkvR5fCr | +| Static P2PKH, watch-only | `pkh(02e96fe52ef0e22d2f131dd425ce1893073a3c6ad20e8cac36726393dfb4856a4c)` | mrkwtj5xpYQjHeJe5wsweNjVeTKkvR5fCr | mrkwtj5xpYQjHeJe5wsweNjVeTKkvR5fCr | +| P2WSH 2-of-2 with one private key | `wsh(thresh_m(2,tprv8ZgxMBicQKsPePmENhT9N9yiSfTtDoC1f39P7nNmgEyCB6Nm4Qiv1muq4CykB9jtnQg2VitBrWh8PJU8LHzoGMHTrS2VKBSgAz7Ssjf9S3P/0/*,tpubDBYDcH8P2PedrEN3HxWYJJJMZEdgnrqMsjeKpPNzwe7jmGwk5M3HRdSf5vudAXwrJPfUsfvUPFooKWmz79Lh111U51RNotagXiGNeJe3i6t/1/*))` | tb1qqsat6c82fvdy73rfzye8f7nwxcz3xny7t56azl73g95mt3tmzvgs9a8vjs | tb1q7sgx6gscgtau57jduend6a8l445ahpk3dt3u5zu58rx5qm27lhkqgfdjdr | +| P2WSH-P2SH one key + 10 days timelock | `sh(wsh(and_v(vc:pk_h(tprv8ZgxMBicQKsPePmENhT9N9yiSfTtDoC1f39P7nNmgEyCB6Nm4Qiv1muq4CykB9jtnQg2VitBrWh8PJU8LHzoGMHTrS2VKBSgAz7Ssjf9S3P/0/*),older(1440))))` | 2Mtk2nyS98MCi2P7TkoBGLaJviBy956XxB1 | 2MuEStKzYhqb5HCFgHz9153tZsL5sVqV5xC | + +
diff --git a/content/repl/_index.md b/content/repl/_index.md new file mode 100644 index 0000000000..07ae230c7d --- /dev/null +++ b/content/repl/_index.md @@ -0,0 +1,12 @@ ++++ +title = "REPL" +date = 2020-04-28T17:03:00+02:00 +weight = 1 +chapter = true +pre = ' ' ++++ + +# REPL + +The [magical-bitcoin-wallet](https://github.com/magicalbitcoin/magical-bitcoin-wallet) repo has a very minimalistic interactive shell that acts both as a reference implementation of a wallet and a tool to +quickly experiment with descriptors and transactions. diff --git a/content/repl/compiler.md b/content/repl/compiler.md new file mode 100644 index 0000000000..2a9633fa39 --- /dev/null +++ b/content/repl/compiler.md @@ -0,0 +1,151 @@ +--- +title: "Compiler" +date: 2020-04-29T12:06:50+02:00 +draft: false +weight: 5 +pre: "5. " +--- + +## Introduction + +If you want to play around with more complicated spending policies, you'll start to find it harder and harder to manually create the descriptors. This is where the miniscript compiler comes in! `magical-bitcoin-wallet` +includes a very simple compiler that can produce a descriptor given a spending policy. The syntax used to encode the spending policiy is very well described [in this page](http://bitcoin.sipa.be/miniscript/), +specifically in the "Policy to Miniscript compiler". The compiler included in Magical Bitcoin does basically the same job, but produces a descriptors for `rust-miniscript` that has some minor differences from +the ones made by the C++ implementation used in that website. + +## Installation + +To install the miniscript compiler run the following command: + +```bash +cargo install --git https://github.com/magicalbitcoin/magical-bitcoin-wallet --features="compiler" --example miniscriptc +``` + +Once the command is done, you should have a `miniscriptc` command available. You can check if that's the case by running `miniscriptc --help`. + +## Usage + +In this case the interface is very simple: it accepts two arguments called "POLICY" and "TYPE", in this order. The first one, as the name implies, sets the spending policy to compile. The latter defines the type +of address that should be used to incapsulate the produced script, like a P2SH, P2WSH, etc. + +Optionally, the `--parsed_policy` flag can be enabled and it will make the compiler print the JSON "human-readable" version of the spending policy, as described in the [`policies subcommand`](/repl/interface/#policies) of the CLI. + +The `--network` flag can be used to change the network encoding of the address shown. + +{{% notice tip %}} +Keep in mind that since the compiler loads and interprets the descriptor, all the public keys specified in the policy must be valid public keys. This differs from the web tool linked above that also accepts +placeholders too. As described in the previous sections of this guide, the keys can be either `xpub`/`xprv` with or without metadata and a derivation path, WIF keys or raw hex public keys. +{{% /notice %}} + +## Example + +Let's take this policy for example: + +```bash +miniscriptc --parsed_policy and(pk(cSQPHDBwXGjVzWRqAHm6zfvQhaTuj1f2bFH58h55ghbjtFwvmeXR),or(50@pk(02e96fe52ef0e22d2f131dd425ce1893073a3c6ad20e8cac36726393dfb4856a4c),older(1000)))) sh-wsh +``` + +The compiler should print something like: + +```text +[2020-04-29T10:42:05Z INFO miniscriptc] Compiling policy: and(pk(cSQPHDBwXGjVzWRqAHm6zfvQhaTuj1f2bFH58h55ghbjtFwvmeXR),or(50@pk(02e96fe52ef0e22d2f131dd425ce1893073a3c6ad20e8cac36726393dfb4856a4c),older(1000))) +[2020-04-29T10:42:05Z INFO miniscriptc] ... Descriptor: sh(wsh(and_v(or_c(c:pk(02e96fe52ef0e22d2f131dd425ce1893073a3c6ad20e8cac36726393dfb4856a4c),v:older(1000)),c:pk(cSQPHDBwXGjVzWRqAHm6zfvQhaTuj1f2bFH58h55ghbjtFwvmeXR)))) +[2020-04-29T10:42:05Z INFO miniscriptc] ... First address: 2MsqrJuZewY3o3ADAy1Uhi5vsBqTANjH3Cf +``` + +JSON policy: + +{{% json %}} +{ + "type":"THRESH", + "items":[ + { + "type":"THRESH", + "items":[ + { + "type":"SIGNATURE", + "pubkey":"02e96fe52ef0e22d2f131dd425ce1893073a3c6ad20e8cac36726393dfb4856a4c", + "satisfaction":{ + "type":"NONE" + }, + "contribution":{ + "type":"NONE" + } + }, + { + "type":"RELATIVETIMELOCK", + "value":1000, + "satisfaction":{ + "type":"NONE" + }, + "contribution":{ + "type":"COMPLETE", + "condition":{ + "csv":1000 + } + } + } + ], + "threshold":1, + "satisfaction":{ + "type":"NONE" + }, + "contribution":{ + "type":"PARTIALCOMPLETE", + "n":2, + "m":1, + "items":[ + 1 + ], + "conditions":{ + "[1]":[ + { + "csv":1000 + } + ] + } + } + }, + { + "type":"SIGNATURE", + "pubkey":"02e96fe52ef0e22d2f131dd425ce1893073a3c6ad20e8cac36726393dfb4856a4c", + "satisfaction":{ + "type":"NONE" + }, + "contribution":{ + "type":"COMPLETE", + "condition":{ + + } + } + } + ], + "threshold":2, + "satisfaction":{ + "type":"NONE" + }, + "contribution":{ + "type":"PARTIALCOMPLETE", + "n":2, + "m":2, + "items":[ + 0, + 1 + ], + "conditions":{ + "[0, 1]":[ + { + "csv":1000 + } + ] + } + } +} +{{% /json %}} + +## Troubleshooting + +#### Nothing is printed + +This might mean that you have a `RUST_LOG` variable set to a value that suppresses the compiler's log. You can try adding `miniscriptc=info` to your `RUST_LOG` value and see if that works, or open a new clean +shell. diff --git a/content/repl/concept.md b/content/repl/concept.md new file mode 100644 index 0000000000..d57f541789 --- /dev/null +++ b/content/repl/concept.md @@ -0,0 +1,26 @@ +--- +title: "Concept" +date: 2020-04-28T17:38:20+02:00 +draft: false +weight: 2 +pre: "2. " +--- + +Now, in order to better grasp some of the design choiches made by Magical Bitcoin, it's important to understand the main concept driving the development of this project, and the goal that it's trying to +achieve. + +Magical Bitcoin is aiming first of all to be a **set of libraries and tools**, all meant to be very reusable and adaptable. Developers working on their own wallets or other projects that are trying to integrate +Bitcoin can pick the tools they need and piece them together to prototype and quickly ship a working product. This means that the REPL that we've just installed is designed to be a **very thin layer** over the +APIs exposed by the various components of the library, **not a full, end-user-ready Bitcoin wallet**. + +This concept leads to a few design choices that are arguably very bad for the "UX" of this wallet, but that allow developers to work more directly with the underlying library. For instance: + +* Magical Bitcoin has an internal database that's used to store data about received transactions, spendable UTXOs, etc. This database is stored by default in your home folder, in `~/.magical-bitcoin`. The database + **will never** contain any data that can't be recreated purely by looking at the blockchain. Keys, descriptors, Electrum endpoints **are not stored in there**. This explains why you'll have to specify them every + time in the command line. It can be seen more like a *cache* and can be safely deleted without risking funds. +* Magical Bitcoin doesn't automatically "monitor" the blockchain, instead there's a `sync` command that has to be called by the user. +* When you create a transaction and then sign it, it's not automatically broadcasted to the network. There's a `broadcast` command that does this. Moreover, the command doesn't accept a normal Bitcoin raw transaction, + but instead a *PSBT*. That's because internally transactions are always moved as PSBTs, and again, the `broadcast` command is just a very thin wrapper over the raw library call. + +There are probably more of these examples, but hopefully by this point you'll have more or less understood the gist of it. If you are not a developer, some parts of this are gonna feel weird, inefficient, hard +to understand, and that's absolutely normal. Just try to survive through the pain and you'll be rewarded! diff --git a/content/repl/installation.md b/content/repl/installation.md new file mode 100644 index 0000000000..8ab8e064a1 --- /dev/null +++ b/content/repl/installation.md @@ -0,0 +1,63 @@ +--- +title: "Installation" +date: 2020-04-28T17:11:29+02:00 +draft: false +weight: 1 +pre: "1. " +--- + +## Requirements + +The only requirement is a Linux/macOS system with a fairly recent Rust toolchain installed. Since Linux distros tend to lack behind with updates, the quickest way to install the Rust compiler and Cargo is +[rustup.rs](https://rustup.rs/). You can head there and follow their instructions, after which you can test if everything went fine by running `cargo version`, which should print something like: + +``` +cargo 1.42.0 (86334295e 2020-01-31) +``` + +If you really don't wanna pipe the output of `curl` into `sh`, you can also try using a [Docker image](https://hub.docker.com/_/rust) and working inside of it, but that's meant for more advanced +users and won't be covered in this guide. + +## Installing Magical Bitcoin + +Once Cargo is installed, you can proceed to install the interactive Magical Bitcoin shell directly from the GitHub repository, by running: + +```bash +cargo install --git https://github.com/magicalbitcoin/magical-bitcoin-wallet --example magic +``` + +This command will probably take a while to finish, since it will fetch and compile all the dependencies and the `magical-bitcoin-wallet` itself. Once it's done, you can check if everything went fine +by running `magic --help` which should print something like this: + +```text +Magical Bitcoin Wallet 0.1.0 +Riccardo Casatta :Alekos Filini +A modern, lightweight, descriptor-based wallet + +USAGE: + magic [FLAGS] [OPTIONS] --descriptor [SUBCOMMAND] + +FLAGS: + -h, --help Prints help information + -v Sets the level of verbosity + -V, --version Prints version information + +OPTIONS: + -c, --change_descriptor Sets the descriptor to use for internal addresses + -d, --descriptor Sets the descriptor to use for the external addresses + -n, --network Sets the network [default: testnet] [possible values: testnet, regtest] + -s, --server Sets the Electrum server to use [default: tn.not.fyi:55001] + -w, --wallet Selects the wallet to use [default: main] + +SUBCOMMANDS: + broadcast Extracts the finalized transaction from a PSBT and broadcasts it to the network + create_tx Creates a new unsigned tranasaction + get_balance Returns the current wallet balance + get_new_address Generates a new external address + help Prints this message or the help of the given subcommand(s) + list_unspent Lists the available spendable UTXOs + policies Returns the available spending policies for the descriptor + repl Opens an interactive shell + sign Signs and tries to finalize a PSBT + sync Syncs with the chosen Electrum server +``` diff --git a/content/repl/interface.md b/content/repl/interface.md new file mode 100644 index 0000000000..90acc4f4fa --- /dev/null +++ b/content/repl/interface.md @@ -0,0 +1,428 @@ +--- +title: "Interface" +date: 2020-04-28T18:20:28+02:00 +draft: false +weight: 3 +pre: "3. " +--- + +Remember the `magic --help` command you ran before? Let's analyze its output here to figure out the interface: + +## Flags + +```text +FLAGS: + -h, --help Prints help information + -v Sets the level of verbosity + -V, --version Prints version information +``` + +These are the optional flags that can be set with every command. The `-h` flag prints the help message, the `-V` flag only prints the version and the `-v` is actually ignored at the moment. + +### Verbosity + +If you want to increase the verbosity of the output, you should use the `RUST_LOG` environment variable. You can set it like so to see a lot more of what's going on behind the scenes, before running the `magic` +command. You only have to do this once when you open a new shell, after that you can run the `magic` command multiple times. + +```bash +export RUST_LOG="magical_bitcoin_wallet=debug" +``` + +## Options + +```text +OPTIONS: + -c, --change_descriptor Sets the descriptor to use for internal addresses + -d, --descriptor Sets the descriptor to use for the external addresses + -n, --network Sets the network [default: testnet] [possible values: testnet, regtest] + -s, --server Sets the Electrum server to use [default: tn.not.fyi:55001] + -w, --wallet Selects the wallet to use [default: main] +``` + +These are the global options that can be set. They are pretty much like the flags, but they also take a value. The only **required** one is the `--descriptor` or `-d` flag, since every wallet **must have an +associated descriptor**. + +The `--change-descriptor` flag can be used to set a different descriptor for the change addresses, sometimes called "internal" addresses in Bitcoin Core. Unfortunately there isn't +[really consensus](https://freenode.irclog.whitequark.org/bitcoin-wizards/2020-01-25#26222504;) on a nice way to encode informations about the change derivation inside the standard descriptor, so we are +stuck with having two separate ones. Keep in mind though, that even if you don't specify a change descriptor, you'll still be able to create transactions - the change address will simply be generated from the +standard descriptor. + +The `--network` flag can be used to change the network. Right now only `testnet` and `regtest` are supported since the code is very much not production-ready yet. + +The `--server` flag can be used to select the Electrum server to use. By default it's connecting to a random `testnet` server that has been found online, but sometimes it has proven to be kinda unreliable. +You can also try with `kirsche.emzy.de:50001` or find other servers [here](https://1209k.com/bitcoin-eye/ele.php?chain=tbtc) and see if you have more luck with those. Right now **only tcp, non-Tor** servers are supported. + +The `--wallet` flag can be used to select which wallet to use, if you have more than one of them. If you get a `ChecksumMismatch` error when you make some changes to your descriptor, it's because it doesn't +match anymore the one you've used to initialize the cache. One solution could be to switch to a new wallet name, or delete the cache directory at `~/.magical-bitcoin` and start from scratch. + +## Subcommands + +```text +SUBCOMMANDS: + broadcast Extracts the finalized transaction from a PSBT and broadcasts it to the network + create_tx Creates a new unsigned tranasaction + get_balance Returns the current wallet balance + get_new_address Generates a new external address + list_unspent Lists the available spendable UTXOs + policies Returns the available spending policies for the descriptor + repl Opens an interactive shell + sign Signs and tries to finalize a PSBT + sync Syncs with the chosen Electrum server +``` + +These are the main "functions" of the wallet. Most of them are pretty self explanatory, but we'll go over them quickly anyways. You can get more details about every single command by running `magic --help`. + +### broadcast + +```text +OPTIONS: + --psbt Sets the PSBT to broadcast +``` + +Broadcasts a transaction. The transaction has to be in PSBT format and has to be "finalizable" (i.e. it should contain enough partial signatures to construct a finalized valid signature). + +### create\_tx + +```text +FLAGS: + -a, --send_all Sends all the funds (or all the selected utxos). Requires only one addressees of value 0 + +OPTIONS: + -f, --fee_rate Fee rate to use in sat/vbyte + --policy Selects which policy will be used to satisfy the descriptor + --to ... Adds an addressee to the transaction + --unspendable ... Marks an utxo as unspendable + --utxos ... Selects which utxos *must* be spent +``` + +Creates a new unsigned PSBT. The flags allow to set a custom fee rate (the default is 1.0 sat/vbyte) with `--fee_rate` or `-f`, the list of UTXOs that should be considered unspendable with `--unspendable` (this +option can be specified multiple times) and a list of UTXOs that must be spent with `--utxos` (again, this option can also be specified multiple times). + +The `--to` option sets the receiver address of the transaction, and should contain the address and amount in Satoshi separated by a colon, like: `--to --to 2NErbQPsooXRatRJdrXDm9wKR2fRiZDT9wL:50000`. This option +can also be specified multiple times to send to multiple addresses at once. + +The `--send_all` flag can be used to send the value of all the spendable UTXOs to a single address, without creating a change output. If this flag is set, there must be only one `--to` address, and its value will +be ignored (it can be set to 0). + +The `--policy` option is an advanced flag that can be used to select the spending policy that the sender intends to satisfy in this transaction. It's normally not required if there's no ambiguity, but sometimes +with complex descriptor it has to be specified, or you'll get a `SpendingPolicyRequired` error. This flag should be set to an array of the list of child indexes that should be taken at each step when traversing the spending +policies tree from the root, at least until there are no more ambiguities. This is probably better explained with an example: + +Let's assume our descriptor is: `thresh(2,c:pk(A),sj:and_v(vc:pk(B),n:older(6)),sjn:and_v(vc:pk(C),after(630000)))`. There are three conditions and we need to satisfy two of them to be able to spend. The conditions are: + +1. Sign with the key corresponding to `pk(A)` +2. Sign with the key corresponding to `pk(B)` AND wait 6 blocks +2. Sign with the key corresponding to `pk(C)` AND wait that block 630,000 is reached + +So if we write down all the possible outcomes when we combine them, we get: + +1. Sign with `pk(A)` + `pk(B)` + wait 6 blocks +2. Sign with `pk(A)` + `pk(C)` + wait block 630,000 +3. Sign with `pk(B)` + `pk(C)` + wait 6 blocks + wait block 630,000 + +* If we choose option #1, the final transaction will need to have the `nSequence` of its inputs to a value greather than or equal to 6, but the `nLockTime` can stay at 0. +* If we choose option #2, the final transaction will need to have its `nLockTime` set to a value greater than or equal to 630,000, but the `nSequence` can be set to a final value. +* If we choose option #3, both the `nSequence` and `nLockTime` must be set. + +The wallet can't choose by itself which one of these combination to use, so the user has to provide this information with the `--policy` flag. Now, let's draw the condition tree to understand better how the chosen +policy is represented: + +{{}} +graph TD; + subgraph "" + R["Root"] --> A["pk(A)"] + R["Root"] --> B + B --> B_0["pk(B)"] + B --> B_1["older(6)"] + end + C --> C_0["pk(C)"] + C --> C_1["after(630,000)"] + R["Root"] --> C +{{< /mermaid >}} + +Let's imagine that we are walking down from the root, and we want to use option #1. So we will have to select `pk(A)` + the whole `B` node. Since the order is always mainteined, we can refer to them with their +indexes, in this case they are children #0 and #1 of the root. So our final policy will be: `--policy [[0, 1]]`, which means "at the first step from the root, pick items #0 and #1". + +### get\_balance + +This subcommand has no extra flags, and simply returns the available balance in Satoshis. This command **must be called after [`sync`](#sync)**, since it only looks into the local cache to determine the list of UTXOs. + +### get\_new\_address + +This subcommand has no extra flags and returns a new address. It internally increments the derivation index and saves it in the database. + +### list\_unspent + +This subcommand has no extra flags and returns the list of available UTXOs and their value in Satoshi. Just like [`get_balance`](#get_balance) it **must be called after [`sync`](#sync)**, since it only operates +on the internal cache. + +### policies + +This subcommand has no extra flags and returns the spending policies encoded by the descriptor in a more human-readable format. As an example, running the `policies` command on the descriptor shown earlier for the +in the explanation of the [`create_tx`](#create_tx) command, it will return this: + +{{% json %}} +{ + "type":"THRESH", + "items":[ + { + "type":"SIGNATURE", + "pubkey":"...", + "satisfaction":{ + "type":"NONE" + }, + "contribution":{ + "type":"COMPLETE", + "condition":{ + + } + } + }, + { + "type":"THRESH", + "items":[ + { + "type":"SIGNATURE", + "pubkey":"...", + "satisfaction":{ + "type":"NONE" + }, + "contribution":{ + "type":"COMPLETE", + "condition":{ + + } + } + }, + { + "type":"RELATIVETIMELOCK", + "value":6, + "satisfaction":{ + "type":"NONE" + }, + "contribution":{ + "type":"COMPLETE", + "condition":{ + "csv":6 + } + } + } + ], + "threshold":2, + "satisfaction":{ + "type":"NONE" + }, + "contribution":{ + "type":"PARTIALCOMPLETE", + "n":2, + "m":2, + "items":[ + 0, + 1 + ], + "conditions":{ + "[0, 1]":[ + { + "csv":6 + } + ] + } + } + }, + { + "type":"THRESH", + "items":[ + { + "type":"SIGNATURE", + "pubkey":"...", + "satisfaction":{ + "type":"NONE" + }, + "contribution":{ + "type":"COMPLETE", + "condition":{ + + } + } + }, + { + "type":"ABSOLUTETIMELOCK", + "value":630000, + "satisfaction":{ + "type":"NONE" + }, + "contribution":{ + "type":"COMPLETE", + "condition":{ + "timelock":630000 + } + } + } + ], + "threshold":2, + "satisfaction":{ + "type":"NONE" + }, + "contribution":{ + "type":"PARTIALCOMPLETE", + "n":2, + "m":2, + "items":[ + 0, + 1 + ], + "conditions":{ + "[0, 1]":[ + { + "timelock":630000 + } + ] + } + } + } + ], + "threshold":2, + "satisfaction":{ + "type":"NONE" + }, + "contribution":{ + "type":"PARTIALCOMPLETE", + "n":3, + "m":2, + "items":[ + 0, + 1, + 2 + ], + "conditions":{ + "[0, 1]":[ + { + "csv":6 + } + ], + "[0, 2]":[ + { + "timelock":630000 + } + ], + "[1, 2]":[ + { + "csv":6, + "timelock":630000 + } + ] + } + } +} +{{% /json %}} + +This is a tree-like recursive structure, so it tends to get huge as more and more pieces are added, but it's in fact fairly simple. Let's analyze a simple node of the tree: + +```json +{ + "type":"SIGNATURE", + "pubkey":"...", + "satisfaction":{ + "type":"NONE" + }, + "contribution":{ + "type":"COMPLETE", + "condition":{} + } +} +``` + +* `type`, as the name implies, represents the type of node. It defines what should be provided to satisfy that particular node. Generally some other data are provided to give meaning to + the type itself (like the `pubkey` field here in the example). There are basically two families of types: some of them can only be used as leaves, while some other can only be used as intermediate nodes. + + Possible leaf nodes are: + - `SIGNATURE`, requires a signature made with the specified key. Has a `pubkey` if it's a single key, a `fingerprint` if the key is an xpub, or a `pubkey_hash` if the full public key is not present in the descriptor. + - `SIGNATUREKEY`, requires a signature plus the raw public key. Again, it can have a `pubkey`, `fingerprint` or `pubkey_hash`. + - `SHA256PREIMAGE`, requires the preimage of a given `hash`. + - `HASH256PREIMAGE`, requires the preimage of a given `hash`. + - `RIPEMD160PREIMAGE`, requires the preimage of a given `hash`. + - `HASH160PREIMAGE`, requires the preimage of a given `hash`. + - `ABSOLUTETIMELOCK`, doesn't technically require anything to be satisfied, just waiting for the timelock to expire. Has a `value` field with the raw value of the timelock (can be both in blocks or time-based). + - `RELATIVETIMELOCK`, again only requires waiting for the timelock to expire. Has a `value` like `ABSOLUTETIMELOCK`. + + Possible non-leaf nodes are: + - `THRESH`, defines a threshold of policies that has to be met to satisfy the node. Has an `items` field, which is a list of policies to satisfy and a `threshold` field that defines the threshold. + - `MULTISIG`, Similar to `THRESH`, has a `keys` field, which is a list of keys represented again as either `pubkey`, `fingerprint` or `pubkey_hash` and a `threshold` field. + +* `satisfaction` is currently not implemented and will be used to provide PSBT introspection, like understanding whether or not a node is already satisfied and to which extent in a PSBT. +* `contribution` represents if so and how much, the provided descriptor can contribute to the node. + + The possible types are: + - `NONE`, which means that the descriptor cannot contribute. + - `COMPLETE`, which means that the descriptor by itself is enough to completely satisfy the node. It also adds a `condition` field which represent any potential extra condition that has to be met to + consider the node complete. An example are the timelock nodes, that are always complete *but* they have an extra `csv` or `timelock` condition. + - `PARTIAL`, which means that the descriptor can partially satisfy the descriptor. This adds a `m`, `n`, `items` that respectively represent the threshold, the number of available items to satisfy and the items + that the provided descriptor can satisfy. Also adds a `conditions` field which is an integer to list of conditions map. The key is the child index and the map are all the possibile extra conditions that + have to be satisfied if that node is used in the threshold. For instance, if you have a threshold of a SIGNATURE and a RELATIVETIMELOCK, in this order, the `conditions` field will be `1 ⇒ csv(x)`, + because the item at index 1 needs the extra csv condition. + - `PARTIALCOMPLETE`, which is basically a `PARTIAL` with the size of `items` >= `m`. It's treated as a separate entity to make the code a bit more clean and easier to implement. Like `PARTIAL`, it also has + a `m`, `n`, `items` fields but the `conditions field` is a bit different: it's a list of integers to list of conditions map. The key represents the combination that can be used to satisfy the threshold, + and the value contains all the possible conditions that also have to be satisfied. For instance, if you have a 2-of-2 threshold of a TIMELOCK and a RELATIVETIMELOCK, the `conditions` field will be `[0, 1] ⇒ + csv(x) + timelock(y)`, because if the combination of items 0 and 1 is picked, both of their conditions will have to be meet too. + +While the structure contains all of the intermediate nodes too, the root node is the most important one because defines how the descriptor can contribute to spend outputs sent to its addresses. + +For instance, looking at the root node of the previous example (with the internal `items` omitted) from a descriptor that has all the three private keys for keys A, B and C, we can clearly see that it can satisfy +the descriptor (type = `PARTIALCOMPLETE`) and the three options are `[0, 1] ⇒ csv(6)` (Option #1), `[0, 2] ⇒ timelock(630,000)` (Option #2) or `[1, 2] ⇒ csv(6) + timelock(630,000)` (Option #3). + +```json +{ + "type":"THRESH", + "items":[], + "threshold":2, + "satisfaction":{ + "type":"NONE" + }, + "contribution":{ + "type":"PARTIALCOMPLETE", + "n":3, + "m":2, + "items":[ + 0, + 1, + 2 + ], + "conditions":{ + "[0, 1]":[ + { + "csv":6 + } + ], + "[0, 2]":[ + { + "timelock":630000 + } + ], + "[1, 2]":[ + { + "csv":6, + "timelock":630000 + } + ] + } + } +} +``` + +### `repl` + +This subcommand has no extra flags and launches an interactive shell session. + +### `sign` + +```text +OPTIONS: + --psbt Sets the PSBT to sign +``` + +Adds to the PSBT all the signatures it can produce with the secrets embedded in the descriptor (xprv or WIF keys). Returns the signed PSBT and, if there are enough item to satisfy the script, also the extracted raw +Bitcoin transaction. + +### `sync` + +This subcommand has no extra flags. It connects to the chosen Electrum server and synchronizes the list of transactions received and available UTXOs. diff --git a/content/repl/regtest.md b/content/repl/regtest.md new file mode 100644 index 0000000000..1fd756ca89 --- /dev/null +++ b/content/repl/regtest.md @@ -0,0 +1,34 @@ +--- +title: "Regtest" +date: 2020-04-29T00:19:34+02:00 +draft: false +weight: 4 +pre: "4. " +--- + +Running the REPL in regtest requires having a local Electrum server set-up. There are two main implementations, [`electrs`](https://github.com/romanz/electrs) in Rust and [`ElectrumX`](https://github.com/kyuupichan/electrumx) in Python. Since the Rust toolchain is already required to +use Magical, this page will focus mostly on the former. + +Electrs can be installed by running: + +```bash +cargo install --git https://github.com/romanz/electrs --bin electrs +``` + +Just like before, this command will probably take a while to finish. + +Once it's done, assuming you have a regtest bitcoind running in background, you can launch a new terminal and run the following command to actually start electrs: + +```bash +electrs -vv --timestamp --db-dir /tmp/electrs-db --electrum-rpc-addr="127.0.0.1:50001" --network=regtest --cookie-file=$HOME/.bitcoin/regtest/.cookie +``` + +on macOS you should change the cookie-file to `$HOME/Library/Application Support/Bitcoin/regtest/.cookie`. + +This will start the Electrum server on port 50001. You can then add the `-n regtest -s localhost:50001` the `magic` commands to switch to the local regtest. + +## Troubleshooting + +#### Stuck with "*wait until bitcoind is synced (i.e. initialblockdownload = false)*" + +Just generate a few blocks with `bitcoin-cli generatetoaddress 1
` diff --git a/layouts/partials/custom-footer.html b/layouts/partials/custom-footer.html new file mode 100644 index 0000000000..15a980ea92 --- /dev/null +++ b/layouts/partials/custom-footer.html @@ -0,0 +1,2 @@ + + diff --git a/layouts/partials/favicon.html b/layouts/partials/favicon.html new file mode 100644 index 0000000000..1eccb39c15 --- /dev/null +++ b/layouts/partials/favicon.html @@ -0,0 +1,7 @@ + + + + + + + diff --git a/layouts/partials/logo.html b/layouts/partials/logo.html new file mode 100644 index 0000000000..814ef465fb --- /dev/null +++ b/layouts/partials/logo.html @@ -0,0 +1,3 @@ + diff --git a/layouts/partials/menu-footer.html b/layouts/partials/menu-footer.html new file mode 100644 index 0000000000..d5a655cea3 --- /dev/null +++ b/layouts/partials/menu-footer.html @@ -0,0 +1,10 @@ + + +
+ + Watch + Star + Fork +
+ +
Built with Hugo
diff --git a/layouts/shortcodes/json.html b/layouts/shortcodes/json.html new file mode 100644 index 0000000000..62d3bdb167 --- /dev/null +++ b/layouts/shortcodes/json.html @@ -0,0 +1,2 @@ +{{ $_hugo_config := `{ "version": 1 }` }} +
diff --git a/static/css/jsonview.css b/static/css/jsonview.css new file mode 100644 index 0000000000..72419b32d1 --- /dev/null +++ b/static/css/jsonview.css @@ -0,0 +1,88 @@ +.json { + padding: 16px; + background-color: #272822; + color: #FFF; + font-family: "Consolas", menlo, monospace; +} + +.line { + margin: 4px 0; + display: flex; + justify-content: flex-start; +} + +.caret-icon { + width: 28px; + text-align: center; + cursor: pointer; +} + +.json .caret-icon > i { + border: 0; +} + +.empty-icon { + width: 20px; +} + +.json-type { + margin-right: 4px; + margin-left: 4px; +} + +.json-key { + color: #EEE; + margin-right: 4px; + margin-left: 4px; +} + +.json-index { + margin-right: 4px; + margin-left: 4px; +} + +.json-separator { + +} + +.json-value { + margin-left: 8px; +} + +.json-number { + color: #f9ae58; +} + +.json-boolean { + color: #ec5f66; +} + +.json-string { + color: #86b25c; +} + +.json-size { + margin-right: 4px; + margin-left: 4px; +} + +.hide { + display: none; +} + +.json .fas { + display: inline-block; + width: 0; + height: 0; + border-style: solid; +} + +.json .fa-caret-down { + border-width: 6px 5px 0 5px; + border-color: #808080 transparent +} + +.json .fa-caret-right { + border-width: 5px 0 5px 6px; + border-color: transparent transparent transparent #808080; +} diff --git a/static/css/style.css b/static/css/style.css new file mode 100644 index 0000000000..9f9f18e732 --- /dev/null +++ b/static/css/style.css @@ -0,0 +1,20 @@ +#descriptor-examples-table { +} + +#descriptor-examples-table code, #descriptor-examples-table td:not(:first-child) { + overflow-x: auto; + white-space: pre-wrap; + white-space: -moz-pre-wrap; + white-space: -pre-wrap; + white-space: -o-pre-wrap; + word-wrap: break-word; + overflow-wrap: anywhere; +} + +#descriptor-examples-table > table > thead > tr > th:nth-child(2) { + width: 45%; +} + +#descriptor-examples-table > table > thead > tr > th:nth-child(2) { + width: 45%; +} diff --git a/static/icons/android-chrome-192x192.png b/static/icons/android-chrome-192x192.png new file mode 100644 index 0000000000..a2e4dad8c2 Binary files /dev/null and b/static/icons/android-chrome-192x192.png differ diff --git a/static/icons/android-chrome-512x512.png b/static/icons/android-chrome-512x512.png new file mode 100644 index 0000000000..3b4b06bbba Binary files /dev/null and b/static/icons/android-chrome-512x512.png differ diff --git a/static/icons/apple-touch-icon.png b/static/icons/apple-touch-icon.png new file mode 100644 index 0000000000..ed9281b8ba Binary files /dev/null and b/static/icons/apple-touch-icon.png differ diff --git a/static/icons/browserconfig.xml b/static/icons/browserconfig.xml new file mode 100644 index 0000000000..b3930d0f04 --- /dev/null +++ b/static/icons/browserconfig.xml @@ -0,0 +1,9 @@ + + + + + + #da532c + + + diff --git a/static/icons/favicon-16x16.png b/static/icons/favicon-16x16.png new file mode 100644 index 0000000000..678299afbe Binary files /dev/null and b/static/icons/favicon-16x16.png differ diff --git a/static/icons/favicon-32x32.png b/static/icons/favicon-32x32.png new file mode 100644 index 0000000000..c0a3b561c9 Binary files /dev/null and b/static/icons/favicon-32x32.png differ diff --git a/static/icons/favicon.ico b/static/icons/favicon.ico new file mode 100644 index 0000000000..b6571971cd Binary files /dev/null and b/static/icons/favicon.ico differ diff --git a/static/icons/mstile-150x150.png b/static/icons/mstile-150x150.png new file mode 100644 index 0000000000..17106a6aa6 Binary files /dev/null and b/static/icons/mstile-150x150.png differ diff --git a/static/icons/safari-pinned-tab.svg b/static/icons/safari-pinned-tab.svg new file mode 100644 index 0000000000..a882dc1927 --- /dev/null +++ b/static/icons/safari-pinned-tab.svg @@ -0,0 +1,82 @@ + + + + +Created by potrace 1.11, written by Peter Selinger 2001-2013 + + + + + diff --git a/static/icons/site.webmanifest b/static/icons/site.webmanifest new file mode 100644 index 0000000000..ccaa826fe6 --- /dev/null +++ b/static/icons/site.webmanifest @@ -0,0 +1,19 @@ +{ + "name": "MagicalBitcoin Docs", + "short_name": "MagicalBitcoin Docs", + "icons": [ + { + "src": "/android-chrome-192x192.png", + "sizes": "192x192", + "type": "image/png" + }, + { + "src": "/android-chrome-512x512.png", + "sizes": "512x512", + "type": "image/png" + } + ], + "theme_color": "#ffffff", + "background_color": "#ffffff", + "display": "standalone" +} diff --git a/static/images/logo.svg b/static/images/logo.svg new file mode 100644 index 0000000000..b284a89c4d --- /dev/null +++ b/static/images/logo.svg @@ -0,0 +1,283 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/static/images/wizard.svg b/static/images/wizard.svg new file mode 100644 index 0000000000..5fc405bf16 --- /dev/null +++ b/static/images/wizard.svg @@ -0,0 +1,327 @@ + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/static/js/github-buttons.js b/static/js/github-buttons.js new file mode 100644 index 0000000000..7b87efaec1 --- /dev/null +++ b/static/js/github-buttons.js @@ -0,0 +1,6 @@ +/*! + * github-buttons v2.7.0 + * (c) 2020 なつき + * @license BSD-2-Clause + */ +!function(){"use strict";var e=window.document,t=e.location,o=window.Math,r=window.HTMLElement,n=window.XMLHttpRequest,a="https://buttons.github.io/buttons.html",i=n&&n.prototype&&"withCredentials"in n.prototype,l=i&&r&&r.prototype.attachShadow&&!r.prototype.attachShadow.prototype,c=function(e,t,o,r){null==t&&(t="&"),null==o&&(o="="),null==r&&(r=window.decodeURIComponent);for(var n={},a=e.split(t),i=0,l=a.length;i'},heart:{width:12,height:16,path:''},eye:{width:16,height:16,path:''},star:{width:14,height:16,path:''},"repo-forked":{width:10,height:16,path:''},"repo-template":{width:14,height:16,path:''},"issue-opened":{width:14,height:16,path:''},"cloud-download":{width:16,height:16,path:''}},x={},y=function(e,t){var o=x[e]||(x[e]=[]);if(!(o.push(t)>1)){var r=p((function(){for(delete x[e];t=o.shift();)t.apply(null,arguments)}));if(i){var a=new n;d(a,"abort",r),d(a,"error",r),d(a,"load",(function(){var e;try{e=JSON.parse(a.responseText)}catch(e){return void r(e)}r(200!==a.status,e)})),a.open("GET",e),a.send()}else{var l=this||window;l._=function(e){l._=null,r(200!==e.meta.status,e.data)};var c=u(l.document)("script",{async:!0,src:e+(/\?/.test(e)?"&":"?")+"callback=_"}),s=function(){l._&&l._({meta:{}})};d(c,"load",s),d(c,"error",s),c.readyState&&h(c,/de|m/,s),l.document.getElementsByTagName("head")[0].appendChild(c)}}},k=function(e,t,o){var r=u(e.ownerDocument),n=e.appendChild(r("style",{type:"text/css"})),a="body{margin:0}a{text-decoration:none;outline:0}.widget{display:inline-block;overflow:hidden;font-family:-apple-system,BlinkMacSystemFont,Segoe UI,Helvetica,Arial,sans-serif;font-size:0;white-space:nowrap}.btn,.social-count{position:relative;display:inline-block;height:14px;padding:2px 5px;font-size:11px;font-weight:600;line-height:14px;vertical-align:bottom;cursor:pointer;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;background-repeat:repeat-x;background-position:-1px -1px;background-size:110% 110%;border:1px solid}.btn{border-radius:.25em}.btn:not(:last-child){border-radius:.25em 0 0 .25em}.social-count{border-left:0;border-radius:0 .25em .25em 0}.widget-lg .btn,.widget-lg .social-count{height:20px;padding:3px 10px;font-size:12px;line-height:20px}.octicon{display:inline-block;vertical-align:text-top;fill:currentColor}"+function(e){if(null==e)return v.light;var t=c(e,";",":",(function(e){return e.replace(/^[ \t\n\f\r]+|[ \t\n\f\r]+$/g,"")}));return v[b(v,t["no-preference"])?t["no-preference"]:"light"]+m("light",t.light)+m("dark",t.dark)}(t["data-color-scheme"]);n.styleSheet?n.styleSheet.cssText=a:n.appendChild(e.ownerDocument.createTextNode(a));var i,l,d=r("a",{className:"btn",href:t.href,target:"_blank",rel:"noopener",innerHTML:(i=t["data-icon"],l=/^large$/i.test(t["data-size"])?16:14,i=(""+i).toLowerCase().replace(/^octicon-/,""),b(w,i)||(i="mark-github"),'"),"aria-label":t["aria-label"]||void 0},[" ",r("span",{},[t["data-text"]||""])]),s=e.appendChild(r("div",{className:"widget"+(/^large$/i.test(t["data-size"])?" widget-lg":"")},[d])),f=d.hostname.split(".").reverse();if(""===f[0]&&f.shift(),"com"!==f[0]||"github"!==f[1])return d.href="#",d.target="_self",void o(s);var h=f.length,g=(" /"+d.pathname).split(/\/+/);if(((2===h||3===h&&"gist"===f[2])&&"archive"===g[3]||2===h&&"releases"===g[3]&&"download"===g[4]||3===h&&"codeload"===f[2])&&(d.target="_top"),/^true$/i.test(t["data-show-count"])&&2===h){var p,x;if(!g[2]&&g[1])p=x="followers";else if(!g[3]&&g[2])x="stargazers_count",p="stargazers";else if(g[4]||"subscription"!==g[3])if(g[4]||"fork"!==g[3]){if("issues"!==g[3])return void o(s);x="open_issues_count",p="issues"}else x="forks_count",p="network/members";else x="subscribers_count",p="watchers";var k=g[2]?"/repos/"+g[1]+"/"+g[2]:"/users/"+g[1];y.call(this,"https://api.github.com"+k,(function(e,t){if(!e){var n=t[x];s.appendChild(r("a",{className:"social-count",href:t.html_url+"/"+p,target:"_blank",rel:"noopener","aria-label":n+" "+x.replace(/_count$/,"").replace("_"," ").slice(0,n<2?-1:void 0)+" on GitHub"},[(""+n).replace(/\B(?=(\d{3})+(?!\d))/g,",")]))}o(s)}))}else o(s)},C=window.devicePixelRatio||1,z=function(e){return(C>1?o.ceil(o.round(e*C)/C*2)/2:o.ceil(e))||0},F=function(e,t){e.style.width=t[0]+"px",e.style.height=t[1]+"px"},M=function(t,r){if(null!=t&&null!=r)if(t.getAttribute&&(t=function(e){for(var t={href:e.href,title:e.title,"aria-label":e.getAttribute("aria-label")},o=["icon","color-scheme","text","size","show-count"],r=0,n=o.length;r { + if (el !== null) { + htmlElement.appendChild(el); + } + }); + } + + return htmlElement; +} + + +/** + * @param {Object} node + * @return {HTMLElement} + */ +function createExpandedElement(node) { + const iElem = createElement('i'); + + if (node.expanded) { + iElem.className = 'fas fa-caret-down'; + } else { + iElem.className = 'fas fa-caret-right'; + } + + const caretElem = createElement('div', { + className: 'caret-icon', + children: [iElem], + }); + + const handleClick = node.toggle.bind(node); + caretElem.addEventListener('click', handleClick); + + const indexElem = createElement('div', { + className: 'json-index', + content: node.key, + }); + + const typeElem = createElement('div', { + className: 'json-type', + content: node.type, + }); + + const keyElem = createElement('div', { + className: 'json-key', + content: node.key, + }); + + const sizeElem = createElement('div', { + className: 'json-size' + }); + + if (node.type === 'array') { + sizeElem.innerText = '[' + node.children.length + ']'; + } else if (node.type === 'object') { + sizeElem.innerText = '{' + node.children.length + '}'; + } + + let lineChildren; + if (node.key === null) { + lineChildren = [caretElem, typeElem, sizeElem] + } else if (node.parent.type === 'array') { + lineChildren = [caretElem, indexElem, sizeElem] + } else { + lineChildren = [caretElem, keyElem, sizeElem] + } + + const lineElem = createElement('div', { + className: 'line', + children: lineChildren + }); + + if (node.depth > 0) { + lineElem.style = 'margin-left: ' + node.depth * 24 + 'px;'; + } + + return lineElem; +} + + +/** + * @param {Object} node + * @return {HTMLElement} + */ +function createNotExpandedElement(node) { + const caretElem = createElement('div', { + className: 'empty-icon', + }); + + const keyElem = createElement('div', { + className: 'json-key', + content: node.key + }); + + const separatorElement = createElement('div', { + className: 'json-separator', + content: ':' + }); + + const valueType = ' json-' + typeof node.value; + const valueContent = String(node.value); + const valueElement = createElement('div', { + className: 'json-value' + valueType, + content: valueContent + }); + + const lineElem = createElement('div', { + className: 'line', + children: [caretElem, keyElem, separatorElement, valueElement] + }); + + if (node.depth > 0) { + lineElem.style = 'margin-left: ' + node.depth * 24 + 'px;'; + } + + return lineElem; +} + + +/** + * create tree node + * @return {Object} + */ +function createNode() { + return { + key: null, + parent: null, + value: null, + expanded: false, + type: null, + children: null, + elem: null, + depth: 0, + + setCaretIconRight() { + const icon = this.elem.querySelector('.fas'); + icon.classList.replace('fa-caret-down', 'fa-caret-right'); + }, + + setCaretIconDown() { + const icon = this.elem.querySelector('.fas'); + icon.classList.replace('fa-caret-right', 'fa-caret-down'); + }, + + hideChildren() { + if (this.children !== null) { + this.children.forEach((item) => { + item.elem.classList.add('hide'); + if (item.expanded) { + item.hideChildren(); + } + }); + } + }, + + showChildren() { + if (this.children !== null) { + this.children.forEach((item) => { + item.elem.classList.remove('hide'); + if (item.expanded) { + item.showChildren(); + } + }); + } + }, + + toggle: function() { + if (this.expanded) { + this.expanded = false; + this.hideChildren(); + this.setCaretIconRight(); + } else { + this.expanded = true; + this.showChildren(); + this.setCaretIconDown(); + } + } + } +} + + +/** + * Return object length + * @param {Object} obj + * @return {number} + */ +function getLength(obj) { + let length = 0; + for (let key in obj) { + length += 1; + }; + return length; +} + + +/** + * Return variable type + * @param {*} val + */ +function getType(val) { + let type = typeof val; + if (Array.isArray(val)) { + type = 'array'; + } else if (val === null) { + type = 'null'; + } + return type; +} + + +/** + * Recursively traverse json object + * @param {Object} obj parsed json object + * @param {Object} parent of object tree + */ +function traverseObject(obj, parent) { + for (let key in obj) { + const child = createNode(); + child.parent = parent; + child.key = key; + child.type = getType(obj[key]); + child.depth = parent.depth + 1; + child.expanded = false; + + if (typeof obj[key] === 'object') { + child.children = []; + parent.children.push(child); + traverseObject(obj[key], child); + child.elem = createExpandedElement(child); + } else { + child.value = obj[key]; + child.elem = createNotExpandedElement(child); + parent.children.push(child); + } + } +} + + +/** + * Create root of a tree + * @param {Object} obj Json object + * @return {Object} + */ +function createTree(obj) { + const tree = createNode(); + tree.type = getType(obj); + tree.children = []; + tree.expanded = true; + + traverseObject(obj, tree); + tree.elem = createExpandedElement(tree); + + return tree; +} + + +/** + * Recursively traverse Tree object + * @param {Object} node + * @param {Callback} callback + */ +function traverseTree(node, callback) { + callback(node); + if (node.children !== null) { + node.children.forEach((item) => { + traverseTree(item, callback); + }); + } +} + + +/** + * Render Tree object + * @param {Object} tree + * @param {String} targetElem + */ +function render(tree, rootElem) { + /*if (targetElem) { + rootElem = document.querySelector(targetElem); + } else { + rootElem = document.body; + }*/ + + traverseTree(tree, (node) => { + if (!node.expanded) { + node.hideChildren(); + } + rootElem.appendChild(node.elem); + }); +} + + +/* Export jsonView object */ +window.jsonView = { + /** + * Render JSON into DOM container + * @param {String} jsonData + * @param {String} targetElem + */ + format: function(jsonData, targetElem) { + let parsedData = jsonData; + if (typeof jsonData === 'string' || jsonData instanceof String) parsedData = JSON.parse(jsonData); + const tree = createTree(parsedData); + render(tree, targetElem); + } +} + +})(); diff --git a/static/js/main.js b/static/js/main.js new file mode 100644 index 0000000000..f8c170f557 --- /dev/null +++ b/static/js/main.js @@ -0,0 +1,6 @@ +jQuery(document).ready(function() { + $('div.json[data-json]').each(function(index, element) { + var json = $(element).attr('data-json').replace(/[\u201C\u201D]/g, '"'); + jsonView.format(json, element); + }); +}); diff --git a/themes/learn b/themes/learn new file mode 160000 index 0000000000..d4abb3c9a1 --- /dev/null +++ b/themes/learn @@ -0,0 +1 @@ +Subproject commit d4abb3c9a103bdd14e82184f76463a02755ee070