Wallets
Using the node12.4.15+

Wallets

The two wallets of a node: the browser wallet at /wallet/, whose keys stay in your browser, and the node wallet you drive over RPC.

A node gives you two different wallets. They share nothing: not the keys, not the storage.

Browser walletNode wallet
Where/wallet/ on the node's web portJSON-RPC, with lotus-cli
KeysIn your browser, encryptedIn a wallet file in the node's data directory
Backup12-word recovery phrasebackupwallet
ForPeople: send, receive, tokens, votesOperators, scripts, mining payouts

Amounts are in XPI. One XPI is 1,000,000 satoshis, so XPI has 6 decimals. Mainnet addresses start with lotus_, testnet addresses with lotusT, regtest addresses with lotusR.

The browser wallet #

Open /wallet/ on your node, for example http://127.0.0.1:10604/wallet/. It is an installable web app (PWA): once loaded it opens without a network, and it updates when you say so.

Where the keys live #

The wallet creates a 12-word BIP39 recovery phrase in the browser, derives the keys and signs there. The node never sees a key.

  • The phrase is kept encrypted in the browser's storage for that site: AES-256-GCM, with a key derived from your passphrase by PBKDF2-HMAC-SHA256, 600,000 iterations.
  • Addresses derive at m/44'/10605'/0'/0/i.
  • The wallet locks itself after an idle time (5 minutes by default, set in Settings).
Warning

The 12 words are the only backup. Write them down at setup. If you lose the passphrase or the browser's data, only the words bring the wallet back; the node cannot help. To see them again: Settings, Export recovery phrase.

A wallet belongs to one site (one origin) in one browser. The same phrase restored on another node's /wallet/ gives the same addresses.

Over plain http the wallet only works on localhost or 127.0.0.1. Anywhere else it must be served over https: browsers disable the cryptography it needs otherwise, and the wallet shows a red banner.

What it does #

The sections are Overview, Send, Receive, Activity, Tokens, Social (RANK votes), BLOB, Contacts, Accounts, MuSig and Settings. Every send goes through a review screen.

Payment links open Send prefilled, and never send by themselves:

Text
/wallet/#/send?to=<address>&amount=<XPI>&label=<text>
/wallet/#/pay?uri=lotus:<address>?amount=<XPI>

What it calls #

The wallet talks only to the REST API of the node that served it:

  • public reads: /api/v1/chain, /api/v1/modules, /api/v1/addresses/{address} with /txs and /utxos, /api/v1/txs/{txid}, and the token, social and BLOB routes;
  • POST /api/v1/txs/broadcast with a signed transaction.

The node keeps no session and sets no cookie. /api/v1/ answers are never cached by the app; offline, the wallet shows the last balance it saw and refuses to sign or broadcast.

The same balance read, outside the wallet:

Shell
curl -s http://127.0.0.1:10604/api/v1/addresses/<address>
12.4.16+

Coming in 12.4.16: Taproot addresses in both wallets. In the browser wallet, Accounts, Address type: Legacy (P2PKH) or Taproot (P2TR). In the node wallet, getnewaddress "" taproot. Legacy stays the default.

The node wallet #

The node wallet is the wallet of lotusd itself. Use it from the machine that runs the node, with lotus-cli. The node's REST API never touches it, and /api/v1/rpc/ refuses every wallet command.

Create or load a wallet #

A new node has no wallet. Create one:

Shell
lotus-cli createwallet "main"

New wallets are stored in a single wallet.sqlite file (-walletdb chooses between sqlite and the older bdb). To encrypt the wallet from the start, give a passphrase as the fourth argument, or run encryptwallet later.

Shell
lotus-cli listwallets
lotus-cli listwalletdir
lotus-cli loadwallet "main"
lotus-cli unloadwallet "main"

createwallet and loadwallet take a load_on_startup argument that makes the node load the wallet at every start; -wallet=<name> on the command line or in lotus.conf does the same. When several wallets are loaded, name the one you mean with -rpcwallet=<name>.

-disablewallet starts the node without any wallet and without the wallet commands.

Receive and send #

Shell
lotus-cli -rpcwallet=main getnewaddress
lotus-cli -rpcwallet=main getbalance
lotus-cli -rpcwallet=main sendtoaddress "lotus_16PSJ..." 12.5
lotus-cli -rpcwallet=main listtransactions
  • getnewaddress returns a new address of the node's network.
  • sendtoaddress takes the address and an amount in XPI, and returns the transaction id.
  • With an encrypted wallet, unlock it first: walletpassphrase "<passphrase>" <seconds>.

The same calls over HTTP are JSON-RPC requests to /wallet/<name> on the RPC port, with the node's credentials: see RPC.

Back up #

Shell
lotus-cli -rpcwallet=main backupwallet /path/to/backup/main.bak

backupwallet safely copies the wallet file to a directory or a file while the node runs. Wallet files are in wallets/ under the data directory when that directory exists, otherwise in the data directory (-walletdir changes it). Back up before every upgrade.

On a public node #

When a node is published through a reverse proxy, the browser wallet and the node wallet share the path prefix /wallet/: GET requests serve the app, POST requests are JSON-RPC. The proxy must pass GET and HEAD only on /wallet/. The node itself refuses JSON-RPC that arrives with a reverse-proxy header unless -rpcallowforwarded=1. See Security.

Source share/www/docs/wallet.md in the lotusd repository
Checked against doc/wallet-pwa.md share/www/wallet/src/router.ts share/www/wallet/src/stores/vault.ts src/wallet/rpcwallet.cpp src/wallet/init.cpp src/wallet/load.cpp src/amount.h doc/xaddress.md