README
¶
Til (Test instructions language)
Language to define sets of instructions to simulate Hermez transactions (L1 & L2) with real data.
Syntax
Global
- Set type definition
- Blockchain: generate the transactions that would come from the Hermez smart contract on the blockchain.
Type: Blockchain
- PoolL2: generate the transactions that would come from the Pool of L2Txs
Type: PoolL2
Blockchain set of instructions
Available instructions:
Type: Blockchain
// add the TokenID:
AddToken(1)
// deposit of TokenID=1, on the account of tokenID=1 for the user A, of an
// amount of 50 units
CreateAccountDeposit(1) A: 50
// create the account of TokenID=1 for the user B, deposit of TokenID=1, on the
// account of tokenID=1 for the user B, of an amount of 40 units and atomically
// transfer 10 units to account of tokenID=1 for the user A
CreateAccountDepositTransfer(1) B-A: 40, 10
// transaction generated by the Coordinator, create account for user User0 for
// the TokenID=2, with a deposit of 0
CreateAccountCoordinator(2) User0
// deposit of TokenID=1, at the account A, of 6 units
Deposit(1) A: 6
// deposit of TokenID=1, on the account of tokenID=1 for the user B, of an
// amount of 6 units and atomically transfer 10 units to account of tokenID=1 for
// the user A
DepositTransfer(1) B-A: 6, 4
// transfer of TokenID=1, from the account A to B (for that token), of 6 units,
// paying a fee of 3. Transaction will be a L2Tx
Transfer(1) A-B: 6 (3)
// exit of TokenID=1, from the account A (for that token), of 5 units, paying a
// fee of 1. Transaction will be a L2Tx
Exit(1) A: 5 (1)
// force-transfer of TokenID=1, from the account A to B (for that token), of 6
// units. Transaction will be L1UserTx of ForceTransfer type
ForceTransfer(1) A-B: 6
// force-exit of TokenID=1, from the account A (for that token), of 5 units.
// Transaction will be L1UserTx of ForceExit type
ForceExit(1) A: 5
// advance one batch, forging without L1UserTxs, only can contain L2Txs and
// L1CoordinatorTxs
> batch
// advance one batch, forging with L1UserTxs (and L2Txs and L1CoordinatorTxs)
> batchL1
// advance an ethereum block
> block
PoolL2 set of instructions
Available instructions:
Type: PoolL2
// transfer of TokenID=1, from the account A to B (for that token), of 6 units,
// paying a fee of 4
PoolTransfer(1) A-B: 6 (4)
// exit of TokenID=1, from the account A (for that token), of 3 units, paying a
// fee of 1
PoolExit(1) A: 3 (1)
Usage
// create a new til.Context
tc := til.NewContext(eth.RollupConstMaxL1UserTx)
// generate Blockchain blocks data from the common.SetBlockcahin0 instructions set
blocks, err = tc.GenerateBlocks(common.SetBlockchainMinimumFlow0)
assert.Nil(t, err)
// generate PoolL2 transactions data from the common.SetPool0 instructions set
poolL2Txs, err = tc.GeneratePoolL2Txs(common.SetPoolL2MinimumFlow0)
assert.Nil(t, err)
Where blocks
will contain:
// BatchData contains the information of a Batch
type BatchData struct {
L1CoordinatorTxs []common.L1Tx
L2Txs []common.L2Tx
CreatedAccounts []common.Account
}
// BlockData contains the information of a Block
type BlockData struct {
L1UserTxs []common.L1Tx
Batches []BatchData
RegisteredTokens []common.Token
}
Documentation
¶
Index ¶
- Constants
- Variables
- func L1TxsToCommonL1Txs(l1 []L1Tx) []common.L1Tx
- type Account
- type ConfigExtra
- type Context
- func (tc *Context) FillBlocksExtra(blocks []common.BlockData, cfg *ConfigExtra) error
- func (tc *Context) FillBlocksForgedL1UserTxs(blocks []common.BlockData) error
- func (tc *Context) FillBlocksL1UserTxsBatchNum(blocks []common.BlockData)
- func (tc *Context) GenerateBlocks(set string) ([]common.BlockData, error)
- func (tc *Context) GenerateBlocksFromInstructions(set []Instruction) ([]common.BlockData, error)
- func (tc *Context) GeneratePoolL2Txs(set string) ([]common.PoolL2Tx, error)
- func (tc *Context) GeneratePoolL2TxsFromInstructions(set []Instruction) ([]common.PoolL2Tx, error)
- func (tc *Context) RestartNonces()
- type Instruction
- type L1Tx
- type L2Tx
- type User
Constants ¶
const ( ILLEGAL token = iota WS EOF IDENT // val )
nolint
Variables ¶
var SetTypeBlockchain = setType("Blockchain")
SetTypeBlockchain defines the type 'Blockchain' of the set
var SetTypePoolL2 = setType("PoolL2")
SetTypePoolL2 defines the type 'PoolL2' of the set
var TxTypeCreateAccountDepositCoordinator common.TxType = "TypeCreateAccountDepositCoordinator"
TxTypeCreateAccountDepositCoordinator is used for testing purposes only, and represents the common.TxType of a create acount deposit made by the coordinator
var TypeAddToken common.TxType = "InstrTypeAddToken" //nolint:gosec
TypeAddToken is used for testing purposes only, and represents the common.TxType of a new Token regsitration. It has 'nolint:gosec' as the string 'Token' triggers gosec as a potential leaked Token (which is not the case).
var TypeNewBatch common.TxType = "InstrTypeNewBatch"
TypeNewBatch is used for testing purposes only, and represents the common.TxType of a new batch
var TypeNewBatchL1 common.TxType = "InstrTypeNewBatchL1"
TypeNewBatchL1 is used for testing purposes only, and represents the common.TxType of a new batch
var TypeNewBlock common.TxType = "InstrTypeNewBlock"
TypeNewBlock is used for testing purposes only, and represents the common.TxType of a new ethereum block
Functions ¶
func L1TxsToCommonL1Txs ¶
L1TxsToCommonL1Txs converts an array of []til.L1Tx to []common.L1Tx
Types ¶
type ConfigExtra ¶
type ConfigExtra struct { // Address to set as forger for each batch BootCoordAddr ethCommon.Address // Coordinator user name used to select the corresponding accounts to // collect coordinator fees CoordUser string }
ConfigExtra is the configuration used in FillBlocksExtra to extend the blocks returned by til.
type Context ¶
type Context struct { Users map[string]*User // Name -> *User UsersByIdx map[int]*User LastRegisteredTokenID common.TokenID Queues [][]L1Tx ToForgeNum int // contains filtered or unexported fields }
Context contains the data of the test
func NewContext ¶
NewContext returns a new Context
func (*Context) FillBlocksExtra ¶
func (tc *Context) FillBlocksExtra(blocks []common.BlockData, cfg *ConfigExtra) error
FillBlocksExtra fills extra fields not generated by til in each block, so that the blockData is closer to what the HistoryDB stores. The filled fields are: - blocks[].Rollup.Batch.EthBlockNum - blocks[].Rollup.Batch.ForgerAddr - blocks[].Rollup.Batch.ForgeL1TxsNum - blocks[].Rollup.Batch.L1CoordinatorTxs[].TxID - blocks[].Rollup.Batch.L1CoordinatorTxs[].BatchNum - blocks[].Rollup.Batch.L1CoordinatorTxs[].EthBlockNum - blocks[].Rollup.Batch.L1CoordinatorTxs[].Position - blocks[].Rollup.Batch.L1CoordinatorTxs[].EffectiveAmount - blocks[].Rollup.Batch.L1CoordinatorTxs[].EffectiveDepositAmount - blocks[].Rollup.Batch.L1CoordinatorTxs[].EffectiveFromIdx - blocks[].Rollup.Batch.L2Txs[].TxID - blocks[].Rollup.Batch.L2Txs[].Position - blocks[].Rollup.Batch.L2Txs[].Nonce - blocks[].Rollup.Batch.L2Txs[].TokenID - blocks[].Rollup.Batch.ExitTree - blocks[].Rollup.Batch.CreatedAccounts - blocks[].Rollup.Batch.FeeIdxCoordinator - blocks[].Rollup.Batch.CollectedFees
func (*Context) FillBlocksForgedL1UserTxs ¶
FillBlocksForgedL1UserTxs fills the L1UserTxs of a batch with the L1UserTxs that are forged in that batch. It always sets `EffectiveAmount` = `Amount` and `EffectiveDepositAmount` = `DepositAmount`. This function requires a previous call to `FillBlocksExtra`. - blocks[].Rollup.L1UserTxs[].BatchNum - blocks[].Rollup.L1UserTxs[].EffectiveAmount - blocks[].Rollup.L1UserTxs[].EffectiveDepositAmount - blocks[].Rollup.L1UserTxs[].EffectiveFromIdx
func (*Context) FillBlocksL1UserTxsBatchNum ¶
FillBlocksL1UserTxsBatchNum fills the BatchNum of forged L1UserTxs: - blocks[].Rollup.L1UserTxs[].BatchNum
func (*Context) GenerateBlocks ¶
GenerateBlocks returns an array of BlockData for a given set made of a string. It uses the users (keys & nonces) of the Context.
func (*Context) GenerateBlocksFromInstructions ¶
func (tc *Context) GenerateBlocksFromInstructions(set []Instruction) ([]common.BlockData, error)
GenerateBlocksFromInstructions returns an array of BlockData for a given set made of instructions. It uses the users (keys & nonces) of the Context.
func (*Context) GeneratePoolL2Txs ¶
GeneratePoolL2Txs returns an array of common.PoolL2Tx from a given set made of a string. It uses the users (keys) of the Context.
func (*Context) GeneratePoolL2TxsFromInstructions ¶
func (tc *Context) GeneratePoolL2TxsFromInstructions(set []Instruction) ([]common.PoolL2Tx, error)
GeneratePoolL2TxsFromInstructions returns an array of common.PoolL2Tx from a given set made of instructions. It uses the users (keys) of the Context.
func (*Context) RestartNonces ¶
func (tc *Context) RestartNonces()
RestartNonces sets all the Users.Accounts.Nonces to 0
type Instruction ¶
type Instruction struct { LineNum int Literal string From string To string Amount *big.Int DepositAmount *big.Int Fee uint8 TokenID common.TokenID Typ common.TxType // D: Deposit, T: Transfer, E: ForceExit }
Instruction is the data structure that represents one line of code
func (Instruction) String ¶
func (i Instruction) String() string
type L1Tx ¶
L1Tx is the data structure used internally for transaction test generation, which contains a common.L1Tx data plus some intermediate data for the transaction generation.
type L2Tx ¶
L2Tx is the data structure used internally for transaction test generation, which contains a common.L2Tx data plus some intermediate data for the transaction generation.