til

package
v1.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 13, 2021 License: AGPL-3.0 Imports: 18 Imported by: 0

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

View Source 
const (
	ILLEGAL token = iota
	WS
	EOF

	IDENT // val
)

nolint

Variables

View Source 
var SetTypeBlockchain = setType("Blockchain")

SetTypeBlockchain defines the type 'Blockchain' of the set

View Source 
var SetTypePoolL2 = setType("PoolL2")

SetTypePoolL2 defines the type 'PoolL2' of the set

View Source 
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

View Source 
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).

View Source 
var TypeNewBatch common.TxType = "InstrTypeNewBatch"

TypeNewBatch is used for testing purposes only, and represents the common.TxType of a new batch

View Source 
var TypeNewBatchL1 common.TxType = "InstrTypeNewBatchL1"

TypeNewBatchL1 is used for testing purposes only, and represents the common.TxType of a new batch

View Source 
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 

func L1TxsToCommonL1Txs(l1 []L1Tx) []common.L1Tx

L1TxsToCommonL1Txs converts an array of []til.L1Tx to []common.L1Tx

Types

type Account 

type Account struct {
	Idx      common.Idx
	TokenID  common.TokenID
	Nonce    nonce.Nonce
	BatchNum int
}

Account contains the data related to the account for a specific TokenID of a User

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 

func NewContext(chainID uint16, rollupConstMaxL1UserTx int) *Context

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 

func (tc *Context) FillBlocksForgedL1UserTxs(blocks []common.BlockData) error

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 

func (tc *Context) FillBlocksL1UserTxsBatchNum(blocks []common.BlockData)

FillBlocksL1UserTxsBatchNum fills the BatchNum of forged L1UserTxs: - blocks[].Rollup.L1UserTxs[].BatchNum

func (*Context) GenerateBlocks 

func (tc *Context) GenerateBlocks(set string) ([]common.BlockData, error)

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 

func (tc *Context) GeneratePoolL2Txs(set string) ([]common.PoolL2Tx, error)

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 

type L1Tx struct {
	L1Tx common.L1Tx
	// contains filtered or unexported fields
}

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 

type L2Tx struct {
	L2Tx common.L2Tx
	// contains filtered or unexported fields
}

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.

type User 

type User struct {
	Name     string
	BJJ      *babyjub.PrivateKey
	EthSk    *ecdsa.PrivateKey
	Addr     ethCommon.Address
	Accounts map[common.TokenID]*Account
}

User contains the data related to a testing user

func NewUser added in v1.6.0 

func NewUser(keyDerivationIndex int, name string) User

NewUser creates a User deriving its keys at the path keyDerivationIndex

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.