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.