My first transaction

My first transaction


This document will guide you through setting up a Themelio wallet and sending your first transaction. Right now, you must use the headless wallet daemon melwalletd and the melwallet-cli CLI tool, though soon we will have a user-friendly GUI wallet that will be as easy to use as Metamask or Electrum.

Assumptions

All the instructions here assume that

  • You’re running a Unix (Linux or macOS) system. The code should work on Windows, but it isn’t well-tested.
  • You have a working Internet connection
  • You have git installed
  • You have a 1.49+ stable Rust compiler, including the cargo command

Install melwalletd and melwallet-cli

Install themelio-core with cargo directly from GitHub:

$ cargo install --locked --git https://github.com/themeliolabs/melwalletd.git

$ cargo install --locked --bin melwallet-cli --git https://github.com/themeliolabs/melwallet-client.git

cargo downloads and compiles the entire codebase and all its dependencies from scratch. This will take a while.

Start melwalletd

In a separate terminal window, leave the following command running:

melwalletd --wallet-dir ~/.themelio-wallets/

You can also use tmux or similar to run it in the background. This starts the persistent wallet daemon that the frontend melwallet-cli will communicate with.

Create Alice’s and Bob’s wallets

Before we send any transactions, we first create two wallets between which we can send money.

Let’s now create two wallets: alice and bob. To do so, first switch to another terminal and use melwallet-cli create-wallet to create two wallets:

$ melwallet-cli create -w alice --testnet
Wallet name:  alice
Network:      testnet
Address:      <ALICE_ADDRESS>
Balance:      0 µMEL

$ melwallet-cli create -w bob --testnet
Wallet name:  bob
Network:      testnet
Address:      <BOB_ADDRESS>
Balance:      0 µMEL

This generates and stores to disk the two wallets. We create the wallets on the testnet network, because right now there isn’t a way of purchasing mainnet tokens yet. Note that the address is a public identifier that uniquely identifies a wallet. It’s what you give other people when you want to receive money.

melwallet-cli will also prompt you for passwords. These passwords are used to encrypt the private keys of the wallets, which are stored in ~/.themelio-wallets/.secrets.json. So make sure to pick something strong! In the future, more interesting forms of authentication may be implemented.

Add money to Alice’s wallet

Use the testnet faucet

Because we created testnet wallets, we can use the testnet faucet: special transaction rules that allows anybody to print mels out of thin air. This allows easy testing on the testnet and is of course absent in the mainnet.

melwallet-cli send-faucet sends a faucet transaction to credit the wallet with 1000 MEL:

$ melwallet-cli send-faucet -w alice
Transaction hash:  9974a514351a0696b6d7e3851da957ff508e44857b4967e3d46b8d16685b9769
(wait for confirmation with melwallet-cli wait-confirmation -w alice 9974a514351a0696b6d7e3851da957ff508e44857b4967e3d46b8d16685b9769)

The faucet transaction is now already on its way. As the output suggests, you can wait for the transaction to confirm:

$ melwallet-cli wait-confirmation -w alice 9974a514351a0696b6d7e3851da957ff508e44857b4967e3d46b8d16685b9769
...............Confirmed at height 93807
(in block explorer: https://scan-testnet.themelio.org/blocks/93807/9974a514351a0696b6d7e3851da957ff508e44857b4967e3d46b8d16685b9769)

Send money to Bob

Send the transaction

Now we are ready to send money to Bob. We first unlock the wallet by entering our password:

$ melwallet-cli unlock -w alice

Let’s send over 500 MEL:

$ melwallet-cli send-tx -w alice --to <BOB_ADDRESS>,500000000
TRANSACTION RECIPIENTS
Address         Amount          Additional data
<BOB_ADDRESS>   500000000 µMEL  ""
 (network fees) 23 µMEL
Proceed? [y/N] y
Transaction hash:  35149dd7e23e4acbc3823578ddd73aa09e0ddd08f970b2b673e7f5e58dab6dc9
(wait for confirmation with melwallet-cli wait-confirmation -w alice 35149dd7e23e4acbc3823578ddd73aa09e0ddd08f970b2b673e7f5e58dab6dc9)

Note that we specify the units as µMEL (1 million µMEL = 1 MEL).

We can now wait until the money settles on the blockchain with the given command:

$ melwallet-cli wait-confirmation -w alice 35149dd7e23e4acbc3823578ddd73aa09e0ddd08f970b2b673e7f5e58dab6dc9
Confirmed at height 93819
(in block explorer: https://scan-testnet.themelio.org/blocks/93819/35149dd7e23e4acbc3823578ddd73aa09e0ddd08f970b2b673e7f5e58dab6dc9)

Receiving the money

In Themelio, wallets based on thin clients, like melwallet-cli, cannot trustlessly know exactly what money has been sent to them without processing every transaction and becoming a full node. Other UTXO blockchains like Bitcoin simply have thin clients trust somebody else to scan the blockchain for them.

However, we intentionally omit any functionality that would require third-party trust in our thin-client-based tools. This means that for Bob to see the money Alice sent him, he must input a “receipt” that Alice gives him: the coin ID of the coin sent to Bob. Coin IDs represent discrete sums of money on the blockchain, and we refer to them by <transaction hash>-<index>. For example, the money sent to Bob was the first output of the transaction with hash 35149dd7e23e4acbc3823578ddd73aa09e0ddd08f970b2b673e7f5e58dab6dc9, so the CoinID is 35149dd7e23e4acbc3823578ddd73aa09e0ddd08f970b2b673e7f5e58dab6dc9-0.

We add the money to Bob’s wallet:

Coin successfully added!
Wallet name:  bob
Network:      testnet
Address:      t0cvmtcqrtepb8tbsasmp3rm4kcv8w4s5s0w80ff46ecgbfafa7k5g
Balance:      500000000  µMEL

We now see that Bob has the 500 MEL from Alice!

Congratulations!

You’ve successfully sent 500 mels from Alice to Bob.

Next steps

In this guide, you used a validating thin client that does not synchronize the entire blockchain state. This has slightly less security and doesn’t allow much functionality without a reliable Internet connection, so in some applications you would want to run an full node to replicate and fully validate blocks. That’s covered in the next guide.