User-Guide

From Snowblossom Wiki
Jump to: navigation, search

Config Files

  • Each component uses a config file - Config Files
  • By default, they're located in configs/

All programs that take config files support a parameter to allow config entries to be specified or overridden by environment variables. In config:

env_override_prefix=snowblossom_

Then any configuration entry can be read from the environment rather than the config file.

$ export snowblossom_wallet_path=wallets/teapot-new9
$ sbc client-generic.conf
Aug 20, 2018 9:45:52 PM snowblossom.client.SnowBlossomClient <init>
INFO: Starting SnowBlossomClient version 1.3.2
Aug 20, 2018 9:45:52 PM snowblossom.lib.NetworkParams loadFromConfig
INFO: Using network teapot - testnet
Aug 20, 2018 9:45:52 PM snowblossom.client.Purse <init>
WARNING: Directory wallets/teapot-new9 does not contain wallet, creating new wallet
Total: 0.000000 (0.000000 pending) (0.000000 spendable)
Wallet Keys: 20, Addresses: 20, Fresh pool: 20
  1of1 ECDSA: 20
Here is an unused address:
snowtest:5v6q5s0038c2dn4q4zran5zj66uugs0plw8jpwrg

Node

Nodes store the blockchain and work with clients and miners.

  • Your node should always be running
  • Everything else relies on your node
  • You can configure 1 node, and modify your configs to connect there.



Client

Manage your wallet, addresses and keys. BACK UP YOUR WALLET

The new client is super cool.

Key Pool

The client now maintains a pool of unused addresses and generates more as needed. The default key pool size is 100. You can change it with the key_pool_size parameter in your config.

Wallet Files

As you may have noticed, the client config has always specified a directory that contains the wallet files rather than a specific wallet file. This is why. Now wallets are sometimes multiple files. This allows the client to quickly write any new changes (like a new key or marking an address as used) to a new file. If that gets interupted or fails that is completely fine because the existing files are still there. On startup, a client reads all the files present in the directory, merges them in memory and writes out a new file of everything those source files contains. Only after that new complete merge is created, the old files can be safely removed.

This all happens automatically, you don't have to worry about it. If you look in your wallet directory you might see something like this:

  • snow-2_05797c77068c.wallet
  • snow-2_1fda3b142533.wallet

or just a single file.

Upgrading

To upgrade from the old wallet file, you don't need to do anything. The new client will automatically read the old wallet.db, generate the new keypool and move on.

Downgrading

If you wish to go back to the old client, run the new client a few times until it merges everything into a single file and rename that file back to wallet.db. Then you can run the old client without trouble.

Future Upgrades

Each file has a built in version number, (also shown as the number after 'snow-'). If a client reads a file with a version number it doesn't recognize, it reads it and merges it as normal but does not delete the new file. It assumes the new versioned file has some new fields that it doesn't know how to operate on and leaves it. This way it will still be there when the user runs the new client again that knows how to read and merge it.

This is all automatic, you don't need to worry about it.

Syncing

One awesome advantage of doing the wallet files in this way is that you can rsync these around or run multiple clients at once. Any changes by any clients will be written to new file names and the merge will happen just fine when a client reads those.

This means if you are running the same wallet on multiple computers you can use any syncing mechanism to copy the files around. Unison, rsync, dropbox, etc. (Just don't do rsync --delete)

Commands

  • balance - show balance of all addresses
  • send <amount> <destination>
  • monitor - show balance and wait and repeat
  • getfresh [mark_used] [generate_now] - Get an unused address.
    • If mark_used is true, the returned address will be marked as used so it won't get given out or used as change.
    • If generate now is true, then a completely new address will be generated right now rather than one from the keypool.
  • export <file> - export wallet to a json file
  • import <file> - import json file, merge into wallet
  • rpcserver - JSON-RPC-Commands. This is done as an explicit command as a security feature to avoid starting one accidentally and maybe not knowing about it. Requires the following things in the config: rpc_port, rpc_username, rpc_password

Sending

Open a terminal, or run cmd-here.bat and type:

  • Windows: client.bat send <amount> <snow:address>
  • Linux: client.sh send <amount> <snow:address>