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

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

Description

Reference implementation of the Theta Blockchain Ledger Protocol

Services available

!
?

Need anything else?

Contributors list

# 241,693
JavaScr...
vanilla...
maskedi...
Shell
414 commits
# 597,048
JavaScr...
draft-j...
React N...
Python
10 commits
# 2,214
d3v5
autoit
R
atom-pl...
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: https://docs.thetatoken.org/

Table of Contents

Setup

On macOS

Install Go and set environment variables

GOPATH
,
GOBIN
, and
PATH
. 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

$GOPATH
. The path should look like this:
$GOPATH/src/github.com/thetatoken/theta
git clone https://github.com/thetatoken/theta-protocol-ledger.git $GOPATH/src/github.com/thetatoken/theta
export THETA_HOME=$GOPATH/src/github.com/thetatoken/theta
cd $THETA_HOME

Build and Install

This should build the binaries and copy them into your

$GOPATH/bin
. Two binaries
theta
and
thetacli
are generated.
theta
can be regarded as the launcher of the Theta Ledger node, and
thetacli
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

mingw64
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

.dll
files
libgcc_s_seh-1.dll
,
libstdc++-6.dll
,
libwinpthread-1.dll
under the same folder as
theta.exe
and
thetacli.exe
.

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.

cd $THETA_HOME
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

qwertyuiop

In another terminal, we can use the

thetacli
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
qwertyuiop
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

SquareCalculator
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.

608060405234801561001057600080fd5b50610148806100206000396000f300608060405260043610610057576000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff1680633fa4f2451461005c578063b5a0241a14610087578063ed8b0706146100b2575b600080fd5b34801561006857600080fd5b506100716100df565b6040518082815260200191505060405180910390f35b34801561009357600080fd5b5061009c6100e5565b6040518082815260200191505060405180910390f35b3480156100be57600080fd5b506100dd60048036038101908080359060200190929190505050610112565b005b60005481565b6000806000546000540290506000546000548281151561010157fe5b0414151561010b57fe5b8091505090565b80600081905550505600a165627a7a72305820459c07c1668e919ca760d663b8df04e80634c53ebd49393dca83e81c58ae2a660029
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

data
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
contract_address
parameter gives the address of the smart contract when it is actually deployed on to the blockchain. The
gas_used
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
qwertyuiop
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
contract_address
returned by the deployment dry run.
thetacli query account --address=0x5c3159ddd2fe0f9862bc7b7d60c1875fa8f81337
Now, let us call the
SetValue()
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
to
parameter. And the
data
parameter is the concatenation of
ed8b0706
, the signature of the function
SetValue()
, and an integer
0x3
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
data
parameter
b5a0241a
is the signature of the
CalculateSquare()
function.
thetacli call smart_contract --chain="privatenet" --from=2E833968E5bB786Ae419c4d13189fB081Cc43bab --to=0x5c3159ddd2fe0f9862bc7b7d60c1875fa8f81337 --gas_price=1000000000wei --gas_limit=50000 --data=b5a0241a
The
vm_return
field in the returned json should be
0000000000000000000000000000000000000000000000000000000000000009
, which is simply the square of
0x3
, 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
to
parameter, while in the execution command, the
to
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

rid1000001
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.