Teal4 math (#2139)

Add a lot of math oriented opcodes that have been requested by teal users.

sqrt, exp, expw, divmodw

byteslice oriented math - a set of opcodes that will treat byteslices as arbitrary precision uints.

Author: jannotti

cmd/opdoc/opdoc.go

@@ -28,13 +28,13 @@ import (
 	"github.com/algorand/go-algorand/protocol"
 )
 
-func opGroupMarkdownTable(og *logic.OpGroup, out io.Writer) {
+func opGroupMarkdownTable(names []string, out io.Writer) {
 	fmt.Fprint(out, `| Op | Description |
 | --- | --- |
 `)
 	opSpecs := logic.OpsByName[logic.LogicVersion]
 	// TODO: sort by logic.OpSpecs[].Opcode
-	for _, opname := range og.Ops {
+	for _, opname := range names {
 		spec := opSpecs[opname]
 		fmt.Fprintf(out, "| `%s%s` | %s |\n",
 			markdownTableEscape(spec.Name), immediateMarkdown(&spec),
@@ -314,14 +314,14 @@ func main() {
 	opsToMarkdown(opcodesMd)
 	opcodesMd.Close()
 	opGroups := make(map[string][]string, len(logic.OpSpecs))
-	for _, og := range logic.OpGroupList {
-		fname := fmt.Sprintf("%s.md", og.GroupName)
+	for grp, names := range logic.OpGroups {
+		fname := fmt.Sprintf("%s.md", grp)
 		fname = strings.ReplaceAll(fname, " ", "_")
 		fout, _ := os.Create(fname)
-		opGroupMarkdownTable(&og, fout)
+		opGroupMarkdownTable(names, fout)
 		fout.Close()
-		for _, opname := range og.Ops {
-			opGroups[opname] = append(opGroups[opname], og.GroupName)
+		for _, opname := range names {
+			opGroups[opname] = append(opGroups[opname], grp)
 		}
 	}
 	constants, _ := os.Create("named_integer_constants.md")

cmd/opdoc/tmLanguage.go

@@ -152,26 +152,30 @@ func buildSyntaxHighlight() *tmLanguage {
 			},
 		},
 	}
-	for _, opgroup := range logic.OpGroupList {
-		switch opgroup.GroupName {
+	var allArithmetics []string
+	for grp, names := range logic.OpGroups {
+		switch grp {
 		case "Flow Control":
 			keywords.Patterns = append(keywords.Patterns, pattern{
 				Name:  "keyword.control.teal",
-				Match: fmt.Sprintf("^(%s)\\b", strings.Join(opgroup.Ops, "|")),
+				Match: fmt.Sprintf("^(%s)\\b", strings.Join(names, "|")),
 			})
 		case "Loading Values":
 			loading := []string{"int", "byte", "addr"}
-			loading = append(loading, opgroup.Ops...)
+			loading = append(loading, names...)
 			keywords.Patterns = append(keywords.Patterns, pattern{
 				Name:  "keyword.other.teal",
 				Match: fmt.Sprintf("^(%s)\\b", strings.Join(loading, "|")),
 			})
 		case "State Access":
 			keywords.Patterns = append(keywords.Patterns, pattern{
 				Name:  "keyword.other.unit.teal",
-				Match: fmt.Sprintf("^(%s)\\b", strings.Join(opgroup.Ops, "|")),
+				Match: fmt.Sprintf("^(%s)\\b", strings.Join(names, "|")),
 			})
-		case "Arithmetic":
+		// For these three, accumulate into allArithmetics,
+		// and only add to keyword.Patterns later, when all
+		// have been collected.
+		case "Arithmetic", "Byteslice Arithmetic", "Byteslice Logic":
 			escape := map[rune]bool{
 				'*': true,
 				'+': true,
@@ -186,30 +190,24 @@ func buildSyntaxHighlight() *tmLanguage {
 				'<': true,
 				'>': true,
 			}
-			var allArithmetics []string
-			for _, op := range opgroup.Ops {
-				if len(op) < 3 {
-					// all symbol-based opcodes are under 3 chars, and no trigraphs so far
-					escaped := make([]byte, 0, len(op)*2)
-					for _, ch := range op {
-						if _, ok := escape[ch]; ok {
-							escaped = append(escaped, '\\')
-						}
-						escaped = append(escaped, byte(ch))
+			for _, op := range names {
+				escaped := make([]byte, 0, len(op)*2)
+				for _, ch := range op {
+					if _, ok := escape[ch]; ok {
+						escaped = append(escaped, '\\')
 					}
-					allArithmetics = append(allArithmetics, string(escaped))
-				} else {
-					allArithmetics = append(allArithmetics, op)
+					escaped = append(escaped, byte(ch))
 				}
+				allArithmetics = append(allArithmetics, string(escaped))
 			}
-			keywords.Patterns = append(keywords.Patterns, pattern{
-				Name:  "keyword.operator.teal",
-				Match: fmt.Sprintf("^(%s)\\b", strings.Join(allArithmetics, "|")),
-			})
 		default:
-			panic(fmt.Sprintf("Unknown ops group: %s", opgroup.GroupName))
+			panic(fmt.Sprintf("Unknown ops group: %s", grp))
 		}
 	}
+	keywords.Patterns = append(keywords.Patterns, pattern{
+		Name:  "keyword.operator.teal",
+		Match: fmt.Sprintf("^(%s)\\b", strings.Join(allArithmetics, "|")),
+	})
 	tm.Repository["keywords"] = keywords
 
 	return &tm

data/transactions/logic/Makefile

@@ -1,11 +1,11 @@
-all:	TEAL_opcodes.md README.md fields_string.go
+all:	TEAL_opcodes.md teal.tmLanguage.json README.md fields_string.go
 
 # Location of algorandfoundation/specs repo. (Optional)
 SPECS := ../../../../specs
 # Location of algorand/docs repo. (Optional)
 DOCS :=  ../../../../docs
 
-TEAL_opcodes.md:	fields_string.go ../../../cmd/opdoc/opdoc.go eval.go assembler.go doc.go opcodes.go
+TEAL_opcodes.md teal.tmLanguage.json:	fields_string.go ../../../cmd/opdoc/opdoc.go ../../../cmd/opdoc/tmLanguage.go eval.go assembler.go doc.go opcodes.go
 	go run ../../../cmd/opdoc/opdoc.go ../../../cmd/opdoc/tmLanguage.go
 	@if [ -e $(SPECS)/dev/TEAL_opcodes.md ]; then \
 		sed '/^$$/q' $(SPECS)/dev/TEAL_opcodes.md | cat - TEAL_opcodes.md > opcodes.spec; \

data/transactions/logic/README.md

@@ -27,7 +27,7 @@ A program can either authorize some delegated action on a normal private key sig
 * If the account has signed the program (an ed25519 signature on "Program" concatenated with the program bytes) then if the program returns true the transaction is authorized as if the account had signed it. This allows an account to hand out a signed program so that other users can carry out delegated actions which are approved by the program.
 * If the SHA512_256 hash of the program (prefixed by "Program") is equal to the transaction Sender address then this is a contract account wholly controlled by the program. No other signature is necessary or possible. The only way to execute a transaction against the contract account is for the program to approve it.
 
-The TEAL bytecode plus the length of any Args must add up to less than 1000 bytes (consensus parameter LogicSigMaxSize). Each TEAL op has an associated cost and the program cost must total less than 20000 (consensus parameter LogicSigMaxCost). Most ops have a cost of 1, but a few slow crypto ops are much higher. Prior to v4, program costs was estimated as the static sum of all opcode costs in a program (ignoring conditionals that might skip some code).  Beginning with v4, a program's cost is tracked dynamically, while being evaluated. If the program exceeds its budget, it fails.
+The TEAL bytecode plus the length of any Args must add up to less than 1000 bytes (consensus parameter LogicSigMaxSize). Each TEAL op has an associated cost and the program cost must total less than 20000 (consensus parameter LogicSigMaxCost). Most ops have a cost of 1, but a few slow crypto ops are much higher. Prior to v4, program costs was estimated as the static sum of all opcode costs in a program (ignoring conditionals that might skip some code). Beginning with v4, a program's cost is tracked dynamically, while being evaluated. If the program exceeds its budget, it fails.
 
 ## Execution modes
 
@@ -111,6 +111,11 @@ For two-argument ops, `A` is the previous element on the stack and `B` is the la
 | `>=` | A greater than or equal to B => {0 or 1} |
 | `&&` | A is not zero and B is not zero => {0 or 1} |
 | `\|\|` | A is not zero or B is not zero => {0 or 1} |
+| `shl` | A times 2^B, modulo 2^64 |
+| `shr` | A divided by 2^B |
+| `sqrt` | The largest integer X such that X^2 <= A |
+| `bitlen` | The index of the highest bit in A. If A is a byte-array, it is interpreted as a big-endian unsigned integer |
+| `exp` | A raised to the Bth power. Panic if A == B == 0 and on overflow |
 | `==` | A is equal to B => {0 or 1} |
 | `!=` | A is not equal to B => {0 or 1} |
 | `!` | X == 0 yields 1; else 0 |
@@ -124,7 +129,8 @@ For two-argument ops, `A` is the previous element on the stack and `B` is the la
 | `~` | bitwise invert value X |
 | `mulw` | A times B out to 128-bit long result as low (top) and high uint64 values on the stack |
 | `addw` | A plus B out to 128-bit long result as sum (top) and carry-bit uint64 values on the stack |
-| `divw` | Pop four uint64 values.  The deepest two are interpreted as a uint128 dividend (deepest value is high word), the top two are interpreted as a uint128 divisor.  Four uint64 values are pushed to the stack. The deepest two are the quotient (deeper value is the high uint64). The top two are the remainder, low bits on top. |
+| `divmodw` | Pop four uint64 values.  The deepest two are interpreted as a uint128 dividend (deepest value is high word), the top two are interpreted as a uint128 divisor.  Four uint64 values are pushed to the stack. The deepest two are the quotient (deeper value is the high uint64). The top two are the remainder, low bits on top. |
+| `expw` | A raised to the Bth power as a 128-bit long result as low (top) and high uint64 values on the stack. Panic if A == B == 0 or if the results exceeds 2^128-1 |
 | `getbit` | pop a target A (integer or byte-array), and index B. Push the Bth bit of A. |
 | `setbit` | pop a target A, index B, and bit C. Set the Bth bit of A to C, and push the result |
 | `getbyte` | pop a byte-array A and integer B. Extract the Bth byte of A and push it as an integer |
@@ -133,6 +139,42 @@ For two-argument ops, `A` is the previous element on the stack and `B` is the la
 | `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 |
 
+These opcodes take and return byte-array values that are interpreted
+as big-endian unsigned integers.  Returned values are the shortest
+byte-array that can represent the returned value.  For example, the
+zero value is the empty byte-array.
+
+Input lengths are limited to maximum length 64, which represents a 512
+bit unsigned integer.
+
+| Op | Description |
+| --- | --- |
+| `b+` | A plus B, where A and B are byte-arrays interpreted as big-endian unsigned integers |
+| `b-` | A minus B, where A and B are byte-arrays interpreted as big-endian unsigned integers. Panic on underflow. |
+| `b/` | A divided by B, where A and B are byte-arrays interpreted as big-endian unsigned integers. Panic if B is zero. |
+| `b*` | A times B, where A and B are byte-arrays interpreted as big-endian unsigned integers. |
+| `b<` | A is less than B, where A and B are byte-arrays interpreted as big-endian unsigned integers => { 0 or 1} |
+| `b>` | A is greater than B, where A and B are byte-arrays interpreted as big-endian unsigned integers => { 0 or 1} |
+| `b<=` | A is less than or equal to B, where A and B are byte-arrays interpreted as big-endian unsigned integers => { 0 or 1} |
+| `b>=` | A is greater than or equal to B, where A and B are byte-arrays interpreted as big-endian unsigned integers => { 0 or 1} |
+| `b==` | A is equals to B, where A and B are byte-arrays interpreted as big-endian unsigned integers => { 0 or 1} |
+| `b!=` | A is not equal to B, where A and B are byte-arrays interpreted as big-endian unsigned integers => { 0 or 1} |
+| `b%` | A modulo B, where A and B are byte-arrays interpreted as big-endian unsigned integers. Panic if B is zero. |
+
+These opcodes operate on the bits of byte-array values.  The shorter
+array is interpeted as though left padded with zeros until it is the
+same length as the other input.  The returned values are the same
+length as the longest input.  Therefore, unlike array arithmetic,
+these results may contain leading zero bytes.
+
+| Op | Description |
+| --- | --- |
+| `b\|` | A bitwise-or B, where A and B are byte-arrays, zero-left extended to the greater of their lengths |
+| `b&` | A bitwise-and B, where A and B are byte-arrays, zero-left extended to the greater of their lengths |
+| `b^` | A bitwise-xor B, where A and B are byte-arrays, zero-left extended to the greater of their lengths |
+| `b~` | A with all bits inverted |
+
+
 ### Loading Values
 
 Opcodes for getting data onto the stack.
@@ -155,6 +197,7 @@ Some of these have immediate data in the byte or bytes after the opcode.
 | `bytec_2` | push constant 2 from bytecblock to stack |
 | `bytec_3` | push constant 3 from bytecblock to stack |
 | `pushbytes bytes` | push the following program bytes to the stack |
+| `bzero` | push a byte-array of length A, containing all zero bytes |
 | `arg n` | push Nth LogicSig argument to stack |
 | `arg_0` | push LogicSig argument 0 to stack |
 | `arg_1` | push LogicSig argument 1 to stack |

data/transactions/logic/README_in.md

@@ -74,6 +74,25 @@ For two-argument ops, `A` is the previous element on the stack and `B` is the la
 
 @@ Arithmetic.md @@
 
+These opcodes take and return byte-array values that are interpreted
+as big-endian unsigned integers.  Returned values are the shortest
+byte-array that can represent the returned value.  For example, the
+zero value is the empty byte-array.
+
+Input lengths are limited to maximum length 64, which represents a 512
+bit unsigned integer.
+
+@@ Byteslice_Arithmetic.md @@
+
+These opcodes operate on the bits of byte-array values.  The shorter
+array is interpeted as though left padded with zeros until it is the
+same length as the other input.  The returned values are the same
+length as the longest input.  Therefore, unlike array arithmetic,
+these results may contain leading zero bytes.
+
+@@ Byteslice_Logic.md @@
+
+
 ### Loading Values
 
 Opcodes for getting data onto the stack.