Continuation and control flow primitives
TVM Instructions Content List
- Overview
- Stack Manipulation
- Tuple, List and Null
- Constants and Literals
- Arithmetic Operations
- Data Comparison
- Cell Manipulation
- Continuation and Control Flow
- Exception Generation and Handling
- Dictionary Manipulation
- Application-specific Primitives
- Miscellaneous
| Opcode | Fift syntax | Stack | Description | Gas |
|---|---|---|---|---|
| Please enter a search query | ||||
| No results found | ||||
Continuation and control flow primitives
Unconditional control flow primitives
| xxxxxxx Opcode | xxxxxxxxxxxxxxxxxxxxxxxxxxxx Fift syntax | xxxxxxxxxxxxxxxxx Stack | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Description | xxxx Gas |
|---|---|---|---|---|
D8 | EXECUTECALLX | c - | Calls, or executes, continuation c. | 18 |
D9 | JMPX | c - | Jumps, or transfers control, to continuation c.The remainder of the previous current continuation cc is discarded. | 18 |
DApr | [p] [r] CALLXARGS | c - | Calls continuation c with p parameters and expecting r return values0 <= p <= 15, 0 <= r <= 15 | 26 |
DB0p | [p] -1 CALLXARGS | c - | Calls continuation c with 0 <= p <= 15 parameters, expecting an arbitrary number of return values. | 26 |
DB1p | [p] JMPXARGS | c - | Jumps to continuation c, passing only the top 0 <= p <= 15 values from the current stack to it (the remainder of the current stack is discarded). | 26 |
DB2r | [r] RETARGS | Returns to c0, with 0 <= r <= 15 return values taken from the current stack. | 26 | |
DB30 | RETRETTRUE | Returns to the continuation at c0. The remainder of the current continuation cc is discarded.Approximately equivalent to c0 PUSHCTR JMPX. | 26 | |
DB31 | RETALTRETFALSE | Returns to the continuation at c1.Approximately equivalent to c1 PUSHCTR JMPX. | 26 | |
DB32 | BRANCHRETBOOL | f - | Performs RETTRUE if integer f!=0, or RETFALSE if f=0. | 26 |
DB34 | CALLCC | c - | Call with current continuation, transfers control to c, pushing the old value of cc into c's stack (instead of discarding it or writing it into new c0). | 26 |
DB35 | JMPXDATA | c - | Similar to CALLCC, but the remainder of the current continuation (the old value of cc) is converted into a Slice before pushing it into the stack of c. | 26 |
DB36pr | [p] [r] CALLCCARGS | c - | Similar to CALLXARGS, but pushes the old value of cc (along with the top 0 <= p <= 15 values from the original stack) into the stack of newly-invoked continuation c, setting cc.nargs to -1 <= r <= 14. | 34 |
DB38 | CALLXVARARGS | c p r - | Similar to CALLXARGS, but takes -1 <= p,r <= 254 from the stack. The next three operations also take p and r from the stack, both in the range -1...254. | 26 |
DB39 | RETVARARGS | p r - | Similar to RETARGS. | 26 |
DB3A | JMPXVARARGS | c p r - | Similar to JMPXARGS. | 26 |
DB3B | CALLCCVARARGS | c p r - | Similar to CALLCCARGS. | 26 |
DB3C | [ref] CALLREF | Equivalent to PUSHREFCONT CALLX. | 126/51 | |
DB3D | [ref] JMPREF | Equivalent to PUSHREFCONT JMPX. | 126/51 | |
DB3E | [ref] JMPREFDATA | Equivalent to PUSHREFCONT JMPXDATA. | 126/51 | |
DB3F | RETDATA | Equivalent to c0 PUSHCTR JMPXDATA. In this way, the remainder of the current continuation is converted into a Slice and returned to the caller. | 26 |
Conditional control flow primitives
| xxxxxxx Opcode | xxxxxxxxxxxxxxxxxxxxxxxxxxxx Fift syntax | xxxxxxxxxxxxxxxxx Stack | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Description | xxxx Gas |
|---|---|---|---|---|
DC | IFRETIFNOT: | f - | Performs a RET, but only if integer f is non-zero. If f is a NaN, throws an integer overflow exception. | 18 |
DD | IFNOTRETIF: | f - | Performs a RET, but only if integer f is zero. | 18 |
DE | IF | f c - | Performs EXECUTE for c (i.e., executes c), but only if integer f is non-zero. Otherwise simply discards both values. | 18 |
DE | IF:<{ code }><{ code }>IF | f - | Equivalent to <{ code }> CONT IF. | |
DF | IFNOT | f c - | Executes continuation c, but only if integer f is zero. Otherwise simply discards both values. | 18 |
DF | IFNOT:<{ code }><{ code }>IFNOT | f - | Equivalent to <{ code }> CONT IFNOT. | |
E0 | IFJMP | f c - | Jumps to c (similarly to JMPX), but only if f is non-zero. | 18 |
E0 | IFJMP:<{ code }> | f - | Equivalent to <{ code }> CONT IFJMP. | |
E1 | IFNOTJMP | f c - | Jumps to c (similarly to JMPX), but only if f is zero. | 18 |
E1 | IFNOTJMP:<{ code }> | f - | Equivalent to <{ code }> CONT IFNOTJMP. | |
E2 | IFELSE | f c c' - | If integer f is non-zero, executes c, otherwise executes c'. Equivalent to CONDSELCHK EXECUTE. | 18 |
E2 | IF:<{ code1 }>ELSE<{ code2 }> | f - | Equivalent to <{ code1 }> CONT <{ code2 }> CONT IFELSE. | |
E300 | [ref] IFREF | f - | Equivalent to PUSHREFCONT IF, with the optimization that the cell reference is not actually loaded into a Slice and then converted into an ordinary Continuation if f=0.Gas consumption of this primitive depends on whether f=0 and whether the reference was loaded before.Similar remarks apply other primitives that accept a continuation as a reference. | 26/126/51 |
E301 | [ref] IFNOTREF | f - | Equivalent to PUSHREFCONT IFNOT. | 26/126/51 |
E302 | [ref] IFJMPREF | f - | Equivalent to PUSHREFCONT IFJMP. | 26/126/51 |
E303 | [ref] IFNOTJMPREF | f - | Equivalent to PUSHREFCONT IFNOTJMP. | 26/126/51 |
E304 | CONDSEL | f x y - x or y | If integer f is non-zero, returns x, otherwise returns y. Notice that no type checks are performed on x and y; as such, it is more like a conditional stack operation. Roughly equivalent to ROT ISZERO INC ROLLX NIP. | 26 |
E305 | CONDSELCHK | f x y - x or y | Same as CONDSEL, but first checks whether x and y have the same type. | 26 |
E308 | IFRETALT | f - | Performs RETALT if integer f!=0. | 26 |
E309 | IFNOTRETALT | f - | Performs RETALT if integer f=0. | 26 |
E30D | [ref] IFREFELSE | f c - | Equivalent to PUSHREFCONT SWAP IFELSE, with the optimization that the cell reference is not actually loaded into a Slice and then converted into an ordinary Continuation if f=0. Similar remarks apply to the next two primitives: cells are converted into continuations only when necessary. | 26/126/51 |
E30E | [ref] IFELSEREF | f c - | Equivalent to PUSHREFCONT IFELSE. | 26/126/51 |
E30F | [ref] [ref] IFREFELSEREF | f - | Equivalent to PUSHREFCONT PUSHREFCONT IFELSE. | 126/51 |
E39_n | [n] IFBITJMP | x c - x | Checks whether bit 0 <= n <= 31 is set in integer x, and if so, performs JMPX to continuation c. Value x is left in the stack. | 26 |
E3B_n | [n] IFNBITJMP | x c - x | Jumps to c if bit 0 <= n <= 31 is not set in integer x. | 26 |
E3D_n | [ref] [n] IFBITJMPREF | x - x | Performs a JMPREF if bit 0 <= n <= 31 is set in integer x. | 126/51 |
E3F_n | [ref] [n] IFNBITJMPREF | x - x | Performs a JMPREF if bit 0 <= n <= 31 is not set in integer x. | 126/51 |
Control flow primitives: loops
| xxxxxxx Opcode | xxxxxxxxxxxxxxxxxxxxxxxxxxxx Fift syntax | xxxxxxxxxxxxxxxxx Stack | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Description | xxxx Gas |
|---|---|---|---|---|
E4 | REPEAT | n c - | Executes continuation c n times, if integer n is non-negative. If n>=2^31 or n<-2^31, generates a range check exception.Notice that a RET inside the code of c works as a continue, not as a break. One should use either alternative (experimental) loops or alternative RETALT (along with a SETEXITALT before the loop) to break out of a loop. | 18 |
E4 | REPEAT:<{ code }><{ code }>REPEAT | n - | Equivalent to <{ code }> CONT REPEAT. | |
E5 | REPEATENDREPEAT: | n - | Similar to REPEAT, but it is applied to the current continuation cc. | 18 |
E6 | UNTIL | c - | Executes continuation c, then pops an integer x from the resulting stack. If x is zero, performs another iteration of this loop. The actual implementation of this primitive involves an extraordinary continuation ec_until with its arguments set to the body of the loop (continuation c) and the original current continuation cc. This extraordinary continuation is then saved into the savelist of c as c.c0 and the modified c is then executed. The other loop primitives are implemented similarly with the aid of suitable extraordinary continuations. | 18 |
E6 | UNTIL:<{ code }><{ code }>UNTIL | - | Equivalent to <{ code }> CONT UNTIL. | |
E7 | UNTILENDUNTIL: | - | Similar to UNTIL, but executes the current continuation cc in a loop. When the loop exit condition is satisfied, performs a RET. | 18 |
E8 | WHILE | c' c - | Executes c' and pops an integer x from the resulting stack. If x is zero, exists the loop and transfers control to the original cc. If x is non-zero, executes c, and then begins a new iteration. | 18 |
E8 | WHILE:<{ cond }>DO<{ code }> | - | Equivalent to <{ cond }> CONT <{ code }> CONT WHILE. | |
E9 | WHILEEND | c' - | Similar to WHILE, but uses the current continuation cc as the loop body. | 18 |
EA | AGAIN | c - | Similar to REPEAT, but executes c infinitely many times. A RET only begins a new iteration of the infinite loop, which can be exited only by an exception, or a RETALT (or an explicit JMPX). | 18 |
EA | AGAIN:<{ code }><{ code }>AGAIN | - | Equivalent to <{ code }> CONT AGAIN. | |
EB | AGAINENDAGAIN: | - | Similar to AGAIN, but performed with respect to the current continuation cc. | 18 |
E314 | REPEATBRK | n c - | Similar to REPEAT, but also sets c1 to the original cc after saving the old value of c1 into the savelist of the original cc. In this way RETALT could be used to break out of the loop body. | 26 |
E314 | REPEATBRK:<{ code }><{ code }>REPEATBRK | n - | Equivalent to <{ code }> CONT REPEATBRK. | |
E315 | REPEATENDBRK | n - | Similar to REPEATEND, but also sets c1 to the original c0 after saving the old value of c1 into the savelist of the original c0. Equivalent to SAMEALTSAVE REPEATEND. | 26 |
E316 | UNTILBRK | c - | Similar to UNTIL, but also modifies c1 in the same way as REPEATBRK. | 26 |
E316 | UNTILBRK:<{ code }> | - | Equivalent to <{ code }> CONT UNTILBRK. | |
E317 | UNTILENDBRKUNTILBRK: | - | Equivalent to SAMEALTSAVE UNTILEND. | 26 |
E318 | WHILEBRK | c' c - | Similar to WHILE, but also modifies c1 in the same way as REPEATBRK. | 26 |
E318 | WHILEBRK:<{ cond }>DO<{ code }> | - | Equivalent to <{ cond }> CONT <{ code }> CONT WHILEBRK. | |
E319 | WHILEENDBRK | c - | Equivalent to SAMEALTSAVE WHILEEND. | 26 |
E31A | AGAINBRK | c - | Similar to AGAIN, but also modifies c1 in the same way as REPEATBRK. | 26 |
E31A | AGAINBRK:<{ code }> | - | Equivalent to <{ code }> CONT AGAINBRK. | |
E31B | AGAINENDBRKAGAINBRK: | - | Equivalent to SAMEALTSAVE AGAINEND. | 26 |
Manipulating the stack of continuations
Here s" is the fee for moving stack elements between continuations. It is equal to the size of the resulting stack minus 32 (or 0 if the stack is smaller than 32).
| xxxxxxx Opcode | xxxxxxxxxxxxxxxxxxxxxxxxxxxx Fift syntax | xxxxxxxxxxxxxxxxx Stack | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Description | xxxx Gas |
|---|---|---|---|---|
ECrn | [r] [n] SETCONTARGS | x_1 x_2...x_r c - c' | Similar to [r] -1 SETCONTARGS, but sets c.nargs to the final size of the stack of c' plus n. In other words, transforms c into a closure or a partially applied function, with 0 <= n <= 14 arguments missing. | 26+s” |
EC0n | [n] SETNUMARGS | c - c' | Sets c.nargs to n plus the current depth of c's stack, where 0 <= n <= 14. If c.nargs is already set to a non-negative value, does nothing. | 26 |
ECrF | [r] -1 SETCONTARGS | x_1 x_2...x_r c - c' | Pushes 0 <= r <= 15 values x_1...x_r into the stack of (a copy of) the continuation c, starting with x_1. If the final depth of c's stack turns out to be greater than c.nargs, a stack overflow exception is generated. | 26+s” |
ED0p | [p] RETURNARGS | - | Leaves only the top 0 <= p <= 15 values in the current stack (somewhat similarly to ONLYTOPX), with all the unused bottom values not discarded, but saved into continuation c0 in the same way as SETCONTARGS does. | 26+s” |
ED10 | RETURNVARARGS | p - | Similar to RETURNARGS, but with Integer 0 <= p <= 255 taken from the stack. | 26+s” |
ED11 | SETCONTVARARGS | x_1 x_2...x_r c r n - c' | Similar to SETCONTARGS, but with 0 <= r <= 255 and -1 <= n <= 255 taken from the stack. | 26+s” |
ED12 | SETNUMVARARGS | c n - c' | -1 <= n <= 255If n=-1, this operation does nothing (c'=c).Otherwise its action is similar to [n] SETNUMARGS, but with n taken from the stack. | 26 |
Creating simple continuations and closures
| xxxxxxx Opcode | xxxxxxxxxxxxxxxxxxxxxxxxxxxx Fift syntax | xxxxxxxxxxxxxxxxx Stack | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Description | xxxx Gas |
|---|---|---|---|---|
ED1E | BLESS | s - c | Transforms a Slice s into a simple ordinary continuation c, with c.code=s and an empty stack and savelist. | 26 |
ED1F | BLESSVARARGS | x_1...x_r s r n - c | Equivalent to ROT BLESS ROTREV SETCONTVARARGS. | 26+s” |
EErn | [r] [n] BLESSARGS | x_1...x_r s - c | 0 <= r <= 15, -1 <= n <= 14Equivalent to BLESS [r] [n] SETCONTARGS.The value of n is represented inside the instruction by the 4-bit integer n mod 16. | 26 |
EE0n | [n] BLESSNUMARGS | s - c | Also transforms a Slice s into a Continuation c, but sets c.nargs to 0 <= n <= 14. | 26 |
Operations with continuation savelists and control registers
| xxxxxxx Opcode | xxxxxxxxxxxxxxxxxxxxxxxxxxxx Fift syntax | xxxxxxxxxxxxxxxxx Stack | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Description | xxxx Gas |
|---|---|---|---|---|
ED4i | c[i] PUSHCTRc[i] PUSH | - x | Pushes the current value of control register c(i). If the control register is not supported in the current codepage, or if it does not have a value, an exception is triggered. | 26 |
ED44 | c4 PUSHCTRc4 PUSH | - x | Pushes the “global data root'' cell reference, thus enabling access to persistent smart-contract data. | 26 |
ED5i | c[i] POPCTRc[i] POP | x - | Pops a value x from the stack and stores it into control register c(i), if supported in the current codepage. Notice that if a control register accepts only values of a specific type, a type-checking exception may occur. | 26 |
ED54 | c4 POPCTRc4 POP | x - | Sets the “global data root'' cell reference, thus allowing modification of persistent smart-contract data. | 26 |
ED6i | c[i] SETCONTc[i] SETCONTCTR | x c - c' | Stores x into the savelist of continuation c as c(i), and returns the resulting continuation c'. Almost all operations with continuations may be expressed in terms of SETCONTCTR, POPCTR, and PUSHCTR. | 26 |
ED7i | c[i] SETRETCTR | x - | Equivalent to c0 PUSHCTR c[i] SETCONTCTR c0 POPCTR. | 26 |
ED8i | c[i] SETALTCTR | x - | Equivalent to c1 PUSHCTR c[i] SETCONTCTR c1 POPCTR. | 26 |
ED9i | c[i] POPSAVEc[i] POPCTRSAVE | x - | Similar to c[i] POPCTR, but also saves the old value of c[i] into continuation c0.Equivalent (up to exceptions) to c[i] SAVECTR c[i] POPCTR. | 26 |
EDAi | c[i] SAVEc[i] SAVECTR | Saves the current value of c(i) into the savelist of continuation c0. If an entry for c[i] is already present in the savelist of c0, nothing is done. Equivalent to c[i] PUSHCTR c[i] SETRETCTR. | 26 | |
EDBi | c[i] SAVEALTc[i] SAVEALTCTR | Similar to c[i] SAVE, but saves the current value of c[i] into the savelist of c1, not c0. | 26 | |
EDCi | c[i] SAVEBOTHc[i] SAVEBOTHCTR | Equivalent to c[i] SAVE c[i] SAVEALT. | 26 | |
EDE0 | PUSHCTRX | i - x | Similar to c[i] PUSHCTR, but with i, 0 <= i <= 255, taken from the stack.Notice that this primitive is one of the few “exotic'' primitives, which are not polymorphic like stack manipulation primitives, and at the same time do not have well-defined types of parameters and return values, because the type of x depends on i. | 26 |
EDE1 | POPCTRX | x i - | Similar to c[i] POPCTR, but with 0 <= i <= 255 from the stack. | 26 |
EDE2 | SETCONTCTRX | x c i - c' | Similar to c[i] SETCONTCTR, but with 0 <= i <= 255 from the stack. | 26 |
EDF0 | COMPOSBOOLAND | c c' - c'' | Computes the composition compose0(c, c’), which has the meaning of “perform c, and, if successful, perform c''' (if c is a boolean circuit) or simply “perform c, then c'''. Equivalent to SWAP c0 SETCONT. | 26 |
EDF1 | COMPOSALTBOOLOR | c c' - c'' | Computes the alternative composition compose1(c, c’), which has the meaning of “perform c, and, if not successful, perform c''' (if c is a boolean circuit). Equivalent to SWAP c1 SETCONT. | 26 |
EDF2 | COMPOSBOTH | c c' - c'' | Computes composition compose1(compose0(c, c’), c’), which has the meaning of “compute boolean circuit c, then compute c', regardless of the result of c''. | 26 |
EDF3 | ATEXIT | c - | Sets c0 to compose0(c, c0). In other words, c will be executed before exiting current subroutine. | 26 |
EDF3 | ATEXIT:<{ code }><{ code }>ATEXIT | - | Equivalent to <{ code }> CONT ATEXIT. | |
EDF4 | ATEXITALT | c - | Sets c1 to compose1(c, c1). In other words, c will be executed before exiting current subroutine by its alternative return path. | 26 |
EDF4 | ATEXITALT:<{ code }><{ code }>ATEXITALT | - | Equivalent to <{ code }> CONT ATEXITALT. | |
EDF5 | SETEXITALT | c - | Sets c1 to compose1(compose0(c, c0), c1),In this way, a subsequent RETALT will first execute c, then transfer control to the original c0. This can be used, for instance, to exit from nested loops. | 26 |
EDF6 | THENRET | c - c' | Computes compose0(c, c0). | 26 |
EDF7 | THENRETALT | c - c' | Computes compose0(c, c1) | 26 |
EDF8 | INVERT | - | Interchanges c0 and c1. | 26 |
EDF9 | BOOLEVAL | c - ? | Performs cc:=compose1(compose0(c, compose0(-1 PUSHINT, cc)), compose0(0 PUSHINT, cc)). If c represents a boolean circuit, the net effect is to evaluate it and push either -1 or 0 into the stack before continuing. | 26 |
EDFA | SAMEALT | - | Sets c1 to c0. Equivalent to c0 PUSHCTR c1 POPCTR. | 26 |
EDFB | SAMEALTSAVE | - | Sets c1 to c0, but first saves the old value of c1 into the savelist of c0.Equivalent to c1 SAVE SAMEALT. | 26 |
Dictionary subroutine calls and jumps
| xxxxxxx Opcode | xxxxxxxxxxxxxxxxxxxxxxxxxxxx Fift syntax | xxxxxxxxxxxxxxxxx Stack | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Description | xxxx Gas |
|---|---|---|---|---|
F0nn | [nn] CALL[nn] CALLDICT | - nn | Calls the continuation in c3, pushing integer 0 <= nn <= 255 into its stack as an argument.Approximately equivalent to [nn] PUSHINT c3 PUSHCTR EXECUTE. | |
F12_n | [n] CALL[n] CALLDICT | - n | For 0 <= n < 2^14, an encoding of [n] CALL for larger values of n. | |
F16_n | [n] JMP | - n | Jumps to the continuation in c3, pushing integer 0 <= n < 2^14 as its argument.Approximately equivalent to n PUSHINT c3 PUSHCTR JMPX. | |
F1A_n | [n] PREPARE[n] PREPAREDICT | - n c | Equivalent to n PUSHINT c3 PUSHCTR, for 0 <= n < 2^14.In this way, [n] CALL is approximately equivalent to [n] PREPARE EXECUTE, and [n] JMP is approximately equivalent to [n] PREPARE JMPX.One might use, for instance, CALLXARGS or CALLCC instead of EXECUTE here. |