Contract

Seele Stem subchain protocol is a layer-2 solution to improve the scalability of Seele mainnet. A general introduction of the protocol can be found here.

Deploy a new Stem contract

To create your own Stem subchain, you need to deploy a Stem contract on Seele mainnet. Stem contract serves as an important interface between Seele mainnet and subchains. It ensures the ultimate safety of your assets in the subchains. Each Stem subchain should have its own Stem contract.

1. Customize parameters

Before deploying Stem contract, you should customize the parameters in function init in StemCreation.sol.

Parameter

Description

MIN_LENGTH_OPERATOR

minimum number of operators

MAX_LENGTH_OPERATOR

maximum number of operators

CHILD_BLOCK_INTERVAL

relay frequency, i.e. relay information should be submitted with this frequency

IS_NEW_OPERATOR_ALLOWED

true if new operators are allowed to join; otherwise false

creatorMinDeposit

minimum deposit of the creator

childBlockChallengePeriod

response to block challenges are allowed within [submission time of last relay block, submission time of last relay block + childBlockChallengePeriod]

childBlockChallengeSubmissionPeriod

block challenges are allowed within [submission time of last relay block, submission time of last relay block + childBlockChallengeSubmissionPeriod]

relayTimeout

the contract will be discarded if the last relay block is not confirmed within [submission time of last relay block, submission time of last relay block + relayTimeout]

isBlockSubmissionBondReleased

should be true initially

blockSubmissionBond

the bond a block submitter pays

blockChallengeBond

the bond a block challenger pays

operatorMinDeposit

the minimum value for each operator deposit

userMinDeposit

the minimum value for each user deposit

userExitBond

the bond a user pays to exit

isFrozen

true if the contract is discarded; otherwise false; should be false initially

You can use MIN_LENGTH_OPERATOR and MAX_LENGTH_OPERATOR to specify how many operators are allowed in your subchain.

After a constant number of blocks are produced in the subchain, some relay information needs to be submitted to Stem contract. This constant number is specified by CHILD_BLOCK_INTERVAL.

IS_NEW_OPERATOR_ALLOWED is used to specify whether new operators are allowed to join after the creation of the subchain. If it is set as false, then operators can only be set up at the creation of the subchain.

creatorMinDeposit, operatorMinDeposit and userMinDeposit are the minimum amount of deposits for each deposit operation. Creator deposit is only needed when the creator creates the Stem contract. Operator deposit is needed when a new operator wants to join the subchain. A minimum user deposit is required when a user wants to deposit more funds into its subchain account.

After the information of a relay block is submitted, it could be challenged if someone finds the information incorrect. There is a time window for submitting challenges. The length of this time window is specified by childBlockChallengeSubmissionPeriod. There is a longer time window, of which the length is childBlockChallengePeriod, for submitting responses to the challenges. After childBlockChallengePeriod if there is no unresolved challenge, the relay block is confirmed.

To prevent the case that a relay block is not confirmed for a long time, relayTimeout is used as the timeout limit. When relayTimeout is exceeded, the Stem contract will be discarded, which means it can not be used anymore and reasonable mainnet funds will be returned to subchain participants. isFrozen is an indicator of whether the Stem contract is discarded. Note that once the Stem contract is discarded, it is permanent.

Bonds are used to penalize possible malicious behaviors. blockSubmissionBond is required when an operator or owner submits the information of a new relay block. If the new relay block is successfully challenged, then the blockSubmissionBond is rewarded to the challenger. The blockSubmissionBond will be returned to the submitter upon the confirmation of the relay block.

Similarly, blockChallengeBond is required when someone wants to challenge a relay block. If the challenge is successful, the challenger gets blockChallengeBond back plus the blockSubmissionBond. Otherwise, the blockChallengeBond is forfeited.

userExitBond is required when a user wants to exit part of its fund from the subchain. If the exit is completed successfully, userExitBond will be returned to the user.

2. Use controller to deploy Stem contract

You will need to deploy a series of contracts on Seele mainnet. The best way is to use controller to do it.

The input of the constructor

type

name

note

bytes32

subchainName

name of the subchain (optional)

bytes32[]

genesisInfo

[root hash of balance merkle tree, root hash of recent transaction merkle tree]

bytes32[]

staticNodes

array of static nodes (optional)

uint256

creatorDeposit

creator deposit

address[]

ops

array of operator account (subchain account); the first account is the mint account in the subchain; the second account is the melt account in the subchain; operator accounts start from the third account

uint256[]

opsDeposits

array of initial operator deposit; the fist two elements are not used; starting from the third element, opsDeposits[i] is the amount of deposit of ops[i]

address[]

refundAccounts

array of refund accounts (Seele mainnet accounts); the first two elements are not used; starting from the third element, refundAccounts[i] is the Seele mainnet account of ops[i]

Note that the contract deployment itself is a mainnet transaction. The sender of the transaction will be the owner of the Stem contract. The amount of the transaction must be greater than or equal to the sum of creator deposit and all operator deposits. The length of array ops, opsDeposits and refundAccounts must be the same. The length of ops should be at least 3; in this case, the subchain has one mint account, one melt account and an operator account. The mint account is the subchain account which issues token to subchain participants. The melt account is

After the deployment of StemRootchain.sol, you've created a Seele stem contract successfully. Congratulations!

Owner

Discard contract

The contract owner is able to discard the Stem contract. All the funds in the Stem contract will be returned to participants based on the information of the most recent confirmed relay block.

Operator

Register a new operator

To register a new operator, you need to provide the operator's subchain account and mainnet account (for the use of refund). The subchain account should not be used before by other operators or users in the same subchain. The deposit amount should be greater than operatorMinDeposit.

Operator exit

The operator can exit from the subchain by submitting an exit request.

Fee exit

The operator can withdraw his reward (users' transaction fee in the subchain) by submitting a fee exit request.

Submit relay block

The operators or owner need to submit information of relay blocks. The information is shown in the following table.

type

name

note

uint256

the height of relay block

should be a multiple of CHILD_BLOCK_INTERVAL

bytes32

root hash of balance merkle tree of the relay block

bytes32

root hash of recent transaction merkle tree of the relay block

address[]

updated accounts

the accounts which have a balance change since last relay block

uint256[]

updated balances

uint256

fee

fee income for each operator (same for each operator) since last relay block

Respond to block challenge

Operators need to respond to every valid block challenge during childBlockChallengePeriod. Otherwise, the new relay block will not be confirmed. Operators needs to provide transaction history to prove the challenged accounts have claimed updated balances.

User

User deposit

To deposit more fund to a (new or existing) user account, you need to provide the user's subchain account and mainnet account (for the use of refund). The subchain account should not be used before by other operators in the same subchain. The deposit amount should be greater than userMinDeposit.

User exit

The user can exit part (or all) of his fund from the subchain by submitting an exit request.

Challenge submitted block

Users can check the updated balances in the Stem contract. If they believe the balances are incorrect, they can submit challenges during childBlockChallengeSubmissionPeriod.

The challenger needs to provide the subchain account to challenge. Additionally, the challenger can provide evidence that a transaction is included in a valid block since last confirmed relay block.