WIP: writing multisig wallet guide #96

joemphilips · 2018-07-15T08:00:40Z

This is for #63
I haven't finished writing yet, after I complete TODO: section, I will mention again.
Tell me if I've got something wrong (e.g. "walk through has missing section" . etc.)

joemphilips · 2018-07-17T02:33:50Z

Waiting for bcoin-org/bcoin#444 to get solved ...

pinheadmz

Thanks for the contribution Joe!

I think you are off to a great start and I look forward to you filling out the TODO's.

My notes in general are:

A lot of the plain text writing needs help (spelling, punctuation, etc.) I have added comments throughout, but I can continue to work with you if English isn't your primary language.
See my comment about rendering the markdown with the built-in npm script convert-markdown and let me know if you need help with that. The script will produce an html file in the guides directory you can open in a browser and check the layout and style. Take a look at the other guides in the guides-markdown directory for tips on how these webpages get rendered.
The section about setting up a wallet server with an SSL certificate is cool but it may be overkill for the new users we want to attract with this guide. Perhaps you can start that section with instructions on how to use the wallet on a local machine, or a server via ssh. Save the SSL stuff for an "advanced" or "what next" type section?
Spending funds: obviously this section is very important! The API docs should help:

http://bcoin.io/api-docs/?shell--curl#create-a-transaction

and

http://bcoin.io/api-docs/?shell--curl#sign-transaction

pinheadmz · 2018-07-17T20:01:01Z

guides-markdown/multisig-wallet.md

+
+Our `bcoin.conf` is
+
+```sh:bcoin.conf


This isn't rendering for me with prismjs:

$ npm run convert-markdown -- --file=multisig-wallet.md There was a problem: TypeError: Cannot read property 'rest' of undefined ...

It renders correctly if these are all changed to just bash but you can include the filename at the top of each blob in a commented line.

Thanks, I decided to change it into bash and worked fine in my local.

pinheadmz · 2018-07-17T20:06:08Z

guides-markdown/multisig-wallet.md

+we must create multisig transaction which has been signed by private key corresponds to those public key,
+see [our multisig transaction guide](http://bcoin.io/guides/multisig-tx.html) for more detail about multisig transaction itself.
+
+In this guide, we take a step little further and see a whole lifecycle of the multisig account in a more practical way.


A few grammar notes:

A Bitcoin multisig account is an account which holds more than 1 public key, and generates P2SH or P2WSH addresses for those public keys. When you want to use those funds, you must create a multisig transaction which has been signed by the private keys corresponding to those public keys. See our multisig transaction guide for more detail about the multisig transaction itself.

In this guide, we will take it a step little further and see a whole lifecycle of the multisig account in a more practical way.

pinheadmz · 2018-07-17T21:15:48Z

guides-markdown/multisig-wallet.md

+
+you can backup your funds unless more than two keys were compromised at the same time.
+In this case, you may use 1. and 2. for usual spending.
+You only need 3 when you lost your secret key for 1 and 2


Grammar:

Use Cases

Personal wallet which is secure against key compromise

Usually in a cryptocurrency world, when you lose your master key and its seed for the wallet there is no way to recover your funds. But by storing multiple secret keys on...

your own server

local hardware you own

a paper wallet in your personal vault

...your funds will be safe unless more than one key is compromised at the same time. In this case, you may use 1 and 2 for usual spending, and only need 3 if you lose your secret keys 1 and 2.

pinheadmz · 2018-07-17T21:20:15Z

guides-markdown/multisig-wallet.md

+2. Or disappeared suddenly.
+3. Or lost his secret-key.
+4. Or be stolen the secret-key
+5. Or tried to thief all funds for his personal use.


Grammar:

Wallet held by more than one person

Sometimes it is desirable to distribute the control of funds among several people. For example, funds for a corporation or a crowdfunding project. We can mitigate the risk of fund loss by utilizing a multisig in cases where a a single person with control:

Is no longer in charge

Disappears suddenly

Loses their secret-key

Tries to steal all funds for their own personal use

pinheadmz · 2018-07-17T21:22:03Z

guides-markdown/multisig-wallet.md

+ 4. receive incoming information from the wallet server.
+ 5. spend funds from the wallet.
+ 6. recovering the wallet
+


Grammar:

Walk-through

This tutorial includes the following steps:

setting up a bcoin wallet server with https

setting up a hot multisig wallet for personal use

setting up a watch-only multisig wallet

receive incoming information from the wallet server

spend funds from the wallet

recovering the wallet

pinheadmz · 2018-07-18T17:01:38Z

guides-markdown/multisig-wallet.md

+  --network=testnet \
+  --api-key=mySecretApiKey \
+  --token=${myadmintoken} \ # Must use your admin token to create a new wallet
+  --watch-only=true \ # make it watch only


watchOnly

It seems master branch (and latest release) has changed after your PR has merged.

pinheadmz · 2018-07-18T17:01:45Z

guides-markdown/multisig-wallet.md

+  --type=multisig \
+  --m=2 \
+  --n=3 \
+  --name=multisig1 \


id or omit

pinheadmz · 2018-07-18T17:02:04Z

guides-markdown/multisig-wallet.md

+  --network=testnet \
+  --api-key=mySecretApiKey \
+  --token=${myadmintoken} \
+  --acount=multisig1 \


account typo :-)

pinheadmz · 2018-07-18T17:02:16Z

guides-markdown/multisig-wallet.md

+  --network=testnet \
+  --api-key=mySecretApiKey \
+  --token=${myadmintoken} \ # rescanning requires admin token
+  --acount=multisig1 \


pinheadmz · 2018-07-18T17:10:22Z

guides-markdown/multisig-wallet.md

+  --api-key=mySecretApiKey \
+  --token=${myadmintoken} \ # rescanning requires admin token
+  --acount=multisig1 \
+  rescan 10000  # start rescanning from height 10000


rescan is slightly problematic at this time.

See bcoin-org/bcoin#532

It really only works on a full archival node. SPV users should probably use reset and pruned full-node users might be out of luck if there are transactions on-chain before their prune height. Might be good to add a warning here.

joemphilips

I have added comments throughout, but I can continue to work with you if English isn't your primary language.

I really appreciate this, thanks.

I've written reasoning behind using (ssl/tls) in the review comment, If you think using the same watch tower among co-signers are too dangerous or somehow problematic, I'd better delete the whole section about (ssl/tls) and rewrite it with assuming co-signers are using their own wallet server.

joemphilips · 2018-07-19T02:40:11Z

guides-markdown/multisig-wallet.md

+  --network=testnet \
+  --api-key=mySecretApiKey \
+  --token=${myadmintoken} \ # Must use your admin token to create a new wallet
+  --watch-only=true \ # make it watch only


It seems master branch (and latest release) has changed after your PR has merged.

joemphilips · 2018-07-19T03:01:28Z

guides-markdown/multisig-wallet.md

+  --network=testnet \
+  --api-key=mySecretApiKey \
+  --token=${myadmintoken} \ # Must use your admin token to create a new wallet
+  --watch-only=true \ # make it watch only


It seems master branch (and latest release) has changed after your PR has merged.

joemphilips · 2018-07-19T09:11:02Z

guides-markdown/multisig-wallet.md

+
+Our `bcoin.conf` is
+
+```sh:bcoin.conf


Thanks, I decided to change it into bash and worked fine in my local.

joemphilips · 2018-07-20T03:02:56Z

guides-markdown/multisig-wallet.md

+ 5. spend funds from the wallet.
+ 6. recovering the wallet
+
+### 1. Setting up bcoin wallet server with https.


Well, this is because I was thinking that this watch-only wallet works as kind of a "semi-trusted watch-tower service" for every co-signer.
I mean, the scenario I was assuming is that co-signer don't have to run a wallet server in the local, instead they register their xpub onto this server and listen to it directly.
I made it this way because this will likely make things more simple when e.g. some co-signer made a intent to pay from the wallet. wallet server can directly push notification to every co-signer. (Possibly through plugin.)
I will certainly clarify this logic in the document. And mention that https is not mandatory as you pointed out.

joemphilips · 2018-07-20T03:08:20Z

guides-markdown/multisig-wallet.md

+and throw it to the bcoin server
+
+```sh
+curl -X PUT ${url}/wallet/sharedWallet1/account/multisig1\?token\=${sharedWalletToken} \


Ah, correct endpoint was /wallet/:id/shared-key . I will fix.
I'd better write both case using curl and bwallet-cli. To me, sometimes it was more intuitive to use curl , since I only had to read source code for wallet/http.js (instead of bclient , bcurl , and wallet/http.js)

joemphilips · 2018-07-20T03:16:51Z

guides-markdown/multisig-wallet.md

+> So some options we have passed here (i.e. `type`, `m`, `n`, and `name`) are for the default account created with the wallet.
+
+If the wallet is created successfully, than you will see the access token for that wallet in the return value.
+So let's set that token into variable named `sharedWalletToken` and pass to co-signers.


I've made it this way with the same reason I assumed https.

joemphilips · 2018-07-20T03:46:06Z

guides-markdown/multisig-wallet.md

+  --api-key=mySecretApiKey \
+  --token=${myadmintoken} \ # rescanning requires admin token
+  --acount=multisig1 \
+  rescan 10000  # start rescanning from height 10000


pinheadmz · 2018-07-24T17:17:39Z

Thanks for the revisions, @joemphilips. I look forward to your TODO's. I still think the simple self-hosted multisig wallet method would be more appropriate to describe before the more advanced shared-server model with SSL and wallet tokens. Also @nodar-chkuaselidze is going to take a look at that section just to make sure the security is handled correctly.

tynes · 2018-07-25T00:00:05Z

guides-markdown/multisig-wallet.md

+For example, funds for a corporation or for a crowdfunding project.
+We can mitigate the risk of fund loss by utilizing a multisig in cases where single person with control:
+
+1. Is no longer in charge


Not super important, but more of a nit, in markdown you can put all of your numbers as 1 and then they will render 1,2,3,4,etc - it helps if you want to quickly reorder things at some point in the future

tynes · 2018-07-25T00:02:41Z

guides-markdown/multisig-wallet.md

+lets assume that Alice uses [bitcoinjs-lib](https://github.com/bitcoinjs/bitcoinjs-lib) in her software.
+So the code will be something like ...
+
+```js


While you can definitely use bitcoinjs, there are also utilities in bcoin to do everything that you would need to do here. The other guides are really good for getting up to speed on this

tynes · 2018-07-25T00:05:33Z

guides-markdown/multisig-wallet.md

+2. To collaborate with others easily ... in later secrion, we are showing how to use watch-only wallet with more than one people. In those situation, some might not be familiar with accessing the server with IP address, or want to access from browser, or don't want to bother himself remember(and track) IP address for the server.
+
+We assume you already have gotten your domain name somehow,
+and that is `bcoin.multisigtest.com`.


Do you think it would be easier to create a self signed cert for localhost so that users can more easily follow along?

tynes · 2018-07-25T00:08:41Z

guides-markdown/multisig-wallet.md

+
+Ok, so let's check the wallet's status by
+
+```bash


Are you familiar with jq? It lets you parse json from stdin and could be very useful for giving precise commands and their results

$ curl ${url}/wallet/sharedWallet1/account/default?token=${sharedWalletToken} \ | jq .balance { "tx": 0, "coin": 0, "unconfirmed": 0, "confirmed": 0 }

pinheadmz requested changes Jul 18, 2018

View reviewed changes

joemphilips commented Jul 20, 2018

View reviewed changes

tynes reviewed Jul 25, 2018

View reviewed changes

joemphilips added 2 commits September 6, 2018 01:35

WIP: writing multisig wallet guide

89ee7d2

squash me! address to comments in the first review

afc0692

joemphilips force-pushed the multisig-guide branch from c66acab to afc0692 Compare September 5, 2018 16:39

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

WIP: writing multisig wallet guide #96

WIP: writing multisig wallet guide #96

joemphilips commented Jul 15, 2018

joemphilips commented Jul 17, 2018 •

edited

Loading

pinheadmz left a comment

pinheadmz Jul 17, 2018

joemphilips Jul 19, 2018

pinheadmz Jul 17, 2018

pinheadmz Jul 17, 2018

pinheadmz Jul 17, 2018

pinheadmz Jul 17, 2018

pinheadmz Jul 18, 2018

joemphilips Jul 19, 2018

pinheadmz Jul 18, 2018

pinheadmz Jul 18, 2018

pinheadmz Jul 18, 2018

pinheadmz Jul 18, 2018

joemphilips Jul 20, 2018

joemphilips left a comment •

edited

Loading

joemphilips Jul 19, 2018

joemphilips Jul 19, 2018

joemphilips Jul 19, 2018

joemphilips Jul 20, 2018

joemphilips Jul 20, 2018

joemphilips Jul 20, 2018

joemphilips Jul 20, 2018

pinheadmz commented Jul 24, 2018

tynes Jul 25, 2018

tynes Jul 25, 2018

tynes Jul 25, 2018

tynes Jul 25, 2018


		Our `bcoin.conf` is

		```sh:bcoin.conf


		Our `bcoin.conf` is

		```sh:bcoin.conf

WIP: writing multisig wallet guide #96

Are you sure you want to change the base?

WIP: writing multisig wallet guide #96

Conversation

joemphilips commented Jul 15, 2018

joemphilips commented Jul 17, 2018 • edited Loading

pinheadmz left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joemphilips left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pinheadmz commented Jul 24, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joemphilips commented Jul 17, 2018 •

edited

Loading

joemphilips left a comment •

edited

Loading