kylefang/stacks-puppet-node
1
0
Fork 0
mirror of https://github.com/alexgo-io/stacks-puppet-node.git synced 2026-04-24 03:45:38 +08:00
Code Issues Packages Projects Releases Wiki Activity

better namespace docs

Browse Source
This commit is contained in:
Jude Nelson
2017-10-17 17:07:02 -04:00
parent 5160e01696
commit 1421bfb478
1 changed files with 110 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

127
docs/namespace_creation.md
View File

@@ -5,6 +5,17 @@ _in its entirety_. You should also _install the test framework_ and experiment
with your namespace's parameters. _FAILURE TO DO SO MAY RESULT IN IRRECOVERABLE
LOSS OF FUNDS._
**Before you begin**: Some basic familiarity with how Bitcoin works is required to
understand this tutorial. This includes:
* knowing the difference between mainnet, testnet, and regtest
* knowing about compressed and uncompressed ECDSA public keys
* knowing about base58-check encoding
* knowing how Bitcoin transactions are structured
* knowing how UTXOs work
## Overview
Creating a namespace is a three-step process. The first
step is to `preorder` the namespace, which broadcasts a salted hash of the
namespace ID. The second step is to `reveal` the namespace, which exposes the
@@ -16,7 +27,7 @@ In between the `reveal` and `ready` steps, the namespace creator will have a
the namespace creator can `import` names. The `import` transaction lets the
namespace creator assign the name a zone file and an owner in one step.
## Before Trying This...
## Before Trying This in Production...
Creating namespaces is expensive (hundreds to millions of USD)
Be sure to test your namespace in our [integration test
@@ -24,20 +35,103 @@ framework](https://github.com/blockstack/blockstack-core/tree/master/integration
first! It will let you simulate any valid namespace configuration
you want at no risk to you.
### Setting up the Test Environment
In this example, we will use the test framework to create a private Bitcoin
blockchain on your computer, and then create a Blockstack namespace on it.
This will let you experiment with different namespace parameters
without spending actual BTC. The test framework uses `bitcoind -regtest`,
so all of the commands you'll run here will work identically on
mainnet.
To install the test framework, please follow these
[instructions](https://github.com/blockstack/blockstack-core/tree/master/integration_tests).
Once you have the test framework installed, you should run the `namespace_check` test in `--interactive-web` mode.
This will create an empty `.test` namespace and leave the test scenario running
once it finishes. You will be able to fund addresses and create new blocks via
your Web browser or via `curl`, as will be explained below. Also, you'll be able to use the
`blockstack` utility to interact with your private blockchain and namespaces.
The test setup command is as follows. This will launch the `namespace_check`
test scenario, and open a web server on port 3001.
```
$ blockstack-test-scenario --interactive-web 3001 blockstack_integration_tests.scenarios.namespace_check
```
When the test is ready for us to experiment, you should see the following:
```
An empty namespace called 'test' has been created
Feel free to experiment with other namespaces
Available keys with a balance:
* 6e50431b955fe73f079469b24f06480aee44e4519282686433195b3c4b5336ef01
* c244642ce0b4eb68da8e098facfcad889e3063c36a68b7951fb4c085de49df1b01
* f4c3907cb5769c28ff603c145db7fc39d7d26f69f726f8a7f995a40d3897bb5201
* 8f87d1ea26d03259371675ea3bd31231b67c5df0012c205c154764a124f5b8fe01
* bb68eda988e768132bc6c7ca73a87fb9b0918e9a38d3618b74099be25f7cab7d01
* 2,3,6f432642c087c2d12749284d841b02421259c4e8178f25b91542c026ae6ced6d01,65268e6267b14eb52dc1ccc500dc2624a6e37d0a98280f3275413eacb1d2915d01,cdabc10f1ff3410082448b708c0f860a948197d55fb612cb328d7a5cc07a6c8a01
* 2,3,4c3ab2a0704dfd9fdc319cff2c3629b72ebda1580316c7fddf9fad1baa323e9601,75c9f091aa4f0b1544a59e0fce274fb1ac29d7f7e1cd020b66f941e5d260617b01,d62af1329e541871b244c4a3c69459e8666c40b683ffdcb504aa4adc6a559a7701
* 2,3,4b396393ca030b21bc44a5eba1bb557d04be1bfe974cbebc7a2c82b4bdfba14101,d81d4ef8123852403123d416b0b4fb25bcf9fa80e12aadbc08ffde8c8084a88001,d0482fbe39abd9d9d5c7b21bb5baadb4d50188b684218429f3171da9de206bb201
* 2,3,836dc3ac46fbe2bcd379d36b977969e5b6ef4127e111f2d3e2e7fb6f0ff1612e01,1528cb864588a6a5d77eda548fe81efc44180982e180ecf4c812c6be9788c76a01,9955cfdac199b8451ccd63ec5377a93df852dc97ea01afc47db7f870a402ff0501
```
Finally, you can use the `blockstack-test-env` command to set up your shell
environment variables so `blockstack` will interact with this test (instead of
mainnet). To do so, run the following in your shell:
```
$ . $(which blockstack-test-env) namespace_check
|blockstack-test namespace_check| $
```
You can verify that the environment variables by verifying that your `$PS1`
variable includes the name of your test (as shown above), and that some other
`BLOCKSTACK_`-prefixed variables are set:
```
|blockstack-test namespace_check| $ env | grep BLOCKSTACK
BLOCKSTACK_OLD_PS1=\u@\h:\w$
BLOCKSTACK_TESTNET=1
BLOCKSTACK_EPOCH_1_END_BLOCK=1
BLOCKSTACK_EPOCH_2_END_BLOCK=2
BLOCKSTACK_TEST=1
BLOCKSTACK_DEBUG=1
BLOCKSTACK_CLIENT_CONFIG=/tmp/blockstack-run-scenario.blockstack_integration_tests.scenarios.namespace_check/client/client.ini
```
## Registering a Namespace
Suppose we're going to create the `hello` namespace. The key
`L1EujLf4S4YXPhDUXwguMDiEjBVME2Tphs9H7qXz6DkwUpD1wf2P` will be the key that
`6e50431b955fe73f079469b24f06480aee44e4519282686433195b3c4b5336ef01` will be the key that
*pays* for the namespace. The key
`KxspG5n8JPqCHWuNdpvsfRayzc1X7FM675zsdmyhWAwpEtpj29cX` will be the key that
*creates* the namespace. The creator's key will be used to `import` names and
declare the namespace `ready`.
`c244642ce0b4eb68da8e098facfcad889e3063c36a68b7951fb4c085de49df1b01` will be the key that
*creates* the namespace. The creator key will be used to `import` names and
declare the namespace `ready`. The payment key will be used to both pay for the
namespace and receive name registration and renewal fees for the first year of
the namespace's lifetime.
In this example, we will set these keys as environment variables:
```
$ export PAYMENT_PKEY="77f76847dfb75cb3b32fa515b2d51bcf548aa0d2761ff3b2ca4d379aec2ea53e01"
$ export CREATOR_PKEY="31709f43493c6c750e3ea969624aad1983907ea0a038aad9e1aff60acd0676b301"
|blockstack-test namespace_check| $ export PAYMENT_PKEY="6e50431b955fe73f079469b24f06480aee44e4519282686433195b3c4b5336ef01"
|blockstack-test namespace_check| $ export CREATOR_PKEY="c244642ce0b4eb68da8e098facfcad889e3063c36a68b7951fb4c085de49df1b01"
```
#### Multisig Namespace Payment
If you want to use a multisig address to pay for your namespace (and collect
name registration fees), then instead of using
`6e50431b955fe73f079469b24f06480aee44e4519282686433195b3c4b5336ef01`, you should
use a string formatted as `m,n,pk1,pk2,...,pk_n`. `m` is the number of
signatures required, `n` is the number of private keys, and `pk1,pk2,...,pk_n`
are the private keys.
For example, you can use the following as your `PAYMENT_PKEY` to have a 2-of-3
multisig script pay for your namespace and collect name registration fees:
```
|blockstack-test namespace_check| $ export PAYMENT_PKEY="2,3,6f432642c087c2d12749284d841b02421259c4e8178f25b91542c026ae6ced6d01,65268e6267b14eb52dc1ccc500dc2624a6e37d0a98280f3275413eacb1d2915d01,cdabc10f1ff3410082448b708c0f860a948197d55fb612cb328d7a5cc07a6c8a01"
```
### Namespace preorder
@@ -45,7 +139,7 @@ In this example, we will set these keys as environment variables:
The command to preorder the namespace would be:
```
$ blockstack namespace_preorder hello "$PAYMENT_PKEY" "$CREATOR_PKEY"
|blockstack-test namespace_check| $ blockstack namespace_preorder hello "$PAYMENT_PKEY" "$CREATOR_PKEY"
```
You will be given a set of instructions on how to proceed to reveal and
@@ -64,7 +158,7 @@ preorder. The command will help you do so.
Here is a sample output:
```
$ blockstack namespace_preorder hello "$PAYMENT_PKEY" "$CREATOR_PKEY"
|blockstack-test namespace_check| $ blockstack namespace_preorder hello "$PAYMENT_PKEY" "$CREATOR_PKEY"
<...snip...>
@@ -72,15 +166,14 @@ Here is a sample output:
You will need it for `blockstack namespace_reveal`
Wait until b40dd1375ef63e5a40ee60d790ec6dccd06efcbac99d0cd5f3b07502a4ab05ac has six (6) confirmations. Then, you can reveal `hello` with:
$ blockstack namespace_reveal "hello" "77f76847dfb75cb3b32fa515b2d51bcf548aa0d2761ff3b2ca4d379aec2ea53e01" "31709f43493c6c750e3ea969624aad1983907ea0a038aad9e1aff60acd0676b301" "b40dd1375ef63e5a40ee60d790ec6dccd06efcbac99d0cd5f3b07502a4ab05ac"
$ blockstack namespace_reveal "hello" "6e50431b955fe73f079469b24f06480aee44e4519282686433195b3c4b5336ef01" "c244642ce0b4eb68da8e098facfcad889e3063c36a68b7951fb4c085de49df1b01" "b40dd1375ef63e5a40ee60d790ec6dccd06efcbac99d0cd5f3b07502a4ab05ac"
{
"status": true,
"success": true,
"transaction_hash": "b40dd1375ef63e5a40ee60d790ec6dccd06efcbac99d0cd5f3b07502a4ab05ac"
}
$
```
### Namespace reveal
@@ -91,7 +184,7 @@ describes the price curve.
This command is **interactive**. The command to invoke it is as follows:
```
$ blockstack namespace_reveal hello "$PAYMENT_PKEY" "$CREATOR_PKEY" "b40dd1375ef63e5a40ee60d790ec6dccd06efcbac99d0cd5f3b07502a4ab05ac"
|blockstack-test namespace_check| $ blockstack namespace_reveal hello "$PAYMENT_PKEY" "$CREATOR_PKEY" "b40dd1375ef63e5a40ee60d790ec6dccd06efcbac99d0cd5f3b07502a4ab05ac"
```
When running the command, you will see the namespace creation wizard prompt you
@@ -104,7 +197,7 @@ Price base: 4
Price bucket exponents: [15, 14, 13, 12, 11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0]
Non-alpha discount: 2
No-vowel discount: 5
Burn or receive fees? Receive to 1PJg2vkxRBJSJDugkcidDmdavs1eXZ6vTv
Burn or receive fees? Receive to mr6nrMvvh44sR5MiX929mMXP5hqgaTr6fx
Name price formula:
(UNIT_COST = 10.0 satoshi):
@@ -172,7 +265,7 @@ Once you're happy, you can begin to populate your namespace with some initial na
Blockstack 0.17 introduced the ability to create a namespace such that for the
first year of its existence (54595 blocks), all name registration and renewal
fees will be sent to the address of the _payment key_. In this example,
this is the address `1PJg2vkxRBJSJDugkcidDmdavs1eXZ6vTv`.
this is the address `mr6nrMvvh44sR5MiX929mMXP5hqgaTr6fx`.
The alternative is to
have all namespace fees sent to an unspendable burn address
@@ -195,7 +288,7 @@ that you wanted to give `example.hello` an initial zone file stored at
following command:
```
$ blockstack name_import example.hello 1CaajyWdX4ZSNxe2RKgjm2UAhuoFaMSTxg /var/blockstack/zone_files/example.hello "$CREATOR_PKEY"
|blockstack-test namespace_check| $ blockstack name_import example.hello 1CaajyWdX4ZSNxe2RKgjm2UAhuoFaMSTxg /var/blockstack/zone_files/example.hello "$CREATOR_PKEY"
```
Once a name is imported, it is public and resolvable. You can re-import the
@@ -226,6 +319,6 @@ names will disappear, and someone else will be able to register it.
To make a namespace `ready`, you use the creator private key as follows:
```
$ blockstack namespace_ready hello "$CREATOR_PKEY"
|blockstack-test namespace_check| $ blockstack namespace_ready hello "$CREATOR_PKEY"
```