Skip to main content

Managing Accounts in Your Wallet

The wallet command is used to manage accounts in your wallet. The wallet can contain file-based accounts which are stored along your Oasis CLI configuration, or a reference to an account stored on your hardware wallet.

The following encryption algorithms and derivation paths are supported by the Oasis CLI for your accounts:

  • ed25519-adr8: Ed25519 keypair using the ADR-8 derivation path in order to obtain a private key from the mnemonic. This is the default setting suitable for accounts on the Oasis consensus layer and Cipher.
  • secp256k1-bip44: Secp256k1 Ethereum-compatible keypair using BIP-44 with ETH coin type to derive a private key. This setting is used for accounts living on EVM-compatible ParaTimes such as Sapphire or Emerald. The same account can be imported into Metamask and other Ethereum wallets.
  • ed25519-raw: Ed25519 keypair imported directly from the Base64-encoded private key. No key derivation is involved. This setting is primarily used by the network validators to sign the governance and other consensus-layer transactions.
  • ed25519-legacy: Ed25519 keypair using a legacy 5-component derivation path. This is the preferred setting for Oasis accounts stored on a hardware wallet like Ledger. It is called legacy, because it was first implemented before the ADR-8 was standardized.
  • sr25519-adr8: Sr25519 keypair using the ADR-8 derivation path. This is an alternative signature scheme for signing ParaTime transactions.
  • secp256k1-raw and sr25519-raw: Respective Secp256k1 and Sr25519 keypairs imported directly from the Hex- or Base64-encoded private key. No key derivation is involved.
tip

For compatibility with Ethereum, each secp256k1 account corresponds to two addresses:

  • 20-byte hex-encoded Ethereum-compatible address, e.g. 0xDCbF59bbcC0B297F1729adB23d7a5D721B481BA9
  • Bech32-encoded Oasis native address, e.g. oasis1qq3agel5x07pxz08ns3d2y7sjrr3xf9paquhhhzl.

There exists a mapping from the Ethereum address to the native Oasis address as in the example above, but there is no reverse mapping.

Create an Account​

The wallet create <name> command is used add a new account into your Oasis CLI wallet by:

  • generating a new mnemonic and storing it into a file-based wallet, or
  • creating a reference to an account stored on your hardware wallet.

By default, a password-encrypted file-based wallet will be used for storing the private key. You will have to enter the password for this account each time to access use it for signing the transactions (e.g. to send tokens). The account address is public and can be accessed without entering the passphrase.

oasis wallet create oscar
? Choose a new passphrase:
? Repeat passphrase:
tip

The first account you create or import will become your default account. This means it will automatically be selected as a source for sending funds or calling smart contracts unless specified otherwise by using --account <name> flag. You can always change the default account later.

To use your hardware wallet, add --kind ledger parameter and Oasis CLI will store a reference to an account on your hardware wallet:

oasis wallet create logan --kind ledger

A specific account kind (ed25519-adr8, secp256k1-bip44) and the derivation path number can be passed with --file.algorithm and --file.number or --ledger.algorithm and --ledger.number respectively. For example:

oasis wallet create logan --kind ledger
tip

When creating a hardware wallet account, Oasis CLI will:

  1. obtain the public key of the account from your hardware wallet,
  2. compute the corresponding native address, and
  3. store the Oasis native address into the Oasis CLI.

If you try to open the same account with a different Ledger device or reset your Ledger with a new mnemonic, Oasis CLI will abort because the address of the account obtained from the new device will not match the one stored in your config.

oasis wallet show logan
Error: address mismatch after loading account (expected: oasis1qpl4axynedmdrrgrg7dpw3yxc4a8crevr5dkuksl got: oasis1qzdyu09x7hs5nqa0sjgy5jtmz3j5f99ccq0aezjk)

Import an Existing Keypair or a Mnemonic​

If you already have a mnemonic or a raw private key, you can import it as a new account by invoking wallet import. You will be asked interactively to select an account kind (mnemonic or private key), encryption algorithm (ed25519 or secp256k1) and then provide either the mnemonic with the derivation number, or the raw private key in the corresponding format.

Importing an account with a mnemonic looks like this:

oasis wallet import eugene
? Kind: mnemonic
? Algorithm: secp256k1-bip44
? Key number: 0
? Mnemonic: [Enter 2 empty lines to finish]man ankle mystery favorite tone number ice west spare marriage control lucky life together neither

? Mnemonic:
man ankle mystery favorite tone number ice west spare marriage control lucky life together neither
? Choose a new passphrase:
? Repeat passphrase:

Let's make another Secp256k1 account and entering a hex-encoded raw private key:

oasis wallet import emma
oasis wallet import emma
? Kind: private key
? Algorithm: secp256k1-raw
? Private key (hex-encoded): [Enter 2 empty lines to finish]4811ebbe4f29f32a758f6f7bad39deb97ea67f07350637e31c75795dc679262a

? Private key (hex-encoded):
4811ebbe4f29f32a758f6f7bad39deb97ea67f07350637e31c75795dc679262a
? Choose a new passphrase:
? Repeat passphrase:

To override the defaults, you can pass --algorithm, --number and --secret parameters. This is especially useful, if you are running the command in a non-interactive mode:

oasis wallet import eugene --algorithm secp256k1-bip44 --number 0 --secret "man ankle mystery favorite tone number ice west spare marriage control lucky life together neither" -y
Be cautious when importing accounts in non-interactive mode

Since the account's secret is provided as a command line parameter in the non-interactive mode, make sure you read the account's secret from a file or an environment variable. Otherwise, the secret may be stored and exposed in your shell history.

Also, protecting your account with a password is currently not supported in the non-interactive mode.

List Accounts Stored in Your Wallet​

You can list all available accounts in your wallet with wallet list:

oasis wallet list
ACCOUNT  	KIND                      	ADDRESS                                        
emma     	file (secp256k1-raw)      	oasis1qph93wnfw8shu04pqyarvtjy4lytz3hp0c7tqnqh	
eugene   	file (secp256k1-bip44:0)  	oasis1qrvzxld9rz83wv92lvnkpmr30c77kj2tvg0pednz	
lenny    	ledger (secp256k1-bip44:3)	oasis1qrmw4rhvp8ksj3yx6p2ftnkz864muc3re5jlgall	
logan    	ledger (ed25519-legacy:0) 	oasis1qpl4axynedmdrrgrg7dpw3yxc4a8crevr5dkuksl	
oscar (*)	file (ed25519-adr8:0)     	oasis1qp87hflmelnpqhzcqcw8rhzakq4elj7jzv090p3e

Above, you can see the native Oasis addresses of all local accounts. The default account has a special (*) sign next to its name.

Show Account Configuration Details​

To verify whether an account exists in your wallet, use wallet show <name>. This will print the account's native address and the public key which requires entering your account's password.

oasis wallet show oscar
Unlock your account.
? Passphrase:
Name:             oscar
Kind:             file (ed25519-adr8:0)
Public Key:       Bx6gOixnxy15tCs09ua5DcKyX9uo2Forb32O6Hyjoc8=
Native address:   oasis1qp87hflmelnpqhzcqcw8rhzakq4elj7jzv090p3e

For secp256k1 accounts Ethereum's hex-encoded address will also be printed.

oasis wallet show eugene
Unlock your account.
? Passphrase:
Name:             eugene
Kind:             file (secp256k1-bip44:0)
Public Key:       ArEjDxsPfDvfeLlity4mjGzy8E/nI4umiC8vYQh+eh/c
Ethereum address: 0xBd16C6bF701a01DF1B5C11B14860b6bDbE776669
Native address:   oasis1qrvzxld9rz83wv92lvnkpmr30c77kj2tvg0pednz

Showing an account stored on your hardware wallet will require connecting it to your computer:

oasis wallet show logan
Name:             logan
Kind:             ledger (ed25519-legacy:0)
Public Key:       l+cuboPsOeuY1+kYlROrpmKgiiELmXSw9xl0WEg8cWE=
Native address:   oasis1qpl4axynedmdrrgrg7dpw3yxc4a8crevr5dkuksl

Export the Account's Secret​

You can obtain the secret material of a file-based account such as the mnemonic or the private key by running wallet export <name>.

For example:

oasis wallet export oscar
WARNING: Exporting the account will expose secret key material!
Unlock your account.
? Passphrase:
Name:             oscar
Kind:             file (ed25519-adr8:0)
Public Key:       Bx6gOixnxy15tCs09ua5DcKyX9uo2Forb32O6Hyjoc8=
Native address:   oasis1qp87hflmelnpqhzcqcw8rhzakq4elj7jzv090p3e
Secret mnemonic:
promote easily runway junior saddle gold flip believe wet example amount believe habit mixed pistol lemon increase moon rail mail fiction miss clip asset
Derived secret key for account number 0:
LHOUUJgVquTdi/3DVsS4caW4jQcvuFgl1Oag6BwlNvwHHqA6LGfHLXm0KzT25rkNwrJf26jYWitvfY7ofKOhzw==

The same goes for your Secp256k1 accounts:

oasis wallet export eugene
WARNING: Exporting the account will expose secret key material!
Unlock your account.
? Passphrase:
Name:             eugene
Kind:             file (secp256k1-bip44:0)
Public Key:       ArEjDxsPfDvfeLlity4mjGzy8E/nI4umiC8vYQh+eh/c
Ethereum address: 0xBd16C6bF701a01DF1B5C11B14860b6bDbE776669
Native address:   oasis1qrvzxld9rz83wv92lvnkpmr30c77kj2tvg0pednz
Secret mnemonic:
man ankle mystery favorite tone number ice west spare marriage control lucky life together neither
Derived secret key for account number 0:
c559cad1e71e0db1b3a657f47ca7a618bfb6a51a7294df72bcfca57aded5377e
oasis wallet export emma
WARNING: Exporting the account will expose secret key material!
Unlock your account.
? Passphrase:
Name:             emma
Kind:             file (secp256k1-raw)
Public Key:       Az8B2UpSUET0E3n9XMzr+HBvviQKcRvz6C6bJtRFWNYG
Ethereum address: 0xeEbE22411f579682F6f9D68f4C19B3581bCb576b
Native address:   oasis1qph93wnfw8shu04pqyarvtjy4lytz3hp0c7tqnqh
Secret key:
4811ebbe4f29f32a758f6f7bad39deb97ea67f07350637e31c75795dc679262a

Trying to export an account stored on your hardware wallet will only export its public key:

oasis wallet export lenny
WARNING: Exporting the account will expose secret key material!
Name:             lenny
Kind:             ledger (secp256k1-bip44:3)
Public Key:       AhhT2TUkEZ7rMasLBvHcsGj4SUO7Iw36ELEpL0evZDV1
Ethereum address: 0x95e5e3C1BDD92cd4A0c14c62480DB5867946281D
Native address:   oasis1qrmw4rhvp8ksj3yx6p2ftnkz864muc3re5jlgall

Renaming the Account​

To rename an account, run wallet rename <old_name> <new_name>.

For example:

oasis wallet list
ACCOUNT  	KIND                      	ADDRESS                                        
emma     	file (secp256k1-raw)      	oasis1qph93wnfw8shu04pqyarvtjy4lytz3hp0c7tqnqh	
eugene   	file (secp256k1-bip44:0)  	oasis1qrvzxld9rz83wv92lvnkpmr30c77kj2tvg0pednz	
lenny    	ledger (secp256k1-bip44:3)	oasis1qrmw4rhvp8ksj3yx6p2ftnkz864muc3re5jlgall	
logan    	ledger (ed25519-legacy:0) 	oasis1qpl4axynedmdrrgrg7dpw3yxc4a8crevr5dkuksl	
oscar (*)	file (ed25519-adr8:0)     	oasis1qp87hflmelnpqhzcqcw8rhzakq4elj7jzv090p3e	
oasis wallet rename lenny lester
oasis wallet list
ACCOUNT  	KIND                      	ADDRESS                                        
emma     	file (secp256k1-raw)      	oasis1qph93wnfw8shu04pqyarvtjy4lytz3hp0c7tqnqh	
eugene   	file (secp256k1-bip44:0)  	oasis1qrvzxld9rz83wv92lvnkpmr30c77kj2tvg0pednz	
lester   	ledger (secp256k1-bip44:3)	oasis1qrmw4rhvp8ksj3yx6p2ftnkz864muc3re5jlgall	
logan    	ledger (ed25519-legacy:0) 	oasis1qpl4axynedmdrrgrg7dpw3yxc4a8crevr5dkuksl	
oscar (*)	file (ed25519-adr8:0)     	oasis1qp87hflmelnpqhzcqcw8rhzakq4elj7jzv090p3e

Deleting an Account​

To irreversibly delete the accounts from your wallet use wallet remove [names]. For file-based accounts this will delete the file containing the private key from your disk. For hardware wallet accounts this will delete the Oasis CLI reference, but the private keys will remain intact on your hardware wallet.

For example, let's delete lenny account:

oasis wallet list
ACCOUNT  	KIND                      	ADDRESS                                        
emma     	file (secp256k1-raw)      	oasis1qph93wnfw8shu04pqyarvtjy4lytz3hp0c7tqnqh	
eugene   	file (secp256k1-bip44:0)  	oasis1qrvzxld9rz83wv92lvnkpmr30c77kj2tvg0pednz	
lenny    	ledger (secp256k1-bip44:3)	oasis1qrmw4rhvp8ksj3yx6p2ftnkz864muc3re5jlgall	
logan    	ledger (ed25519-legacy:0) 	oasis1qpl4axynedmdrrgrg7dpw3yxc4a8crevr5dkuksl	
oscar (*)	file (ed25519-adr8:0)     	oasis1qp87hflmelnpqhzcqcw8rhzakq4elj7jzv090p3e	
oasis wallet remove lenny
WARNING: Removing the account will ERASE secret key material!
WARNING: THIS ACTION IS IRREVERSIBLE!
? Enter 'I really want to remove account lenny' (without quotes) to confirm removal: I really want to remove account lenny
oasis wallet list
ACCOUNT         KIND                            ADDRESS                                        
emma            file (secp256k1-raw)            oasis1qph93wnfw8shu04pqyarvtjy4lytz3hp0c7tqnqh
eugene          file (secp256k1-bip44:0)        oasis1qrvzxld9rz83wv92lvnkpmr30c77kj2tvg0pednz
logan           ledger (ed25519-legacy:0)       oasis1qpl4axynedmdrrgrg7dpw3yxc4a8crevr5dkuksl
oscar (*)       file (ed25519-raw)              oasis1qp87hflmelnpqhzcqcw8rhzakq4elj7jzv090p3e

You can also delete accounct in non-interactive mode format by passing the -y parameter:

oasis wallet remove lenny -y

Set Default Account​

To change your default account, use wallet set-default <name> and the name of the desired default account.

oasis wallet list
ACCOUNT  	KIND                      	ADDRESS                                        
emma     	file (secp256k1-raw)      	oasis1qph93wnfw8shu04pqyarvtjy4lytz3hp0c7tqnqh	
eugene   	file (secp256k1-bip44:0)  	oasis1qrvzxld9rz83wv92lvnkpmr30c77kj2tvg0pednz	
lenny    	ledger (secp256k1-bip44:3)	oasis1qrmw4rhvp8ksj3yx6p2ftnkz864muc3re5jlgall	
logan    	ledger (ed25519-legacy:0) 	oasis1qpl4axynedmdrrgrg7dpw3yxc4a8crevr5dkuksl	
oscar (*)	file (ed25519-adr8:0)     	oasis1qp87hflmelnpqhzcqcw8rhzakq4elj7jzv090p3e	
oasis wallet set-default lenny
oasis wallet list
ACCOUNT  	KIND                      	ADDRESS                                        
emma     	file (secp256k1-raw)      	oasis1qph93wnfw8shu04pqyarvtjy4lytz3hp0c7tqnqh	
eugene   	file (secp256k1-bip44:0)  	oasis1qrvzxld9rz83wv92lvnkpmr30c77kj2tvg0pednz	
lenny (*)	ledger (secp256k1-bip44:3)	oasis1qrmw4rhvp8ksj3yx6p2ftnkz864muc3re5jlgall	
logan    	ledger (ed25519-legacy:0) 	oasis1qpl4axynedmdrrgrg7dpw3yxc4a8crevr5dkuksl	
oscar    	file (ed25519-adr8:0)     	oasis1qp87hflmelnpqhzcqcw8rhzakq4elj7jzv090p3e

Advanced​

Import an Existing Keypair from PEM file​

Existing node operators may already use their Ed25519 private key for running their nodes stored in a PEM-encoded file typically named entity.pem. In order to submit their governance transaction, for example to vote on the network upgrade using the Oasis CLI, they need to import the key into the Oasis CLI wallet:

oasis wallet import-file my_entity entity.pem
? Choose a new passphrase:
? Repeat passphrase:

The key is now safely stored and encrypted inside the Oasis CLI.

oasis wallet list
ACCOUNT                         KIND                            ADDRESS                                        
my_entity                       file (ed25519-raw)              oasis1qpe0vnm0ahczgc353vytvtz9r829le4pjux8lc5z

Remote Signer for oasis-node​

You can bind the account in your Oasis CLI wallet with a local instance of oasis-node. To do this, use wallet remote-signer <account_name> <socket_path>, pick the account you wish to expose and provide a path to the new unix socket:

oasis wallet remote-signer oscar /datadir/oasis-oscar.socket
Unlock your account.
? Passphrase:
Address: oasis1qp87hflmelnpqhzcqcw8rhzakq4elj7jzv090p3e
Node Args:
  --signer.backend=remote \
  --signer.remote.address=unix:/datadir/oasis-oscar.socket

*** REMOTE SIGNER READY ***

Test Accounts​

Oasis CLI comes with the following hardcoded test accounts:

  • test:alice: Ed25519 test account used by Oasis core tests
  • test:bob: Ed25519 test account used by Oasis core tests
  • test:charlie: Secp256k1 test account
  • test:cory: Ed25519 account used by oasis-net-runner
  • test:dave: Secp256k1 test account
  • test:erin: Sr25519 test account
  • test:frank: Sr25519 test account
Do not use these accounts on public networks

Private keys for these accounts are well-known. Do not fund them on public networks, because anyone can drain them!

We suggest that you use these accounts for Localnet development or for reproducibility when you report bugs to the Oasis core team. You can access the private key of a test account the same way as you would for ordinary accounts by invoking the oasis wallet export command.