tenrai-wallet commands

tenrai-wallet alone opens a menu. It creates your wallet on the first start, then shows the balance, your address, sending and the transactions, and asks for approval before anything is sent. tenrai-wallet <command> does one thing and ends; tenrai-wallet <command> --help prints its options.

Defaults

Nothing has to be passed. Every option on this page replaces one of these defaults:

What	Default
Network	`mainnet`
Wallet file	Windows: `%LOCALAPPDATA%\Tenrai\wallet\<network>\wallet.vault`. Linux and macOS: `~/.tenrai/wallet/<network>/wallet.vault`
Password	Asked for at the prompt
Service	The node on this machine. While none answers there, the public Tenrai API
Settings	`wallet.vault.settings.json` beside the wallet file, written on first use

Shell

tenrai-wallet                 # the menu
tenrai-wallet balance
tenrai-wallet receive
tenrai-wallet send --to <address> --amount 1.25 --wait

A command that finds no wallet says where it looked and how to create one.

Options most commands take

Wallet file

Option	Meaning
`--file <FILE>`	Another encrypted wallet file than the one of this machine
`--password-file <FILE>`	File with the wallet password. A trailing line break is ignored
`--password <PASSWORD>`	The password itself, also read from `TENRAI_WALLET_PASSWORD`. Other programs on the machine can see a command line, so prefer the prompt or a file
`--passphrase-file <FILE>`	File with the recovery passphrase, when the wallet has one
`--account <N>`	Account number, default 0

The wallet takes the password from the first of these that is there: --password-file, --password or TENRAI_WALLET_PASSWORD, the file <wallet file>.pass, the keyboard. A new password has at least 12 characters.

Service

Option	Default	Meaning
`--service <SERVICE>`	the wallet's settings, else `node`	`node` is the node on this machine, `public` the Tenrai API, anything else a host, `HOST:PORT` or a URL
`--fallback <SERVICE>`	the wallet's settings, else `public`; none for the daemon	Used while the service cannot be reached or is busy: `public`, `node`, a URL, or `none` to switch it off
`--identity <HEX>`		Pins the service's identity before the first contact
`--network <NETWORK>`	`mainnet`	`mainnet`, `testnet`, `testnet100` or `development`, before or after the command. Each network has its own wallet folder and ports: `node` is `127.0.0.1:28701` on mainnet, 28706 on a testnet, 28711 on development. A service on another network is refused
`--trust-file <FILE>`	`<wallet file>.nodes.json`	Where pinned service identities are kept
`--ignore-payloads`	off	Payments arrive in full, but no payload is read or shown
`--send-when-not-synced`	off	Sends while the node is not synchronized, for a new chain or a lone test node. Otherwise a send waits up to 30 seconds for a node that is catching up, and the daemon answers `-32001` at once

On first contact the wallet pins the service's signing key. A changed key is refused until you remove its entry from the trust file.

The public API sees which addresses the wallet asks about; a node of your own does not. The wallet says so each time it uses the API in place of the node. --fallback none keeps it on the node.

Transactions

Option	Default	Meaning
`--fee <FEE>`	`normal`	`minimum`, `normal`, `priority`, or a total fee in TRAI
`--dry-run`	off	Shows the signed transaction and its fee, sends nothing
`--wait`	off	Waits until the transaction is final or failed

Output and logs

Option	Meaning
`--output human\|text\|json`	`human` prints lines for reading and is the default on a terminal. `text` prints `key=value` lines with every field and is the default when a program reads the output. `json` prints one JSON document
`-d, --debug`	Logs every service request
`--log-file <FILE>`	Also writes the log to a file
`--no-color`	Plain output

Create and restore

Command	What it does
`init`	Creates the wallet and prints the recovery phrase, the recovery fingerprint, the first address and where the file lies. It asks for the new password twice; `--generate-password` writes a random one to `<wallet file>.pass` instead, for a wallet that has to open unattended
`import --mnemonic-file <FILE>`	Restores a wallet from a file with the 24 words
`import --from-vault <FILE>`	Restores from a wallet file saved by the Tenrai Wallet or `export-vault`
`export-vault --out <FILE>`	Writes a copy of the wallet file
`export-recovery`	Prints the recovery phrase. Needs `--i-understand-this-exposes-my-recovery-phrase`

A wallet file is never replaced: init and import refuse a file that exists.

Addresses

Command	What it does
`receive`	The main address, or with `fresh` mode the first unused one. `--qr` prints a QR code
`new-address`	An address no earlier call returned. `--label` stores a note with it, such as a customer number
`address-mode single\|fresh`	`single` keeps payments and change on the main address; `fresh` uses a new address each time
`address`, `addresses`	Derives addresses offline: `--network`, `--account`, `--branch receive\|change`, `--index` or `--from` and `--count`
`address-words <ADDRESS>`	The six verification words of an address

Balance and history

Command	What it does
`balance`	Finalized balance, coins held by pending sends, change on its way back and incoming payments. `--funded` lists funded addresses, `--address` reads any address
`outputs`	Spendable coins. `--address` shows one address only
`history`	Pending transactions first, then finalized ones. `--limit`, default 50
`received --since <HEIGHT>`	Every payment received after a cut height, oldest first. `--change` includes returning change
`status --transaction <ID>`	State of one transaction. `--wait` follows it until it is final
`watch`	Prints payments and balance changes as they happen
`info`	The service's identity and network

Send

Command	What it does
`send --to <ADDRESS> --amount <TRAI>`	Pays one address or payment request
`send-many --recipient <ADDRESS>=<TRAI>`	Pays up to seven recipients in one transaction. Repeat `--recipient`; `<ADDRESS>=<TRAI>=<TEXT>` gives a recipient its own payload
`sweep --to <ADDRESS>`	Sends everything to one address
`burn --amount <TRAI>`	Pays the amount to the burn address, which takes it out of the supply. Asks first; `--yes` skips the question and is required without a terminal
`compound`	Merges the coins of each address into one coin of that address; an address with more coins than one scan reads merges into another address of the wallet

send and send-many also take:

Option	Meaning
`--payload-text <TEXT>`, `--payload-hex <HEX>`	Public payload, at most 1,024 bytes
`--request-id <ID>`	Your ID for this payment. Repeating it returns the first result instead of paying again. Also for `sweep` and `burn`
`--subtract-fee`	Takes the fee out of the amount
`--compound-first`	Merges coins first when the payment needs more than eight, then pays

Staking

Command	What it does
`validators`	All validators with ID, state, number of positions and owner
`stake --validator <ID> --amount <TRAI>`	Bonds stake to a validator, at least 1,000 TRAI
`positions`	Your positions with state, amount and time until they can be withdrawn
`unstake --position <ID>`	Starts the 10 days of unbonding
`withdraw --position <ID>`	Returns an unbonded position
`reward-address --position <ID> --to <ADDRESS>`	Sends a position's future rewards to another address

Validators

Command	What it does
`validator-register`	Registers a validator with `--amount`, at least 100,000 TRAI, and `--overlay-endpoint-hex`. `--commission-bps` accepts 0 to 1,000 in steps of 10 and defaults to 500. Optional `--reward-address`, `--consensus-key-index`
`validator-key-export`	Writes the consensus key for the node to `--validator-key-file`, encrypted with `--validator-key-password-file`
`validator-heartbeat-fee-key-export`	Writes the heartbeat fee key to `--heartbeat-fee-key-file`, encrypted with `--heartbeat-fee-key-password-file`, and prints its address
`validator-heartbeat --validator <ID>`	Sends a heartbeat by hand
`validator-rotate`	New consensus key and endpoint: `--validator`, `--consensus-key-index`, `--overlay-endpoint-hex`
`validator-endpoint`	Schedules an endpoint change without rotating the consensus key: `--validator`, active `--consensus-key-index`, `--overlay-endpoint-hex`. It activates two finalized epochs later
`validator-commission --validator <ID> --commission-bps <0..1000, step 10>`	Schedules one commission change for the finalized epoch boundary 14 epochs later
`validator-exit --validator <ID>`	Leaves the validator set; every position bonded to it starts unbonding

Consensus keys use the indexes 2147418112 to 2147483647; the default is the highest. Run a validator shows the whole procedure.

Address ownership

Command	What it does
`proof-request --address <ADDRESS> --request <FILE>`	Writes a request for the owner to answer. `--valid-for` seconds, default 600
`prove-address --request <FILE> --proof <FILE>`	Answers a request with the key of the requested address
`verify-address-proof --proof <FILE>`	Checks a proof; with `--request` also that it answers that request. Exits with 1 when it does not hold

Multisig

2-of-3 and 3-of-5 addresses. Each member keeps their own wallet file; packages carry no secrets.

Each member prints a public key from their own wallet:

Shell

tenrai-wallet multisig-member --file member-a.vault --password-file member-a.pass

Create the address from all member keys:

Shell

tenrai-wallet multisig-create --threshold 2 --member-public-key <key A> \
  --member-public-key <key B> --member-public-key <key C> --descriptor team.trmsig

Build a payment:
Shell
```
tenrai-wallet multisig-build --descriptor team.trmsig --package unsigned.trmpkg \
  --recipient <address>=1.25 --change <change address>
```
When the address holds too many small coins for a payment, merge them first:
Shell
```
tenrai-wallet multisig-consolidate-build --descriptor team.trmsig \
  --package consolidation.trmpkg
```
The package spends as many finalized coins as one transaction can carry, at most --max-inputs (default 16), and pays them back to the same multisig address as one coin, less the fee. Sign, combine and submit it like a payment, and wait until it is final before you spend the new coin.

Enough members sign, each with their own wallet:

Shell

tenrai-wallet multisig-sign --file member-a.vault --password-file member-a.pass \
  --package unsigned.trmpkg --signed-package a.trmpkg

Combine the signed packages and send:

Shell

tenrai-wallet multisig-combine --package a.trmpkg --package b.trmpkg --combined-package complete.trmpkg
tenrai-wallet multisig-submit --package complete.trmpkg

multisig-inspect and multisig-package-inspect show a descriptor or a package before anyone signs. Once every member key is registered on the chain, packages refer to the keys instead of carrying them and cost less; the review shows which form a package uses.

Daemon

tenrai-wallet daemon runs the wallet as a service with JSON-RPC and WebSocket events, see Accept and send payments. Without options it serves the wallet of this machine on 127.0.0.1. It runs unattended, so it takes the password from --password-file, TENRAI_WALLET_PASSWORD or <wallet file>.pass, and it stays on its node: it waits for it and uses another service only when --fallback names one.

Option	Default	Meaning
`--listen <IP[:PORT]>`	`127.0.0.1:28703`	Address of the API; with `--network testnet` port 28708, `development` 28713
`--token-file <FILE>`	`<wallet file>.token`	Bearer token, created on the first start
`--allow-remote`	off	Allows a listen address outside this machine; put TLS in front
`--auto-compound <N>`	off	Compounds once more than N coins are spendable
`--auto-sweep-to <ADDRESS>`	off	Forwards every finalized payment to this address
`--auto-sweep-min <TRAI>`	0	Forwards only from this amount on
`--auto-fee <FEE>`	`normal`	Fee of automatic compounds and sweeps
`--confirmations <N>`	off	Also reports each payment after N cuts, at least 2

Files beside the wallet file

File	Content
`.settings.json`	Service, fallback, `ignore_payloads` and `send_when_not_synced` of this wallet, and the fingerprint of the wallet it opens; the command line wins
`.pass`	The password, when `init --generate-password` wrote it or you put it there
`.nodes.json`	Pinned service identities
`.pending.json`, `.pending/`	Pending sends and the coins they hold
`.addresses.json`	Handed-out addresses and their labels
`.requests.json`	Request IDs and their transactions
`.token`	Daemon API token
`.operation.lock`	Keeps the daemon and single commands from spending the same coins

Each name starts with the wallet file's name, for example wallet.vault.nodes.json.