tx_field tables (#2849)

Drive the checking of whether tx_field can set a particular field in a table-driven way, rather than by simple switch. This is cleaner as we add functionality in later versions, and will allow generating the spec for tx_field.

Author: jannotti

cmd/opdoc/opdoc.go

@@ -159,7 +159,11 @@ func opToMarkdown(out io.Writer, op *logic.OpSpec) (err error) {
 			if cost.From == cost.To {
 				fmt.Fprintf(out, "   - %d (LogicSigVersion = %d)\n", cost.Cost, cost.To)
 			} else {
-				fmt.Fprintf(out, "   - %d (%d <= LogicSigVersion <= %d)\n", cost.Cost, cost.From, cost.To)
+				if cost.To < logic.LogicVersion {
+					fmt.Fprintf(out, "   - %d (%d <= LogicSigVersion <= %d)\n", cost.Cost, cost.From, cost.To)
+				} else {
+					fmt.Fprintf(out, "   - %d (LogicSigVersion >= %d)\n", cost.Cost, cost.From)
+				}
 			}
 		}
 	} else {

data/transactions/logic/README.md

@@ -148,10 +148,10 @@ various sizes.
 | `substring s e` | pop a byte-array A. For immediate values in 0..255 S and E: extract a range of bytes from A starting at S up to but not including E, push the substring result. If E < S, or either is larger than the array length, the program fails |
 | `substring3` | pop a byte-array A and two integers B and C. Extract a range of bytes from A starting at B up to but not including C, push the substring result. If C < B, or either is larger than the array length, the program fails |
 | `extract s l` | pop a byte-array A. For immediate values in 0..255 S and L: extract a range of bytes from A starting at S up to but not including S+L, push the substring result. If L is 0, then extract to the end of the string. If S or S+L is larger than the array length, the program fails |
-| `extract3` | pop a byte-array A and two integers B and C. Extract a range of bytes from A starting at B up to but not including B+C, push the substring result. If B or B+C is larger than the array length, the program fails |
-| `extract16bits` | pop a byte-array A and integer B. Extract a range of bytes from A starting at B up to but not including B+2, convert bytes as big endian and push the uint64 result. If B or B+2 is larger than the array length, the program fails |
-| `extract32bits` | pop a byte-array A and integer B. Extract a range of bytes from A starting at B up to but not including B+4, convert bytes as big endian and push the uint64 result. If B or B+4 is larger than the array length, the program fails |
-| `extract64bits` | pop a byte-array A and integer B. Extract a range of bytes from A starting at B up to but not including B+8, convert bytes as big endian and push the uint64 result. If B or B+8 is larger than the array length, the program fails |
+| `extract3` | pop a byte-array A and two integers B and C. Extract a range of bytes from A starting at B up to but not including B+C, push the substring result. If B+C is larger than the array length, the program fails |
+| `extract16bits` | pop a byte-array A and integer B. Extract a range of bytes from A starting at B up to but not including B+2, convert bytes as big endian and push the uint64 result. If B+2 is larger than the array length, the program fails |
+| `extract32bits` | pop a byte-array A and integer B. Extract a range of bytes from A starting at B up to but not including B+4, convert bytes as big endian and push the uint64 result. If B+4 is larger than the array length, the program fails |
+| `extract64bits` | pop a byte-array A and integer B. Extract a range of bytes from A starting at B up to but not including B+8, convert bytes as big endian and push the uint64 result. If B+8 is larger than the array length, the program fails |
 
 These opcodes take byte-array values that are interpreted as
 big-endian unsigned integers.  For mathematical operators, the
@@ -197,9 +197,9 @@ The following opcodes allow for the construction and submission of
 
 | Op | Description |
 | --- | --- |
-| `tx_begin` | Prepare a new application action |
-| `tx_field f` | Set field F of the current application action |
-| `tx_submit` | Execute the current application action. Panic on any failure. |
+| `tx_begin` | Begin preparation of a new inner transaction |
+| `tx_field f` | Set field F of the current inner transaction to X |
+| `tx_submit` | Execute the current inner transaction. Panic on any failure. |
 
 
 ### Loading Values
@@ -390,7 +390,7 @@ App fields used in the `app_params_get` opcode.
 | `dup` | duplicate last value on stack |
 | `dup2` | duplicate two last values on stack: A, B -> A, B, A, B |
 | `dig n` | push the Nth value from the top of the stack. dig 0 is equivalent to dup |
-| `cover n` | remove top of stack, and place it down the stack such that N elements are above it |
+| `cover n` | remove top of stack, and place it deeper in the stack such that N elements are above it |
 | `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 |
 | `swap` | swaps two last values on stack: A, B -> B, A |
 | `select` | selects one of two values based on top-of-stack: A, B, C -> (if C != 0 then B else A) |

data/transactions/logic/TEAL_opcodes.md

@@ -18,7 +18,7 @@ Ops have a 'cost' of 1 unless otherwise specified.
 - SHA256 hash of value X, yields [32]byte
 - **Cost**:
    - 7 (LogicSigVersion = 1)
-   - 35 (2 <= LogicSigVersion <= 5)
+   - 35 (LogicSigVersion >= 2)
 
 ## keccak256
 
@@ -28,7 +28,7 @@ Ops have a 'cost' of 1 unless otherwise specified.
 - Keccak256 hash of value X, yields [32]byte
 - **Cost**:
    - 26 (LogicSigVersion = 1)
-   - 130 (2 <= LogicSigVersion <= 5)
+   - 130 (LogicSigVersion >= 2)
 
 ## sha512_256
 
@@ -38,7 +38,7 @@ Ops have a 'cost' of 1 unless otherwise specified.
 - SHA512_256 hash of value X, yields [32]byte
 - **Cost**:
    - 9 (LogicSigVersion = 1)
-   - 45 (2 <= LogicSigVersion <= 5)
+   - 45 (LogicSigVersion >= 2)
 
 ## ed25519verify
 
@@ -667,7 +667,7 @@ See `bnz` for details on how branches work. `b` always jumps to the offset.
 - Opcode: 0x4e {uint8 depth}
 - Pops: *... stack*, any
 - Pushes: any
-- remove top of stack, and place it down the stack such that N elements are above it
+- remove top of stack, and place it deeper in the stack such that N elements are above it
 - LogicSigVersion >= 5
 
 ## uncover n
@@ -753,31 +753,31 @@ When A is a uint64, index 0 is the least significant bit. Setting bit 3 to 1 on
 - Opcode: 0x58
 - Pops: *... stack*, {[]byte A}, {uint64 B}, {uint64 C}
 - Pushes: []byte
-- pop a byte-array A and two integers B and C. Extract a range of bytes from A starting at B up to but not including B+C, push the substring result. If B or B+C is larger than the array length, the program fails
+- pop a byte-array A and two integers B and C. Extract a range of bytes from A starting at B up to but not including B+C, push the substring result. If B+C is larger than the array length, the program fails
 - LogicSigVersion >= 5
 
 ## extract16bits
 
 - Opcode: 0x59
 - Pops: *... stack*, {[]byte A}, {uint64 B}
 - Pushes: uint64
-- pop a byte-array A and integer B. Extract a range of bytes from A starting at B up to but not including B+2, convert bytes as big endian and push the uint64 result. If B or B+2 is larger than the array length, the program fails
+- pop a byte-array A and integer B. Extract a range of bytes from A starting at B up to but not including B+2, convert bytes as big endian and push the uint64 result. If B+2 is larger than the array length, the program fails
 - LogicSigVersion >= 5
 
 ## extract32bits
 
 - Opcode: 0x5a
 - Pops: *... stack*, {[]byte A}, {uint64 B}
 - Pushes: uint64
-- pop a byte-array A and integer B. Extract a range of bytes from A starting at B up to but not including B+4, convert bytes as big endian and push the uint64 result. If B or B+4 is larger than the array length, the program fails
+- pop a byte-array A and integer B. Extract a range of bytes from A starting at B up to but not including B+4, convert bytes as big endian and push the uint64 result. If B+4 is larger than the array length, the program fails
 - LogicSigVersion >= 5
 
 ## extract64bits
 
 - Opcode: 0x5b
 - Pops: *... stack*, {[]byte A}, {uint64 B}
 - Pushes: uint64
-- pop a byte-array A and integer B. Extract a range of bytes from A starting at B up to but not including B+8, convert bytes as big endian and push the uint64 result. If B or B+8 is larger than the array length, the program fails
+- pop a byte-array A and integer B. Extract a range of bytes from A starting at B up to but not including B+8, convert bytes as big endian and push the uint64 result. If B+8 is larger than the array length, the program fails
 - LogicSigVersion >= 5
 
 ## balance
@@ -1222,7 +1222,7 @@ bitlen interprets arrays as big-endian integers, unlike setbit/getbit
 - Opcode: 0xb1
 - Pops: _None_
 - Pushes: _None_
-- Prepare a new application action
+- Begin preparation of a new inner transaction
 - LogicSigVersion >= 5
 - Mode: Application
 
@@ -1231,7 +1231,7 @@ bitlen interprets arrays as big-endian integers, unlike setbit/getbit
 - Opcode: 0xb2 {uint8 transaction field index}
 - Pops: *... stack*, any
 - Pushes: _None_
-- Set field F of the current application action
+- Set field F of the current inner transaction to X
 - LogicSigVersion >= 5
 - Mode: Application
 
@@ -1240,7 +1240,7 @@ bitlen interprets arrays as big-endian integers, unlike setbit/getbit
 - Opcode: 0xb3
 - Pops: _None_
 - Pushes: _None_
-- Execute the current application action. Panic on any failure.
+- Execute the current inner transaction. Panic on any failure.
 - LogicSigVersion >= 5
 - Mode: Application
 

data/transactions/logic/assembler.go

@@ -2552,7 +2552,7 @@ func disTxField(dis *disassembleState, spec *OpSpec) (string, error) {
 	dis.nextpc = dis.pc + 2
 	arg := dis.program[dis.pc+1]
 	if int(arg) >= len(TxnFieldNames) {
-		return "", fmt.Errorf("invalid txfield arg index %d at pc=%d", arg, dis.pc)
+		return "", fmt.Errorf("invalid %s arg index %d at pc=%d", spec.Name, arg, dis.pc)
 	}
 	return fmt.Sprintf("%s %s", spec.Name, TxnFieldNames[arg]), nil
 }

data/transactions/logic/doc.go

@@ -100,7 +100,7 @@ var opDocByName = map[string]string{
 	"dup":           "duplicate last value on stack",
 	"dup2":          "duplicate two last values on stack: A, B -> A, B, A, B",
 	"dig":           "push the Nth value from the top of the stack. dig 0 is equivalent to dup",
-	"cover":         "remove top of stack, and place it down the stack such that N elements are above it",
+	"cover":         "remove top of stack, and place it deeper in the stack such that N elements are above it",
 	"uncover":       "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",
 	"swap":          "swaps two last values on stack: A, B -> B, A",
 	"select":        "selects one of two values based on top-of-stack: A, B, C -> (if C != 0 then B else A)",
@@ -112,10 +112,10 @@ var opDocByName = map[string]string{
 	"getbyte":       "pop a byte-array A and integer B. Extract the Bth byte of A and push it as an integer",
 	"setbyte":       "pop a byte-array A, integer B, and small integer C (between 0..255). Set the Bth byte of A to C, and push the result",
 	"extract":       "pop a byte-array A. For immediate values in 0..255 S and L: extract a range of bytes from A starting at S up to but not including S+L, push the substring result. If L is 0, then extract to the end of the string. If S or S+L is larger than the array length, the program fails",
-	"extract3":      "pop a byte-array A and two integers B and C. Extract a range of bytes from A starting at B up to but not including B+C, push the substring result. If B or B+C is larger than the array length, the program fails",
-	"extract16bits": "pop a byte-array A and integer B. Extract a range of bytes from A starting at B up to but not including B+2, convert bytes as big endian and push the uint64 result. If B or B+2 is larger than the array length, the program fails",
-	"extract32bits": "pop a byte-array A and integer B. Extract a range of bytes from A starting at B up to but not including B+4, convert bytes as big endian and push the uint64 result. If B or B+4 is larger than the array length, the program fails",
-	"extract64bits": "pop a byte-array A and integer B. Extract a range of bytes from A starting at B up to but not including B+8, convert bytes as big endian and push the uint64 result. If B or B+8 is larger than the array length, the program fails",
+	"extract3":      "pop a byte-array A and two integers B and C. Extract a range of bytes from A starting at B up to but not including B+C, push the substring result. If B+C is larger than the array length, the program fails",
+	"extract16bits": "pop a byte-array A and integer B. Extract a range of bytes from A starting at B up to but not including B+2, convert bytes as big endian and push the uint64 result. If B+2 is larger than the array length, the program fails",
+	"extract32bits": "pop a byte-array A and integer B. Extract a range of bytes from A starting at B up to but not including B+4, convert bytes as big endian and push the uint64 result. If B+4 is larger than the array length, the program fails",
+	"extract64bits": "pop a byte-array A and integer B. Extract a range of bytes from A starting at B up to but not including B+8, convert bytes as big endian and push the uint64 result. If B+8 is larger than the array length, the program fails",
 
 	"balance":           "get balance for account A, in microalgos. The balance is observed after the effects of previous transactions in the group, and after the fee for the current transaction is deducted.",
 	"min_balance":       "get minimum required balance for account A, in microalgos. Required balance is affected by [ASA](https://developer.algorand.org/docs/features/asa/#assets-overview) and [App](https://developer.algorand.org/docs/features/asc1/stateful/#minimum-balance-requirement-for-a-smart-contract) usage. When creating or opting into an app, the minimum balance grows before the app code runs, therefore the increase is visible there. When deleting or closing out, the minimum balance decreases after the app executes.",
@@ -152,9 +152,9 @@ var opDocByName = map[string]string{
 	"b~":  "X with all bits inverted",
 
 	"log":       "write bytes to log state of the current application",
-	"tx_begin":  "Prepare a new application action",
-	"tx_field":  "Set field F of the current application action",
-	"tx_submit": "Execute the current application action. Panic on any failure.",
+	"tx_begin":  "Begin preparation of a new inner transaction",
+	"tx_field":  "Set field F of the current inner transaction to X",
+	"tx_submit": "Execute the current inner transaction. Panic on any failure.",
 
 	"txnas":   "push Xth value of the array field F of the current transaction",
 	"gtxnas":  "push Xth value of the array field F from the Tth transaction in the current group",