Beam command line (CLI) guide
The "official" Beam command line reference guide!
The command line is the most reliable method of using Beam wallets and certain features (Registering CAs, Lightning Payments, Beam Shaders) can only perform on the command line. Available for macOS, Windows, and Linux.
Due to Beam's LelantusMW protocols, the private keys of Beam wallets record the user's UTXO balance on the blockchain, while transaction histories, addresses, and other wallet metadata are stored locally on each device.
Beam allows users to run a full node and interact with it via the command line.
Getting started
This section uses Linux and macOS commands; Windows users, please substitute./beam-wallet
with beam-wallet.exe
and Windows Command Prompts where necessary.
Creating a new Beam wallet
To create a new wallet, enter the following command:
The-wallet init
command will ask users to create a wallet password:
Create a strong wallet password and keep your password secret! Anyone who has your wallet password will have access to your funds! Wallet passwords protect your wallet.db
files that store all your crucial wallet metadata.
After creating your wallet password, the-wallet init
command output should resemble the following:
Therules signature
is a hash of the current node configuration that determines compatibility between different versions of nodes and wallets.
Write down your seed phrase! Keep your seed phrase secret, and never share your seed phrase with anyone!
Your seed phrase is the only way you (or anybody) can access your funds. Your seed phrase is not linked to your email or phone number. If you forget your wallet password or lose your device, the only way to restore your wallet is through your seed phrase!
Please do not write your seed phrase down electronically, take a screenshot or store it anywhere vulnerable to cyber attacks. Pen and paper are unhackable and recommended. Make multiple copies of your seed phrase and store them somewhere safe.
Restoring CLI wallet from seed phrase
Restoring Beam coins from an old wallet seed phrase requires users to run their own node and owner_key
.
To begin restoring your CLI wallet, first create a new wallet by entering the following command:
Now export your owner_key
from your Beam wallet. Enter the following command:
Now that you have exported the owner_key
, you can run your own node by entering the following command:
Once the node has synchronized, connect your wallet to the node and update your wallet database by entering the following command:
Once your wallet has synched with the Beam network, enter -wallet info
command to check the wallet status:
Exporting secret keys
Exporting miner key
Theminer_key
is a secret key that miners can use to collect their miner rewards.
To export yourminer_key
, enter the following command:
Enter your wallet password.
The output should resemble the following:
Keep yourminer_key
secret! Anyone with theminer_key
can retrieve the Miner Rewards associated with said keys.
Exporting owner key
Anowner_key
connects all the nodes mining under that key and communicates with all the other nodes on the network of accumulated miner rewards. If a scenario occurs where a user has multiple mining nodes under oneowner_key
, the user would only need to connect to a single node to collect the miner rewards.
Most cryptocurrencies allow users to connect mining nodes to a single address; however, the Mimblewimble protocol has no addresses. Unique blinding factors are deterministically derivative from themaster_key
code into the miner rewards tagged by a singleowner_key
.
While anowner_key
cannot access users' funds, it allows users to view all the coins mined by every mining node associated with said key. Keep yourowner_key
secret.
To exportowner_key
from your Beam wallet, enter the following command:
Enter your wallet password.
Sample output for this command should look like this:
Printing wallet info
Printing your wallet info will give you a snapshot of your wallet, including wallet balance, block height, current state ID, available balance, total groth, and more.
To print the current status of your wallet, enter the following command:
Enter your wallet password.
The output should resemble the following:
Transaction history
Users can view their transaction history with the--tx_history
tag:
View transaction details
To view transaction details, add the--tx_id
tag:
Receiving Beam
Synching with a specific node
Users must connect to a specific node before they can start receiving Beam coins.
To connect to a specific node, enter the following command:
Enter your wallet password.
The output should resemble the following:
Once your wallet syncs with the specific node, your wallet will automatically scan the network for incoming transactions via SBBS addresses.
Receiving Beam coins
To Receive Beam coins, send your wallet address to the sender over a secure channel such as email or Telegram.
All incoming transactions will be viewable in your wallet logs and command terminal.
The output should be similar to the following:
Sending Beam
Things to consider:
You can split a large UTXO by creating a transaction and sending a portion of the UTXO to yourself. Use the
-wallet send
command to send the required amount to your own SBBS wallet address. A transaction fee will still be required.
To Send Beam coins, enter the following command:
The output should resemble the following:
Sending a specific UTXO
For certain transactions, the user might consider sending a specific UTXO.
Print wallet info
To find a specific UTXO, enter the-wallet info
command:
Sending UTXO
Review and select the UTXO you wish to send.
Enter the -wallet send
command with a--utxo
tag, (use a comma to separate multiple UTXO IDs):
Cancel and delete a transaction
There might be an instance where it is necessary to cancel or delete an unsuccesful transaction.
Canceling a transaction
First, print your wallets transaction history using --tx_history
command:
After locating the--tx_id
t you wish to cancel, enter the following command:
Deleting a transaction
To delete a canceled transaction, enter the following command:
Create a new wallet address
Create a regular address
To create a regular address, enter the following command:
Enter your wallet password.
Sample output should be similar to the following:
Create an SBBS address
To create a new SBBS address, enter the following command:
Enter your wallet password.
Sample output should be similar to following:
Create an Offline address
It is essential to provide the number of payments (i.e., vouchers). If the payments reach zero, the Sender wallet will automatically request more payments to the Receiver wallet using SBBS. If the Receiver's wallet is online within 12 hours of the request (until the SBBS message expires), it will send 30 more offline payment vouchers to the Sender. Otherwise, the Sender will receive notification that there are no more vouchers and need to request another offline address via an external channel.
To create an Offline address, enter the following command:
Enter your wallet password.
The output should be similar to following:
Locate Public-Offline address
A Public-Offline address is unique address to your Beam wallet and never expires. Public Offline addresses are a little less secure in one aspect: the Sender can potentially see when the Receiver spends the funds sent to this address (though, of course, not to whom or how much). We recommend using this address for donations or a Receiver wallet that is rarely online.
To locate your Beam wallet's Public-Offline address, enter the following command:
Enter your wallet password
The output should be similar to the following:
Print address list
To print your Beam wallet address list, enter the following command:
The output should be similar to the following:
Change address expiry date
Beam wallets create a new wallet address for every transaction, It is possible however, to extend the expiration (24 hours) for an old address.
Extending the expiration date for a single wallet address
To extend your wallet address expiration date, enter the following command:
Extending the expiration for all addresses in your Beam wallet
To extend your wallets existing addresses, use the previous command, omitting the --address
tag.
Choosing an expiration date
Wallet addresses provided users with three different expiration date options:
Never: address expiration date will never expire.
Auto: wallet address expiration date will extend for an additional 24 hours before expiring.
Now: the wallet address will be expire immediately and will no longer be usable.
Enter the following command:
Export and import wallet metadata
If you have previously created a Beam wallet, you can recover your funds by restoring your wallet from your 12-word seed phrase. However, your wallet data (transaction history, contacts, addresses) is always stored locally onto yourwallet.db
file.
Exporting wallet metadata
To export yourwallet.db
file, enter the following command:
Importing wallet metada
To import yourwallet.db
file, enter the following command:
Proof of transaction
SinceBeam 1.1.4194
, the Receiver wallet has automatically signed proof of received transaction before sending it to the Sender. Upon request, the sender can generate proof of transaction.
When Sending Beam coins, adding the–payment_proof_required=1
tag will require the Receiver to send the payment proof to Sender.
Print transactions list
Locate the--tx_id
. Enter the following command:
Get payment proof
After locating the--tx_id
, enter the following command:
The output should resemble the following:
Send payment proof
Copy, paste and send the payment proof (exported form
) to the Receiver.
The payment proof (from the above example) should resemble the following:
Verifying the payment proof
The Receiver can verify the payment proof by entering the following command:
Rescan wallet
Beam wallets regularly monitor the blockchain and sync new information with the wallet. If you suspect your balance, transaction, or UTXO status is not updated, the -wallet rescan
command will sych your wallet with the blockchain's latest state.
In order to rescan the CLI wallet please follow the steps below:
Run the node with your owner key
Running a node with your owner key will verify if your wallet is synchornized with the network.
To run node with owner key, enter the following command:
Rescan the blockchain
To rescan the blockchain, enter following command:
Listen for updates
To listen for any updates to the node, enter the-wallet listen
command:
Wait for synchronization
After your wallet and node have syncronized, recheck your wallet balance, transaction histories by entering the-wallet info
command:
Last updated