Skip to content

Commit 8710354

Browse files
werner-stacksgitbook-bot
authored andcommitted
GITBOOK: Signer Quickstart: 4.0.1 outputs, PoX-5 final step, link and style fixes
1 parent 93fcb57 commit 8710354

1 file changed

Lines changed: 86 additions & 44 deletions

File tree

‎docs/operate/run-a-signer/signer-quickstart.md‎

Lines changed: 86 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -3,24 +3,20 @@
33
{% hint style="info" %}
44
**Current Signer and Stacks Node Versions**
55

6-
**Stacks Signer - latest**
6+
**Stacks Signer**
77

8-
* [Docker Image](https://hub.docker.com/layers/blockstack/stacks-signer/latest)
8+
* [Container image](https://github.com/stacks-network/stacks-core/pkgs/container/stacks-signer) (`ghcr.io/stacks-network/stacks-signer`)
99
* [GitHub Release](https://github.com/stacks-network/stacks-core/releases/latest)
1010

11-
**Stacks Node - latest**
11+
**Stacks Node**
1212

13-
* [Docker Image](https://hub.docker.com/layers/blockstack/stacks-core/latest)
13+
* [Container image](https://github.com/stacks-network/stacks-core/pkgs/container/stacks-core) (`ghcr.io/stacks-network/stacks-core`)
1414
* [GitHub Release](https://github.com/stacks-network/stacks-core/releases/latest)
1515
{% endhint %}
1616

17-
If you want to get up and running as an active signer as quickly as possible, here is a list of the commands you need to run and actions to take.
17+
The commands below take a fresh Ubuntu machine to a running signer and Stacks node.
1818

19-
If you are not familiar with how signing works yet, be sure to check out the [Signing concept guide](https://github.com/stacks-network/docs/blob/master/docs/learn/block-production/signing.md).
20-
21-
{% hint style="danger" %}
22-
The CLI examples below may show outdated release versions. For the latest releases, always refer to the links above in the top info block.
23-
{% endhint %}
19+
If you are not familiar with how signing works yet, be sure to check out the [Signing concept guide](https://docs.stacks.co/learn/block-production/signing).
2420

2521
{% stepper %}
2622
{% step %}
@@ -64,7 +60,7 @@ stx make_keychain -t | jq > ~/stacks-signer/keychain.json
6460
{% endtab %}
6561
{% endtabs %}
6662

67-
The account file previously created looks like this:
63+
The account file looks like this:
6864

6965
```json
7066
{
@@ -88,12 +84,11 @@ From this file, you'll need the `privateKey` value.
8884

8985
**Download the stacks-signer binary**
9086

91-
Official binaries are available from the [Stacks Core releases page on Github](https://github.com/stacks-network/stacks-core/releases/latest). Each release includes pre-built binaries. Download the [latest signer release ZIP file](https://github.com/stacks-network/stacks-core/releases/latest) for your server’s architecture and decompress it. Inside of that folder is a `stacks-signer` binary.
87+
Download the [latest signer release ZIP file](https://github.com/stacks-network/stacks-core/releases/latest) for your server's architecture and decompress it. Inside that folder is a `stacks-signer` binary.
9288

9389
Assuming a `Linux x64 glibc` machine, the commands to download and uncompress the signer binary look like this:
9490

9591
```bash
96-
# The CLI examples below may show outdated release versions.
9792
# Enter the signer directory
9893
cd ~/stacks-signer
9994

@@ -106,12 +101,12 @@ unzip linux-glibc-x64.zip
106101

107102
**Create the configuration file**
108103

109-
Create the configuration file required to start the signer (be sure to replace `<your_token>` and `<your_private_key>` with your auth token and private key values):
104+
Create the configuration file required to start the signer (be sure to replace `<your_token>` and `<your_private_key>` with your auth token and private key values). Every option is documented in [Signer Configuration](https://docs.stacks.co/reference/node-operations/signer-configuration).
110105

111106
{% tabs %}
112107
{% tab title="Mainnet" %}
108+
{% code title="signer-config.toml" %}
113109
```bash
114-
# The CLI examples below may show outdated release versions.
115110
# Set environment variables
116111
AUTH_TOKEN=<your_token> # Used for signer-node authentication
117112
PRIVATE_KEY=<your_private_key> # privateKey from Step 1, this is the signer's private key
@@ -129,9 +124,11 @@ block_proposal_timeout_ms = 180000
129124
tenure_idle_timeout_secs = 120
130125
EOF
131126
```
127+
{% endcode %}
132128
{% endtab %}
133129
134130
{% tab title="Testnet" %}
131+
{% code title="signer-config.toml" %}
135132
```bash
136133
# Set environment variables
137134
AUTH_TOKEN=<your_token> # Used for signer-node authentication
@@ -149,26 +146,28 @@ metrics_endpoint = "127.0.0.1:9154"
149146
block_proposal_timeout_ms = 180000
150147
EOF
151148
```
149+
{% endcode %}
152150
{% endtab %}
153151
{% endtabs %}
154152
155153
**Verify the setup**
156154
157-
To ensure the signer has been set up correctly, you can run the following commands:
155+
Check the version and the config file:
158156
159157
```bash
160-
# The CLI examples below may show outdated release versions.
161158
# Verify the signer's version
162159
~/stacks-signer/stacks-signer --version
163160
164161
# Output:
165-
stacks-signer stacks-signer signer-3.1.0.0.5.0 (release/signer-3.1.0.0.5.0:513dbc5, release build, linux [x86_64])
162+
stacks-signer 4.0.1 (62e03cc, release build, linux [x86_64])
166163
167164
# Verify the config file
168165
~/stacks-signer/stacks-signer check-config -c ~/stacks-signer/signer-config.toml
169166
170167
# Output:
168+
Signer version: stacks-signer 4.0.1 (62e03cc, release build, linux [x86_64])
171169
Config:
170+
172171
Stacks node host: 127.0.0.1:20443
173172
Signer endpoint: 127.0.0.1:30000
174173
Stacks address: SP1G... # address from keychain file
@@ -177,11 +176,12 @@ Network: mainnet # or testnet
177176
Chain ID: 0x1 # or 0x80000000 for testnet
178177
Database path: /home/admin/stacks-signer/data/signer.sqlite
179178
Metrics endpoint: 127.0.0.1:9154
179+
Dry run: false
180180
```
181181
182182
**Start the signer**
183183
184-
If the outputs of the previous commands are correct, you can proceed and start the signer:
184+
If the output is correct, start the signer:
185185
186186
```bash
187187
~/stacks-signer/stacks-signer run -c ~/stacks-signer/signer-config.toml
@@ -191,7 +191,7 @@ If the outputs of the previous commands are correct, you can proceed and start t
191191
{% step %}
192192
#### Optional: Set up a Bitcoin node (strongly recommended)
193193
194-
In order to optimize signer health and performance, we highly recommend setting up your own Bitcoin node rather than relying on a third-party node.
194+
Run your own Bitcoin node rather than relying on a third-party one. A hosted node can leave your Stacks node behind tip and unsynced.
195195
196196
We have created guides for running both a [full Bitcoin node](../run-a-node/run-a-bitcoin-node.md) and a [pruned Bitcoin node](../run-a-node/run-a-pruned-bitcoin-node.md) you can follow.
197197
{% endstep %}
@@ -201,12 +201,11 @@ We have created guides for running both a [full Bitcoin node](../run-a-node/run-
201201
202202
**Download the stacks-node binary**
203203
204-
Official binaries are available from the [Stacks Core releases page on Github](https://github.com/stacks-network/stacks-core/releases/latest). Each release includes pre-built binaries. Download the [latest node release ZIP file](https://github.com/stacks-network/stacks-core/releases/latest) for your server’s architecture and decompress it. Inside of that folder is a `stacks-node` binary.
204+
Download the [latest node release ZIP file](https://github.com/stacks-network/stacks-core/releases/latest) for your server's architecture and decompress it. Inside that folder is a `stacks-node` binary.
205205
206206
Assuming a `Linux x64 glibc` machine, the commands to download and uncompress the node binary look like this:
207207
208208
```bash
209-
# The CLI examples below may show outdated release versions.
210209
# Enter the node directory
211210
cd ~/stacks-node
212211
@@ -219,18 +218,16 @@ unzip linux-glibc-x64.zip
219218
220219
**Create the configuration file**
221220
222-
Create the configuration file required to start the node (be sure to replace `<your_token>` with your auth token value):
221+
Create the configuration file required to start the node (be sure to replace `<your_token>` with your auth token value). Every option is documented in [Stacks Node Configuration](https://docs.stacks.co/reference/node-operations/readme-1).
223222
224223
{% tabs %}
225224
{% tab title="Mainnet" %}
226225
{% hint style="warning" %}
227-
For mainnet, we strongly recommended that you run your own bitcoin node (you can follow guides on how to run a [full Bitcoin node](https://docs.stacks.co/guides-and-tutorials/nodes-and-miners/run-a-bitcoin-node) or a [pruned Bitcoin node](https://docs.stacks.co/guides-and-tutorials/nodes-and-miners/run-a-pruned-bitcoin-node)) in order to ensure you have no connection issues when downloading bitcoin blocks. A hosted bitcoin node may cause your stacks node to fall behind tip and remain unsynced.
228-
229226
If you run your own bitcoin node, you'll have to update `peer_host` and optionally add `rpc_port`, `peer_port`, `username` and `password` fields under the `[burnchain]` section of the node's configuration file.
230227
{% endhint %}
231228
229+
{% code title="node-config.toml" %}
232230
```bash
233-
# The CLI examples below may show outdated release versions.
234231
# Set environment variables
235232
AUTH_TOKEN=<your_token> # Used for signer-node authentication, same token as the one set up in the signer configuration
236233
@@ -257,9 +254,11 @@ endpoint = "127.0.0.1:30000"
257254
events_keys = ["stackerdb", "block_proposal", "burn_blocks"]
258255
EOF
259256
```
257+
{% endcode %}
260258
{% endtab %}
261259
262260
{% tab title="Testnet" %}
261+
{% code title="node-config.toml" %}
263262
```bash
264263
# Set environment variables
265264
AUTH_TOKEN=<your_token> # Used for signer-node authentication, same token as the one set up in the signer configuration
@@ -270,16 +269,20 @@ cat <<EOF> ~/stacks-node/node-config.toml
270269
working_dir = "$HOME/stacks-node/data"
271270
rpc_bind = "127.0.0.1:20443"
272271
p2p_bind = "0.0.0.0:20444"
273-
bootstrap_node = "029266faff4c8e0ca4f934f34996a96af481df94a89b0c9bd515f3536a95682ddc@seed.testnet.hiro.so:30444"
272+
bootstrap_node = "0348af7ce1b224476e8f042727af3f84dcf49a69bb3c9dd2a1afaa783acfffb729@seed.testnet.hiro.so:20444"
274273
prometheus_bind = "127.0.0.1:9153"
275274
stacker = true
276275
pox_sync_sample_secs = 30
277276
always_use_affirmation_maps = true
278277
require_affirmed_anchor_blocks = true
278+
pox_5_sbtc_contract = "SN3VMHXEN64ZZF71JQ5VESXDWTR301XTTXGF4J8F1.sbtc-token"
279+
pox_5_sbtc_registry_contract = "SN3VMHXEN64ZZF71JQ5VESXDWTR301XTTXGF4J8F1.sbtc-registry"
280+
pox_5_bond_admin = "ST1V2ASRWGR81W7GBN1Z4W2JQKXJWCADPVZG30X45"
279281
280282
[burnchain]
281283
mode = "krypton"
282284
peer_host = "bitcoin.regtest.hiro.so"
285+
rpc_port = 18443
283286
peer_port = 18444
284287
pox_prepare_length = 100
285288
pox_reward_length = 900
@@ -308,6 +311,38 @@ amount = 10000000000000000
308311
address = "ST2TFVBMRPS5SSNP98DQKQ5JNB2B6NZM91C4K3P7B"
309312
amount = 10000000000000000
310313
314+
[[ustx_balance]]
315+
address = "ST31XHNM0GZ2K978FPP4QA3STNQ73Z8C9G9MJEPK2"
316+
amount = 10000000000000000
317+
318+
[[ustx_balance]]
319+
address = "ST1B38CGQRPXEMRH7B66VXTS22DQTNMSW4YJJ7QK1"
320+
amount = 10000000000000000
321+
322+
[[ustx_balance]]
323+
address = "STDMN71Z0H9EF8CRKAWTGBB5YS0BNV26HZ79QFFP"
324+
amount = 1000000000000000
325+
326+
[[ustx_balance]]
327+
address = "ST1E0PSCH72JMQH9QCH293ZTEEH7BPA40Y3F39XQ"
328+
amount = 10000000000000
329+
330+
[[ustx_balance]]
331+
address = "ST3QBTK0Q438YVNX8EG6Z85HN0WKQPXYT25H5SPPK"
332+
amount = 10000000000000
333+
334+
[[ustx_balance]]
335+
address = "ST10BX04F9PC6N1WBXKW3H7CG0NS0A3PK650T3P3R"
336+
amount = 10000000000000
337+
338+
[[ustx_balance]]
339+
address = "ST3AF1BBQAFSFCM8K4ZBR1FBXP3P8J1CKGSGDHWR5"
340+
amount = 100000000000000
341+
342+
[[ustx_balance]]
343+
address = "STHY13V44422NAN6D3NSJPY9CDR3ED1M6HH9WZ6Y"
344+
amount = 10000000000000
345+
311346
[[burnchain.epochs]]
312347
epoch_name = "1.0"
313348
start_height = 0
@@ -342,31 +377,36 @@ start_height = 6
342377
343378
[[burnchain.epochs]]
344379
epoch_name = "3.0"
345-
start_height = 1_900
380+
start_height = 1802
346381
347382
[[burnchain.epochs]]
348383
epoch_name = "3.1"
349-
start_height = 2000
384+
start_height = 1803
350385
351386
[[burnchain.epochs]]
352387
epoch_name = "3.2"
353-
start_height = 71525
388+
start_height = 1804
354389
355390
[[burnchain.epochs]]
356391
epoch_name = "3.3"
357-
start_height = 109280
392+
start_height = 1805
358393
359394
[[burnchain.epochs]]
360395
epoch_name = "3.4"
361-
start_height = 159350
396+
start_height = 1806
397+
398+
[[burnchain.epochs]]
399+
epoch_name = "4.0"
400+
start_height = 2702
362401
EOF
363402
```
403+
{% endcode %}
364404
{% endtab %}
365405
{% endtabs %}
366406
367407
**Optional: Start the node with a data archive**
368408
369-
You can [download a chainstate archive](https://archive.hiro.so/) in order to quickly sync your node, otherwise it will take a long time to get up-to-date with the other nodes.
409+
You can [download a chainstate archive](https://archive.hiro.so/) instead of syncing from genesis.
370410
371411
{% tabs %}
372412
{% tab title="Mainnet" %}
@@ -404,29 +444,28 @@ rm testnet-stacks-blockchain-latest.tar.gz
404444
405445
**Verify the setup**
406446
407-
To ensure the node has been set up correctly, you can run the following commands:
447+
Check the version and the config file:
408448
409449
```bash
410-
# The CLI examples below may show outdated release versions.
411450
# Verify the node's version
412451
~/stacks-node/stacks-node version
413452
414453
# Output:
415-
INFO [1738695915.769633] [testnet/stacks-node/src/main.rs:278] [main] stacks-node 3.1.0.0.5 (release/3.1.0.0.5:513dbc5, release build, linux [x86_64])
416-
stacks-node 3.1.0.0.5 (release/3.1.0.0.5:513dbc5, release build, linux [x86_64])
454+
INFO [1786366428.758607] [stacks-node/src/main.rs:329] [main] stacks-node 4.0.1 (62e03cc, release build, linux [x86_64])
455+
stacks-node 4.0.1 (62e03cc, release build, linux [x86_64])
417456
418457
# Verify the node's config
419458
~/stacks-node/stacks-node check-config --config ~/stacks-node/node-config.toml
420459
421460
# Output:
422-
INFO [1738695915.769633] [testnet/stacks-node/src/main.rs:278] [main] stacks-node 3.1.0.0.5 (release/3.1.0.0.5:513dbc5, release build, linux [x86_64])
423-
INFO [1729788064.913175] [testnet/stacks-node/src/main.rs:318] [main] Loading config at path /home/admin/stacks-node/node-config.toml
424-
INFO [1729788064.969551] [testnet/stacks-node/src/main.rs:331] [main] Loaded config!
461+
INFO [1786366428.987308] [stacks-node/src/main.rs:329] [main] stacks-node 4.0.1 (62e03cc, release build, linux [x86_64])
462+
INFO [1786366428.987352] [stacks-node/src/main.rs:359] [main] Loading config at path /home/admin/stacks-node/node-config.toml
463+
INFO [1786366429.090617] [stacks-node/src/main.rs:372] [main] Loaded config!
425464
```
426465
427466
**Start the node**
428467
429-
If the outputs of the previous commands are correct, you can proceed and start the node:
468+
If the output is correct, start the node:
430469
431470
```bash
432471
~/stacks-node/stacks-node start --config ~/stacks-node/node-config.toml
@@ -440,10 +479,13 @@ If you would like to learn more about monitoring your signer and its correspondi
440479
{% endstep %}
441480
442481
{% step %}
443-
#### Next Steps: Stacking
482+
#### Next Steps: Register Your Signer
483+
484+
Once your signer and Stacks node are running and verified, this signer key has to be bound to a signer-manager contract before stakers can route to it. PoX-5 replaces the PoX-4 per-transaction signer signature with a standing on-chain grant:
444485
445-
Once your signer and Stacks node are running and verified, the next step is to stack STX to register your signer for a reward cycle. See the [Stacking STX](../staking-stx/) guide for complete instructions on solo stacking, delegated stacking, and managing your keys.
486+
1. You produce a SIP-018 signature off-chain with this signer's private key, binding it to a specific signer-manager and an `auth-id`. See [Generate a Signer Signature](../staking-stx/generate-signer-signature.md).
487+
2. That signer-manager submits `grant-signer-key` carrying your signature, then calls `register-signer` to bind itself to your key on chain.
446488
447-
You will need to [generate a signer signature](../staking-stx/generate-signer-signature.md) before making any stacking transaction.
489+
See [Staking STX](../staking-stx/) for the full PoX-5 staking flow, and [Key and Address Rotation](../staking-stx/key-and-address-rotation.md) for changing this key later.
448490
{% endstep %}
449491
{% endstepper %}

0 commit comments

Comments
 (0)