AVM: frame pointers

data/transactions/logic/README.md

@@ -584,15 +584,21 @@ Account fields used in the `acct_params_get` opcode.
 | `b target` | branch unconditionally to TARGET |
 | `return` | use A as success value; end |
 | `pop` | discard A |
+| `popn n` | Remove N values from the top of the stack |
 | `dup` | duplicate A |
 | `dup2` | duplicate A and B |
+| `dupn n` | duplicate A, N times |
 | `dig n` | Nth value from the top of the stack. dig 0 is equivalent to dup |
+| `bury n` | Replace the Nth value from the top of the stack. bury 0 fails. |
 | `cover n` | remove top of stack, and place it deeper in the stack such that N elements are above it. Fails if stack depth <= N. |
 | `uncover n` | remove the value at depth N in the stack and shift above items down so the Nth deep value is on top of the stack. Fails if stack depth <= N. |
+| `frame_dig i` | Nth (signed) value from the frame pointer. |
+| `frame_bury i` | Replace the Nth (signed) value from the frame pointer in the stack |
 | `swap` | swaps A and B on stack |
 | `select` | selects one of two values based on top-of-stack: B if C != 0, else A |
 | `assert` | immediately fail unless A is a non-zero number |
 | `callsub target` | branch unconditionally to TARGET, saving the next instruction on the call stack |
+| `proto a r` | Prepare top call frame for a retsub that will assume A args and R return values. |
 | `retsub` | pop the top instruction from the call stack and branch to it |
 | `switch target ...` | branch to the Ath label. Continue at following instruction if index A exceeds the number of labels. |
 

data/transactions/logic/TEAL_opcodes.md

@@ -610,6 +610,27 @@ See `bnz` for details on how branches work. `b` always jumps to the offset.
 - immediately fail unless A is a non-zero number
 - Availability: v3
 
+## bury n
+
+- Opcode: 0x45 {uint8 depth}
+- Stack: ..., A → ...
+- Replace the Nth value from the top of the stack. bury 0 fails.
+- Availability: v8
+
+## popn n
+
+- Opcode: 0x46 {uint8 stack depth}
+- Stack: ..., [N items] → ...
+- Remove N values from the top of the stack
+- Availability: v8
+
+## dupn n
+
+- Opcode: 0x47 {uint8 copy count}
+- Stack: ..., A → ..., A, [N copies of A]
+- duplicate A, N times
+- Availability: v8
+
 ## pop
 
 - Opcode: 0x48
@@ -790,7 +811,7 @@ When A is a uint64, index 0 is the least significant bit. Setting bit 3 to 1 on
 
 ## json_ref r
 
-- Opcode: 0x5f {string return type}
+- Opcode: 0x5f {uint8 return type}
 - Stack: ..., A: []byte, B: []byte → ..., any
 - key B's value, of type R, from a [valid](jsonspec.md) utf-8 encoded json object A
 - **Cost**: 25 + 2 per 7 bytes of A
@@ -1042,7 +1063,7 @@ pushint args are not added to the intcblock during assembly processes
 - branch unconditionally to TARGET, saving the next instruction on the call stack
 - Availability: v4
 
-The call stack is separate from the data stack. Only `callsub` and `retsub` manipulate it.
+The call stack is separate from the data stack. Only `callsub`, `retsub`, and `proto` manipulate it.
 
 ## retsub
 
@@ -1051,11 +1072,34 @@ The call stack is separate from the data stack. Only `callsub` and `retsub` mani
 - pop the top instruction from the call stack and branch to it
 - Availability: v4
 
-The call stack is separate from the data stack. Only `callsub` and `retsub` manipulate it.
+If the current frame was prepared by `proto A R`, `retsub` will remove the 'A' arguments from the stack, move the `R` return values down, and pop any stack locations above the relocated return values.
+
+## proto a r
+
+- Opcode: 0x8a {uint8 arguments} {uint8 return values}
+- Stack: ... → ...
+- Prepare top call frame for a retsub that will assume A args and R return values.
+- Availability: v8
+
+Fails unless the last instruction executed was a `callsub`.
+
+## frame_dig i
+
+- Opcode: 0x8b {int8 frame slot}
+- Stack: ... → ..., any
+- Nth (signed) value from the frame pointer.
+- Availability: v8
+
+## frame_bury i
+
+- Opcode: 0x8c {int8 frame slot}
+- Stack: ..., A → ...
+- Replace the Nth (signed) value from the frame pointer in the stack
+- Availability: v8
 
 ## switch target ...
 
-- Opcode: 0x8a {uint8 branch count} [{int16 branch offset, big-endian}, ...]
+- Opcode: 0x8d {uint8 branch count} [{int16 branch offset, big-endian}, ...]
 - Stack: ..., A: uint64 → ...
 - branch to the Ath label. Continue at following instruction if index A exceeds the number of labels.
 - Availability: v8