vechain/thor-builtins

Builtin contracts & examples

thor-builtins

builtin for vechain

The builtin contracts including "authority.sol", "energy.sol", "extension.sol", "params.sol", "prototype.sol" and "executor.sol". You can check the source code of these contracts by visiting: https://github.com/vechain/thor/blob/master/builtin/gen. We will give a detailed description of these contracts and teach you how to use it in your dapp. Some simple examples generated by truffle will be given and you can run it in VechainThor testnet.

builtin contracts

• authority.sol

  Authority is related to the POA(proof of authority) consensus mechanism. The Authority contract manages a list of candidates proposers who is responsible for packing transactions into a block. The proposers are authorized by a voting committee, but only the first 101 proposers in the candidates list can pack block. A candidates proposer include signer address, endorsor address and identity. Signer address is releated to sign a block, endorsor address is used for charging miner's fee and identity is used for identifying the proposer.

• energy.sol

  Energy represents the sub-token in VeChainThor which conforms VIP180(ERC20) standard. The name of token is "VeThor" and 1 THOR equals to 1e18 wei. The main function of VeThor is to pay for the transaction fee. VeThor is generated from VET, so the initial supply of VeThor is zero in the genesis block. The growth rate of VeThor is 5000000000 wei per token(VET) per second, that is to say 1 VET will produce about 0.000432 THOR per day. The miner will charge 30 percent of transation fee and 70 percent will be burned. So the total supply of VeThor is dynamic.

• extension.sol

  Extension extends EVM functions. Extension gives an opportunity for the developer to get information of the current transaction and any history block within the range of genesis to best block. The information obtained based on block numer includes blockID, blockTotalScore, blockTime and blockSigner. The developer can also get the current transaction information, including txProvedWork, txID, txBlockRef and txExpiration.

• params.sol

  Params stores the governance params of VeChain thor. The params can be set by the executor, a contract that is authorized to modify governance params by a voting Committee. Anyone can get the params just by calling "get" funtion. The governance params is written in genesis block at launch time. You can check these params at source file: https://github.com/vechain/thor/blob/master/thor/params.go.

• prototype.sol

  Prototype is an account management model of VeChainThor. In the account management model every contract has a master account, which, by default, is the creator of a contract. The master account plays the role of a contract manager, which has some authorities including "setMaster", "setCreditPlan", "addUser", "removeUser" and "selectSponsor". Every contract keeps a list of users who can call the contract for free but limited by credit. The user of a specific contract can be either added or removed by the contract master. Although from a user's perspective the fee is free, it is paid by a sponsor of the contract. Any one can be a sponser of a contract, just by calling sponsor function, and also the sponsor identity can be cancelled by calling unsponsor funtion. A contract may have more than one sponsors, but only the current sponsor chosen by master need to pay the fee for the contract. If the current sponsor is out of energy, master can select sponser from other sponsers candidates by calling selectSponsor function. The creditPlan can be set by the master which includes credit and recoveryRate. Every user have the same original credit. Every Transaction consumes some amount of credit which is equal to the fee of the Transaction, and the user can also pay the fee by itself if the gas payer is out of the credit. The credit can be recovered based on recoveryRate (per block).

• executor.sol

  Executor represents core component for on-chain governance. The on-chain governance params can be changed by the Executor through a voting. A executive committee are composed to seven approvers who had been added to the contract Executor in the genesis block. The new approver can be added and the old approver also can be removed from the executive committee. The steps of executor include proposing, approving and executing voting if the voting was passed. Only the approver in the executive committee has the authority to propose and approving a voting.

Library Builtin

• builtin.sol

  The VeChainThor builtin contracts are encapsulated in library Builtin. It's very easy to use it for the developer, just import it.

How to use it

• extension

The contract extension gives extension information about blockchain including "blockID", "txID", and "blockTotalScore" etc. And you can reference it conveniently in your dapp. So you maybe have a contract named "Example.sol"

1. Import "Library Builtin" in your solidity code "Example.sol".

   import "./builtin.sol"
   

2. Create your contract "Example" and get instance of extension.

   contract Example {
       Extension extension = Builtin.getExtension()
   }
   

3. In some cases you maybe want to calculate blake2b-256 checksum of given _data.

       bytes32 ret = extension.blake2b256(_data);
   

4. Get blockID of blockNum

       bytes32 id = extension.blockID(blockNum);
   

5. Get blockTotalScore of blockNum

       uint64 totalScore = extension.blockTotalScore(blockNum);
   

6. Get blockTime of blockNum

       uint time = extension.blockTime(blockNum);
   

7. Get blockSigner of blockNum

       address signer = extension.blockSigner(blockNum);
   

8. Get totalSupply of VET

       uint256 total = extension.totalSupply();
   

9. Get txProvedWork of current transaction

       uint256 provedWork = extension.txProvedWork();
   

10. Get txID of current transaction

        bytes32 id = extension.txID();
    

11. Get txBlockRef of current transaction

        bytes8 Ref = extension.txBlockRef();
    

12. txExpiration of current transaction

        uint expiration = extension.txExpiration();
    

• executor

Some builtin contracts need executor to execute it, such as "authority.sol" and "params.sol". We use "executor" including three steps: "propose a voting", "voting by executive committee" and "execute a voting". So you maybe have a voting contract named "voting.sol".

1. Import "Library Builtin" in your solidity code "voting.sol"

   import "./builtin.sol"
   

2. Create your voting contract and add "propose functon" named "propose".

   contract voting {
       bytes32 proposalID;
       Executor executor = Builtin.getExecutor();
   
       function propose(address target, bytes _data) {
           proposalID = executor.propose(target, _data);
       }
   }
   

3. The executive committee will approve a voting, so will add approve function named "approve".

   contract voting {
       ......
   
       function approve() {
           executor.approve(proposalID);
       }
   }
   

4. If a voting is passed in one week, anybody can execute it. So we add execute function named "execute".

   contract voting {
       ......
   
       function execute() {
           executor.execute(proposalID);
       }
   }
   

• authority

If you want to update authority node, you should have a target contract, such as "Target.sol". Because only the contract executor have the authority to execute it, so firstly you should propose a voting to executor. If the voting is passed in a week, you can execute your target contract. Now you can write code like this.

1. Import "Library Builtin" in your solidity code "Target.sol".

   import "./builtin.sol"
   

2. Create your target contract, we named it "Target", and create the target function named "targetFunc". We suppose you want to add "_signer" to the candidate of authority node.

   contract Target {
       Authority authority = Builtin.getAuthority();
   
       function targetFunc() {
           authority.add(_signer, _endorsor, _indentity);
       }
   }
   

3. You may be propose a voting by executor, and add the proposing function named "proposeFunc".

   contract Target {
       ......
   
       bytes32 proposalID;
       Executor executor = Builtin.getExecutor();
       function proposeFunc() {
           proposalID = executor.propose(address(this), abi.encodePacked(keccak256("targetFunc()")));
       }
   }
   

4. If the voting is passed in one week, you can execute it, so we should add "execute function" named "executeFunc".

   contract Target {
       ......
   
       function executeFunc() {
           executor.execute(proposalID);
       }
   }
   

5. Only "add" and "revoke" need executor to execute it, other functions like "get", "first" and "next", you can call it as your will.

• parmas

The operaion of parmas is very simple, just including "set" and "get". But the "set" operaion need executor to execute.

• prototype

The prototype gives extra property to contract, such as "master", "user", "sponsor" and "credit". Once a contract is created, the contract have these properties automatically. So you maybe just create a empty contract named "EmptyContract".

1. Import "Library Builtin" in your solidity code "EmptyContract.sol".

   import "./builtin.sol"
   

2. Create your "EmptyContract", and using "Library Builtin" for EmptyContract

   contract EmptyContract {
       using Builtin for EmptyContract;
   }
   

3. You maybe want to know who is the master of the contract, you just call like this in your contract:

   contract EmptyContract {
       using Builtin for EmptyContract;
       address master = this.$master();
   }
   

4. You alse can set a new master to your contract, but the msg sender must be the old master.

       this.$setMaster(newMaster);
   

5. Get the blance of the contract:

       uint256 blance = this.$balance(block.number);
   

6. Get the energy(VTHOR) of the contract:

       uint256 energy = this.$energy(block.number);
   

7. Check storage value by "key".

       bytes32 value = this.$storageFor(key);
   

8. Check creditPlan of a contract.

       uint256 credit;
       uint256 recoveryRate;
       credit, recoveryRate = this.$creditPlan()
   

9. Set a new creditPlan to a contract, but only the master have the authority to do it.

       this.$setCreditPlan(credit, recoveryRate);
   

10. Add a user to contract, and the operation need master authority.

        this.$addUser(newUser);
    

11. Remove an old user from contract(need master authority).

        this.$removeUser(oldUser);
    

12. Check if somebody is the user of a given contract.

        bool isUser = this.$isUser(somebody);
    

13. Check somebody userCredit of a contract:

        uint256 credit = this.$userCredit(somebody);
    

14. Check if somebody is the sponsor of a contract.

        bool isSponsor = this.$isSponsor(somebody);
    

15. Check who is the currentSponsor.

        address somebody = this.$currentSponsor();
    

instance contracts

• CommodityInfo.sol

  CommodityInfo stores commodity information into a contract storage. Just for example, the information of commodity is very simple and it includes id, originPlace, productionDate and shelfLife. Only master or users of the contract have authority to add commodity information.

• Voting.sol

  Voting intends to modify governance params 'BaseGasPrice' in VechainThor by executor. First a voting will be proposed by an approver, and the approvers will vote it in a week. If two thirds of approvers approver the voting, the voting can be executed.

thor-builtins's Issues

Contract for Multi Party Protocol

The source for contract for the MPP should be added, so that we can do unit testing with it.