Need help with theta-protocol-ledger?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

135 Stars 33 Forks GNU General Public License v3.0 1.6K Commits 13 Opened issues


Reference implementation of the Theta Blockchain Ledger Protocol

Services available


Need anything else?

Contributors list

# 241,693
414 commits
# 597,048
React N...
10 commits
# 2,214
1 commit

Theta Blockchain Ledger Protocol

The Theta Blockchain Ledger is a Proof-of-Stake decentralized ledger designed for the video streaming industry. It powers the Theta token economy which incentives end users to share their redundant bandwidth and storage resources, and encourage them to engage more actively with video platforms and content creators. The ledger employs a novel multi-level BFT consensus engine, which supports high transaction throughput, fast block confirmation, and allows mass participation in the consensus process. Off-chain payment support is built directly into the ledger through the resource-oriented micropayment pool, which is designed specifically to achieve the “pay-per-byte” granularity for streaming use cases. Moreover, the ledger storage system leverages the microservice architecture and reference counting based history pruning techniques, and is thus able to adapt to different computing environments, ranging from high-end data center server clusters to commodity PCs and laptops. The ledger also supports Turing-Complete smart contracts, which enables rich user experiences for DApps built on top of the Theta Ledger. For more technical details, please refer to our technical whitepaper and 2019 IEEE ICBC paper Scalable BFT Consensus Mechanism Through Aggregated Signature Gossip.

To learn more about the Theta Network, please visit the Theta Documentation site:

Table of Contents


On macOS

Install Go and set environment variables

, and
. The current code base should compile with Go 1.12.1. On macOS, install Go with the following command
brew install [email protected]
brew link [email protected] --force

Clone this repo into your

. The path should look like this:
git clone $GOPATH/src/
export THETA_HOME=$GOPATH/src/

Build and Install

This should build the binaries and copy them into your

. Two binaries
are generated.
can be regarded as the launcher of the Theta Ledger node, and
is a wallet with command line tools to interact with the ledger.
export GO111MODULE=on
make install

Notes for Linux binary compilation

The build and install process on Linux is similar, but note that Ubuntu 18.04.4 LTS / Centos 8 or higher version is required for the compilation.

Notes for Windows binary compilation

The Windows binary can be cross-compiled from macOS. To cross-compile a Windows binary, first make sure

is installed (
brew install mingw-w64
) on your macOS. Then you can cross-compile the Windows binary with the following command:
make exe

You'll also need to place three

under the same folder as

Run Unit Tests

Run unit tests with the command below

make test_unit

Launch a Local Private Net

Open a terminal to launch the private net. For the first time, follow the setup steps below.

cp -r ./integration/privatenet ../privatenet
mkdir ~/.thetacli
cp -r ./integration/privatenet/thetacli/* ~/.thetacli/
chmod 700 ~/.thetacli/keys/encrypted
And then, use the following commands to launch a private net with a single validator node.
theta start --config=../privatenet/node

When the prompt asks for password, simply enter


In another terminal, we can use the

command line tool to send Theta tokens from one address to another by executing the following command. When the prompt asks for password, simply enter
thetacli tx send --chain="privatenet" --from=2E833968E5bB786Ae419c4d13189fB081Cc43bab --to=9F1233798E905E173560071255140b4A8aBd3Ec6 --theta=10 --tfuel=20 --seq=1
The balance of an address can be retrieved with the following query command
thetacli query account --address=9F1233798E905E173560071255140b4A8aBd3Ec6

CLI Commands

|Link|Binary| |---|---| |Theta Wallet command line tools|thetacli| |Theta Ledger node|theta|

Deploy and Execute Smart Contracts

The Theta Ledger provides a Turing-Complete smart contract runtime environment compatible with the Ethereum Virtual Machine (EVM). Solidity based Ethereum smart contracts can be ported to the Theta Ledger with little effort. The example below demonstrates how to deploy and execute an example smart contract

on the local private net we just launched.
pragma solidity ^0.4.18;

contract SquareCalculator { uint public value;

function SetValue(uint val) public {
    value = val;

function CalculateSquare() constant public returns (uint) {
    uint sqr = value * value;
    assert(sqr / value == value); // overflow protection
    return sqr;


Using any Solidity compiler, such as Remix, we can generate the deployment bytecode of the smart contract as shown below.

Now let us deploy the bytecode on the Theta Ledger, and then use it to calculate squares. Note that for each of steps below, we may perform a dry run first with the
thetacli call
command, which simulates the smart contract execution locally. For the actually deployment and execution, we use the
thetacli tx
command instead.

First, let us do a dry run for the smart contract deployment. The

parameter carries the deployment bytecode of the smart contract as provided above.
thetacli call smart_contract --chain="privatenet" --from=2E833968E5bB786Ae419c4d13189fB081Cc43bab --value=0 --gas_price=1000000000wei --gas_limit=200000 --data=608060405234801561001057600080fd5b50610148806100206000396000f300608060405260043610610057576000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff1680633fa4f2451461005c578063b5a0241a14610087578063ed8b0706146100b2575b600080fd5b34801561006857600080fd5b506100716100df565b6040518082815260200191505060405180910390f35b34801561009357600080fd5b5061009c6100e5565b6040518082815260200191505060405180910390f35b3480156100be57600080fd5b506100dd60048036038101908080359060200190929190505050610112565b005b60005481565b6000806000546000540290506000546000548281151561010157fe5b0414151561010b57fe5b8091505090565b80600081905550505600a165627a7a72305820459c07c1668e919ca760d663b8df04e80634c53ebd49393dca83e81c58ae2a660029
This call should return a json similar to the one shown below. The
parameter gives the address of the smart contract when it is actually deployed on to the blockchain. The
field is the amount of gas to be consumed if we deploy the smart contract.
    "contract_address": "0x5c3159ddd2fe0f9862bc7b7d60c1875fa8f81337",
    "gas_used": 139293,
    "vm_error": "",
    "vm_return": "608060405260043610610057576000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff1680633fa4f2451461005c578063b5a0241a14610087578063ed8b0706146100b2575b600080fd5b34801561006857600080fd5b506100716100df565b6040518082815260200191505060405180910390f35b34801561009357600080fd5b5061009c6100e5565b6040518082815260200191505060405180910390f35b3480156100be57600080fd5b506100dd60048036038101908080359060200190929190505050610112565b005b60005481565b6000806000546000540290506000546000548281151561010157fe5b0414151561010b57fe5b8091505090565b80600081905550505600a165627a7a72305820459c07c1668e919ca760d663b8df04e80634c53ebd49393dca83e81c58ae2a660029"
Now, let us deploy the contract with the following command. Again, when the prompt asks for password, simply enter
thetacli tx smart_contract --chain="privatenet" --from=2E833968E5bB786Ae419c4d13189fB081Cc43bab --value=0 --gas_price=1000000000wei --gas_limit=200000 --data=608060405234801561001057600080fd5b50610148806100206000396000f300608060405260043610610057576000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff1680633fa4f2451461005c578063b5a0241a14610087578063ed8b0706146100b2575b600080fd5b34801561006857600080fd5b506100716100df565b6040518082815260200191505060405180910390f35b34801561009357600080fd5b5061009c6100e5565b6040518082815260200191505060405180910390f35b3480156100be57600080fd5b506100dd60048036038101908080359060200190929190505050610112565b005b60005481565b6000806000546000540290506000546000548281151561010157fe5b0414151561010b57fe5b8091505090565b80600081905550505600a165627a7a72305820459c07c1668e919ca760d663b8df04e80634c53ebd49393dca83e81c58ae2a660029 --seq=2
Wait for a few seconds for the transaction to be included in the blockchain. Then we can use the following query command to confirmed that the smart contract has been deployed, where the account address is the
returned by the deployment dry run.
thetacli query account --address=0x5c3159ddd2fe0f9862bc7b7d60c1875fa8f81337
Now, let us call the
function of the deployed smart contract with the following
thetacli tx
command. Note that the smart contract address is passed to the command with the
parameter. And the
parameter is the concatenation of
, the signature of the function
, and an integer
for which we want to calculate the square.
thetacli tx smart_contract --chain="privatenet" --from=2E833968E5bB786Ae419c4d13189fB081Cc43bab --to=0x5c3159ddd2fe0f9862bc7b7d60c1875fa8f81337 --gas_price=1000000000wei --gas_limit=50000 --data=ed8b07060000000000000000000000000000000000000000000000000000000000000003 --seq=3
Again, wait for a couple seconds for the transaction to be included in the blockchain, and then we can query the square result with the following command, where the
is the signature of the
thetacli call smart_contract --chain="privatenet" --from=2E833968E5bB786Ae419c4d13189fB081Cc43bab --to=0x5c3159ddd2fe0f9862bc7b7d60c1875fa8f81337 --gas_price=1000000000wei --gas_limit=50000 --data=b5a0241a
field in the returned json should be
, which is simply the square of
, the value we set previously.

You might have noticed that both the smart contract deployment and execution use the

thetacli tx smart_contract
command with similar parameters. The only difference is that the deployment command does not have the
parameter, while in the execution command, the
parameter is set to the smart contract address.

Off-Chain Micropayment Support

In order to handle the sheer amount of micropayments for the bandwidth sharing reward, the Theta Ledger provides native support for off-chain payment through the resource oriented micropayment pool concept. The micropayment pool allows a sender to pay to multiple recipients with off-chain transactions without the sender being able to double spend.

Below is an example. To get started, the sender creates a resource oriented micropayment pool for a live video stream with resourceid

by reserving some TFuel tokens for 1002 blocktimes. She can use this micropayment pool to pay multiple relay nodes that provides the desired video stream. ``` thetacli tx reserve --chain="privatenet" --from=2E833968E5bB786Ae419c4d13189fB081Cc43bab --fund=100 --collateral=101 --duration=1002 --resourceids=rid1000001 --seq=4

After this transaction has been processed. We can query the `from` account to confirm the creation of the micropayment pool.
thetacli query account --address=2E833968E5bB786Ae419c4d13189fB081Cc43bab
The return should look like the json below. As we can see, 100 TFuel (= 100000000000000000000 TFuelWei) were reserved for the off-chain payment with 101 TFuel collateral for resourceID `rid1000001`. If the sender overspends the reserved fund, her collateral will be entirely slashed.
{ "address": "2E833968E5bB786Ae419c4d13189fB081Cc43bab", ... "reservedfunds": [ { "collateral": { "tfuelwei": 101000000000000000000, "thetawei": 0 }, "endblockheight": 1588, "initialfund": { "tfuelwei": 100000000000000000000, "thetawei": 0 }, "reservesequence": 4, "resourceids": [ "rid1000001" ], "transferrecords": [], "usedfund": { "tfuelwei": 0, "thetawei": 0 } } ], ... } ``` From the reserved fund, the sender can send tokens to multiple parties with a special off-chain Service Payment Transaction. Before the reserved fund expires (1002 blocktimes), whenever a recipient wants to receive the tokens, he simply signs the last received service payment transaction, and submits the signed raw transaction to the Ledger node. A sender might send the recipient multiple off-chain transactions before the recipient signs and submits the last transaction to receive the full amount. This mechanism achieves the "pay-per-byte" granularity, and yet could reduce the amount of on-chain transactions by several orders of magnitude. For more details, please refer to the "Off-Chain Micropayment Support" section of our technical whitepaper.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.