diff --git a/Docs/Account-map.md b/Docs/Account-map.md new file mode 100644 index 0000000..5d3f8e5 --- /dev/null +++ b/Docs/Account-map.md @@ -0,0 +1,73 @@ +# Account Map + +*Gordian Wallet* utilizes what we refer to as an *Account Map* to allow users to seamlessly export and import accounts (wallets). The below description is a brief spec defining the scheme and the motivation. + +### Overview +An Account Map is a simple `json` serialized dictionary that consists of three parts; + +1. `descriptor` - string, required. This is a Bitcoin Core compatible output descriptor which utilizes `h` to denote hardened path components and does not include a checksum. +2. `blockheight` - int, required. This is the blockheight which is associated with the first ever transaction or birthdate of the account. Client software should automatically initiate a rescan from this blockheight so that users may seamlessly view balances and transaction history when going importing accounts. If the birthdate is not known then a 0 can be used which will initiate a rescan from the genesis block. +3. `label` - string, required. This can be an empty string or consist of a user added label for the account, so that end users may easily recognize what it is they are importing. + +### Motivation +Recovering a wallet can be a daunting task with little cross wallet compatibility. Bitcoin Core output descriptors are used so that there is no ambiguity between wallets and the account which is being recovered will derive the correct keys with certainty. + +JSON was chosen as it is widely adopted and used in all programming languages, its simple to serialize and parse. + +Account Maps prove to be incredibly useful especially in the case of multi signature wallets, a huge amount of information is easily and unambiguously accessed. It allows users to easily back up all of their public keys and scripts which are needed to recreate multi signature accounts. This is of course made possible by Bitcoin Core output descriptors which you can read more about [here](https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md). + +### Change keys +Client side software needs to deduce the how the change keys will be derived from the supplied descriptor. As a general guideline Gordian Wallet will parse the descriptor to see if it contains `/0/*`, which denotes receive keys. *Gordian Wallet* automatically generates a change descriptor by simply replacing `/0/*` with `/1/*`. Users ought to be warned if they are not utilizing a standard extended key descriptor as the client side software will have no way of knowing with certainty how to derive change keys if the supplied descriptor is not HD and does not include `/0/*`. + +### Examples + +1. Single sig, testnet, BIP84 account + +- JSON: +``` +{ +"descriptor": +"wpkh([c258d2e4\/84h\/1h\/0h]tpubDD3ynpHgJQW8VvWRzQ5WFDCrs4jqVFGHB3vLC3r49XHJSqP8bHKdK4AriuUKLccK68zfzowx7YhmDN8SiSkgCDENUFx9qVw65YyqM78vyVe\/0\/*)", +"blockheight":1782088, +"label":"testnet" +} +``` +- Plain text: +``` +"descriptor": +"wpkh([c258d2e4/84h/1h/0h]tpubDD3ynpHgJQW8VvWRzQ5WFDCrs4jqVFGHB3vLC3r49XHJSqP8bHKdK4AriuUKLccK68zfzowx7YhmDN8SiSkgCDENUFx9qVw65YyqM78vyVe/0/*)", +"blockheight":1782088, +"label":"testnet" +``` + +- QR (json serialized): +Single-sig Account Map + +2. Multi sig, testnet, BIP67, m48', p2wsh, 2 of 3 account + +- JSON: +``` +{ +"descriptor":"wsh(sortedmulti(2,[119dbcab\/48h\/1h\/0h\/2h]tpubDFYr9xD4WtT3yDBdX2qT2j2v6ZruqccwPKFwLguuJL99bWBrk6D2Lv1aPpRbFnw1sQUU9DM7ScMAkPRJqR1iXKhWMBNMAJ45QCTuvSZbzzv\/0\/*,[e650dc93\/48h\/1h\/0h\/2h]tpubDEijNAeHVNmm6wHwspPv4fV8mRkoMimeVCk47dExpN9e17jFti12BdjzL8MX17GvKEekRzknNuDoLy1Q8fujYfsWfCvjwYmjjENUpzwDy6B\/0\/*,[bcc3df08\/48h\/1h\/0h\/2h]tpubDFLAjoM9CeEsvZp3UEakCW9jGpx1MgVJP9eteh8Qyr8XN9ASDJoMz58D5YNqm4oRbuBr5LFjfzv6SzsQYUPNWHHYUxvsPimak1tU3cMUhqv\/0\/*))", +"blockheight":1781992, +"label":"warm test" +} +``` + +- Plain text: +``` +{ +"descriptor":"wsh(sortedmulti(2,[119dbcab/48h/1h/0h/2h]tpubDFYr9xD4WtT3yDBdX2qT2j2v6ZruqccwPKFwLguuJL99bWBrk6D2Lv1aPpRbFnw1sQUU9DM7ScMAkPRJqR1iXKhWMBNMAJ45QCTuvSZbzzv/0/*,[e650dc93/48h/1h/0h/2h]tpubDEijNAeHVNmm6wHwspPv4fV8mRkoMimeVCk47dExpN9e17jFti12BdjzL8MX17GvKEekRzknNuDoLy1Q8fujYfsWfCvjwYmjjENUpzwDy6B/0/*,[bcc3df08/48h/1h/0h/2h]tpubDFLAjoM9CeEsvZp3UEakCW9jGpx1MgVJP9eteh8Qyr8XN9ASDJoMz58D5YNqm4oRbuBr5LFjfzv6SzsQYUPNWHHYUxvsPimak1tU3cMUhqv/0/*))", +"blockheight":1781992, +"label":"warm test" +} +``` + +- QR (json serialized): +Multi-sig Account Map + +### Supported by +- [Gordian Wallet](https://testflight.apple.com/join/RNvBmjB3) +- [Specter-Desktop](https://github.com/cryptoadvance/specter-desktop) +- [Fully Noded](https://apps.apple.com/us/app/fully-noded/id1436425586) +- [Magical Bitcoin Wallet](https://github.com/MagicalBitcoin/magical-bitcoin-wallet) diff --git a/Docs/Policy-map.md b/Docs/Policy-map.md new file mode 100644 index 0000000..150e98c --- /dev/null +++ b/Docs/Policy-map.md @@ -0,0 +1,61 @@ +# Policy Map + +*Gordian System* utilizes what we refer to as an [*Account Map*](./Account-map.md) to allow users to seamlessly export and import accounts (aka wallets). + +A *Policy Map* is a key-less (or incomplete) *Account Map* which can be utilized for the purpose of coordinating a multi-party/multi-signature account. + +The *Policy Map* defines the total number of participants that may join, the number of required signatories to spend funds, the script type, and optionally derivation paths. + +Other metadata may be added which is not yet described. + +### Initiator + +The initiator will create the initial *Policy Map*, the primary parameter is an incomplete [output descriptor](https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md). + +The initiator must decide on a script type, for our purposes we will stick with the most widely adopted standard which is `witness script hash`, denoted as `wsh` in an output descriptor. + +The total number of participants for our example will be `3`. + +The required number of signatories for our example will be `2`, creating a 2 of 3 multi-sig account. + +This particular *Policy Map* will utilize [BIP67](https://github.com/bitcoin/bips/blob/master/bip-0067.mediawiki) by including the `sortedmulti` prefix. + +The initiator, in this example, prefers to utilize the most widely adopted multi-sig derivation path which is `m/48'/0'/0'/2'`. This is optional, there is no requirement that the initiator must decide on this. Derivations can be added by each individual participant when they add their public key. + +The *Policy Map* would look like this in the initiation stage as per our example: + +`wsh(sortedmulti(2,[/48h/0h/0h/2h],[/48h/0h/0h/2h],[/48h/0h/0h/2h]))` + +The initiator role is now complete, they may either update the *Policy Map* with their own `` and `` or simply pass it to the concerned parties. + +### Updater + +An updater is one of the concerned parties who will be invited to take part in the creation of the *Account Map*. + +In order to take part they must update the *Policy Map* with their extended public key and master key fingerprint (``, ``), at which point they either send it back to the initiator or to the next peer. + +After being passed to one party who agrees to take part the *Policy Map* would look like: + +`wsh(sortedmulti(2,[83hf9h94/48h/0h/0h/2h]xpub6CMZuJmP86KE8gaLyDNCQJWWzfGvWfDPhepzBG3keCLZPZ6XPXzsU82ms8BZwCUVR2UxrsDRa2YQ6nSmYbASTqadhRDp2qqd37UvFksA3wT,[/48h/0h/0h/2h],[/48h/0h/0h/2h]))` + +The master key fingerprint is described in [BIP32](https://en.bitcoin.it/wiki/BIP_0032), some offline signers require this metadata, others do not. Generally if the party does not know the master key fingerprint then wallet software can derive the fingerprint of the provided extended key and utilize that. + +### Finalizer + +Once all concerned parties have filled in their respective `fingerprint` and `xpub` the finalizer should ensure the validity of the output descriptor's keys and process it. For the purposes of *Gordian Wallet*, *Fully Noded* and *Specter* a standard has been discussed whereby the *Account Map's* `descriptor` is utilized as a cross application account identifier whereby the `wallet.dat` file created on Bitcoin Core is named deterministically as a derivate of the *Account Map's* `descriptor`. + +This works by ensuring the xpub's in the `descriptor` are sorted lexicographically. Hardened derivation path components are denoted using `h` (not `H` or `'`). This way we can then run the processed `descriptor` through a sha256 hash function, the resulting hash acting as the `wallet.dat` filename for the wallet/account (or at least a portion of it). This is an example `wallet.dat` filename in GordianWallet: `Gordian-8268d751e68922956e6b3ee6ccbb469d18e8a158ee814aa47cb07d0259c1bbad.dat`. + +Lexicographic sorting of the xpub's is important because a `sortedmulti` (BIP67) compatible `descriptor` will derive the same multi-sig addresses irregardless of the order of xpub's, however the hash of the descriptor would obviously change defeating the purpose of the use of the hash as a deterministic identifier. + +This can be incredibly useful for client software during the process of importing an account. The client software can simply process the `descriptor`, hash it and then see if the Bitcoin Core backend already holds a matching account, if it does it can simply reuse that `wallet.dat` file without requiring a rescan or worse a reindex of the blockchain, if it does not exist it will create the account from scratch. + +This works particularly well for users who utilize pruned nodes where wallet import/recovery can result in a very long and tedious process of "re-downloading the entire blockchain". In a multi-sig world it is likely a user will use multiple apps/wallets with one Bitcoin Core backend so as to reap the benefits of multi-sig by not relying on one application or operating system. + +Once the *Policy Map* is complete it can be added as the `descriptor` parameter in an *Account Map* along with the other relevant metadata. + +The finalized *Policy Map* should look like this: + +`wsh(sortedmulti(2,[83hf9h94/48h/0h/0h/2h]xpub6CMZuJmP86KE8gaLyDNCQJWWzfGvWfDPhepzBG3keCLZPZ6XPXzsU82ms8BZwCUVR2UxrsDRa2YQ6nSmYbASTqadhRDp2qqd37UvFksA3wT,[9ihgte55/48h/0h/0h/2h]xpub6FJ6w4NAGLFuE6dN3kjbu3fzdfJgULEMpNVD1QacRvnBozrgy4tMMJtXweewEngBxrwR4Q6NwHqu15w2ALPsaUCyXDWUCKUV3WztzJYGZHw,[00yt3t6t/48h/0h/0h/2h]xpub6CcJQNxt2z7s1dPMCuR6CAtyoqc5xYkFPkyJbokjaiEjixcWZPx2huKc8BSBYqv3jya1SBeUfx6rRdLneGVgNCWsBghSiPNB7Vz3ZhWtCcD))` + +See [*Account Map*](./Account-map.md) for complete examples. diff --git a/Images/msig_map.jpeg b/Images/msig_map.jpeg new file mode 100644 index 0000000..d6801e3 Binary files /dev/null and b/Images/msig_map.jpeg differ diff --git a/Images/single_sig_map.jpeg b/Images/single_sig_map.jpeg new file mode 100644 index 0000000..06682a7 Binary files /dev/null and b/Images/single_sig_map.jpeg differ