all: implement EIP-8024: backward compatible SWAPN, DUPN, EXCHANGE (#24)

This implements [EIP-8024](https://eips.ethereum.org/EIPS/eip-8024),
adding three new stack manipulation instructions. The EIP is currently
scheduled for the "Amsterdam" execution-layer fork of Ethereum.

These instructions are followed by an immediate argument, which is a new
concept in geas. I have chosen the `[x]` syntax for immediates, i.e.

```
    swapn[17]
    exchange[1, 22]
```

I'm not sure if there is a need for being able to write the immediate
argument in its encoded form. The encoding function is not
straightforward, but it is of course reversible (for valid inputs), and
the disassembler currently also shows the decoded form.

Author: fjl

asm/compiler.go

@@ -396,16 +396,20 @@ loop:
 				c.errorAt(inst.ast, fmt.Errorf("%w %s", ecUnknownOpcode, inst.op))
 				continue loop
 			}
+			output = append(output, op.Code)
+			if len(inst.data) > 0 && !op.HasImmediate {
+				panic(fmt.Sprintf("BUG: instruction at pc=%d has unexpected data", inst.pc))
+			}
+			output = append(output, inst.data...)
 			// Unreachable code check.
 			if !c.errors.hasError() {
 				unreachable.check(c, inst.ast, op)
 			}
-			output = append(output, op.Code)
-			fallthrough
 
 		default:
+			// Empty op.
 			if len(inst.data) > 0 {
-				panic(fmt.Sprintf("BUG: instruction at pc=%d has unexpected data", inst.pc))
+				panic(fmt.Sprintf("BUG: empty instruction at pc=%d has unexpected data", inst.pc))
 			}
 		}
 	}

asm/compiler_expand.go

@@ -81,15 +81,31 @@ func (op opcodeStatement) expand(c *Compiler, doc *ast.Document, prog *compilerP
 		}
 
 	default:
-		if _, err := prog.resolveOp(opcode); err != nil {
+		evmOp, err := prog.resolveOp(opcode)
+		if err != nil {
 			return err
 		}
+		// Arg is not expected.
 		if op.Arg != nil {
 			if opcode == "PUSH0" {
 				return ecPushzeroWithArgument
 			}
 			return ecUnexpectedArgument
 		}
+		// Handle immediates.
+		if evmOp.HasImmediate {
+			if len(op.Immediates) == 0 {
+				return ecMissingImmediate
+			}
+			imm, err := evmOp.EncodeImmediateArgs(op.Immediates)
+			if err != nil {
+				return fmt.Errorf("%s %v", evmOp.Name, err)
+			}
+			inst.data = []byte{imm}
+			inst.dataSize = 1
+		} else if len(op.Immediates) > 0 {
+			return ecUnexpectedImmediate
+		}
 	}
 
 	prog.addInstruction(inst)

asm/error.go

@@ -61,6 +61,8 @@ const (
 	ecPragmaTargetInIncludeFile
 	ecPragmaTargetConflict
 	ecPragmaTargetUnknown
+	ecMissingImmediate
+	ecUnexpectedImmediate
 )
 
 func (e compilerError) Error() string {
@@ -115,6 +117,10 @@ func (e compilerError) Error() string {
 		return "duplicate '#pragma target ...' directive"
 	case ecPragmaTargetUnknown:
 		return "unknown #pragma target"
+	case ecMissingImmediate:
+		return "missing immediate for opcode"
+	case ecUnexpectedImmediate:
+		return "unexpected immediate"
 	default:
 		return fmt.Sprintf("invalid error %d", e)
 	}

asm/testdata/compiler-tests.yaml

@@ -847,6 +847,56 @@ instr-macro-variable-shadow:
   output:
     bytecode: "6001 6002"
 
+immediates:
+  input:
+    code: |
+      dupn[17]
+      dupn[18]
+      add
+      exchange[2, 3]
+      exchange[1, 19]
+      sub
+      swapn[19]
+      swapn[108]
+      #pragma target "amsterdam"
+  output:
+    bytecode: "e600 e601 01 e812 e8d0 03 e702 e780"
+
+immediate-swapn-range-errors:
+  input:
+    code: |
+      swapn[2]
+      swapn[245]
+      #pragma target "amsterdam"
+  output:
+    errors:
+      - ':1: SWAPN stack depth 2 out of range (17-235)'
+      - ':2: SWAPN stack depth 245 out of range (17-235)'
+
+immediate-dupn-range-errors:
+  input:
+    code: |
+      dupn[2]
+      dupn[245]
+      #pragma target "amsterdam"
+  output:
+    errors:
+      - ':1: DUPN stack depth 2 out of range (17-235)'
+      - ':2: DUPN stack depth 245 out of range (17-235)'
+
+immediate-exchange-range-errors:
+  input:
+    code: |
+      exchange[14, 15]
+      exchange[1, 30]
+      exchange[13, 29]
+      #pragma target "amsterdam"
+  output:
+    errors:
+      - ':1: EXCHANGE first position 14 out of range (1-13)'
+      - ':2: EXCHANGE second position 30 out of range (1-29)'
+      - ':3: EXCHANGE invalid positions 13, 29 (n+m > 30)'
+
 opcode-unknown-in-fork:
   input:
     code: |

disasm/disassembler.go

@@ -93,6 +93,9 @@ func (d *Disassembler) Disassemble(bytecode []byte, outW io.Writer) error {
 			if op.Push {
 				size := d.printPush(out, op, bytecode[pc:])
 				pc += size
+			} else if op.HasImmediate {
+				size := d.printImmediate(out, op, bytecode[pc:])
+				pc += size
 			} else {
 				d.printOp(out, op)
 			}
@@ -143,6 +146,30 @@ func (d *Disassembler) printPush(out io.Writer, op *evm.Op, code []byte) (dataSi
 	return len(data)
 }
 
+func (d *Disassembler) printImmediate(out io.Writer, op *evm.Op, code []byte) (dataSize int) {
+	if len(code) < 2 {
+		// Truncated instruction
+		fmt.Fprintf(out, "#bytes %#x", code)
+		return len(code) - 1
+	}
+	imm := code[1]
+	if !op.ValidateImmediate(imm) {
+		fmt.Fprintf(out, "#bytes %#x   ; invalid %s", code[0], op.Name)
+		return 0
+	}
+	d.printOp(out, op)
+	args := op.DecodeImmediate(imm)
+	fmt.Fprint(out, "[")
+	for i, arg := range args {
+		if i > 0 {
+			fmt.Fprint(out, ", ")
+		}
+		fmt.Fprintf(out, "%d", arg)
+	}
+	fmt.Fprint(out, "]")
+	return 1
+}
+
 func (d *Disassembler) newline(out io.Writer, prevOp *evm.Op, nextOp *evm.Op) {
 	if prevOp == nil {
 		return

disasm/disassembler_test.go

@@ -25,6 +25,77 @@ import (
 	"github.com/fjl/geas/asm"
 )
 
+func TestImmediateOpcodes(t *testing.T) {
+	// Test EIP-8024 opcodes: DUPN (0xe6), SWAPN (0xe7), EXCHANGE (0xe8)
+	bytecode, _ := hex.DecodeString("e600e780e812e8d0")
+	expectedOutput := strings.TrimSpace(`
+dupn[17]
+swapn[108]
+exchange[2, 3]
+exchange[1, 19]
+`)
+
+	var buf strings.Builder
+	d := New()
+	d.SetShowBlocks(false)
+	d.SetTarget("amsterdam")
+	d.Disassemble(bytecode, &buf)
+	output := strings.TrimSpace(buf.String())
+	if output != expectedOutput {
+		t.Fatalf("wrong output:\ngot:\n%s\n\nwant:\n%s", output, expectedOutput)
+	}
+
+	// try round trip
+	a := asm.New(nil)
+	a.SetDefaultFork("amsterdam")
+	rtcode := a.CompileString(output)
+	if !bytes.Equal(rtcode, bytecode) {
+		t.Error("disassembly did not round-trip")
+	}
+}
+
+func TestImmediateOpcodeTruncated(t *testing.T) {
+	bytecode, _ := hex.DecodeString("e6")
+	expectedOutput := "#bytes 0xe6"
+
+	var buf strings.Builder
+	d := New()
+	d.SetShowBlocks(false)
+	d.SetTarget("amsterdam")
+	d.Disassemble(bytecode, &buf)
+	output := strings.TrimSpace(buf.String())
+	if output != expectedOutput {
+		t.Fatalf("wrong output:\ngot: %s\nwant: %s", output, expectedOutput)
+	}
+}
+
+// This checks that the disassembler can handle immediate opcodes which are not working.
+func TestImmediateOpcodeInvalid(t *testing.T) {
+	bytecode, _ := hex.DecodeString("e75be6605be7610000e65fe850")
+	expectedOutput := strings.TrimSpace(`
+#bytes 0xe7   ; invalid SWAPN
+jumpdest
+#bytes 0xe6   ; invalid DUPN
+push1 0x5b
+#bytes 0xe7   ; invalid SWAPN
+push2 0x0000
+#bytes 0xe6   ; invalid DUPN
+push0
+#bytes 0xe8   ; invalid EXCHANGE
+pop
+`)
+
+	var buf strings.Builder
+	d := New()
+	d.SetShowBlocks(false)
+	d.SetTarget("amsterdam")
+	d.Disassemble(bytecode, &buf)
+	output := strings.TrimSpace(buf.String())
+	if output != expectedOutput {
+		t.Fatalf("wrong output:\ngot: %s\nwant: %s", output, expectedOutput)
+	}
+}
+
 func TestIncompletePush(t *testing.T) {
 	bytecode, _ := hex.DecodeString("6080604052348015600e575f80fd5b50603e80601a5f395ff3fe60806040525f80fdfea2646970667358221220ba4339602dd535d09d71fae3164f7aa7f6e098ec879fc9e8f36bd912d4877c5264736f6c63430008190033")
 	expectedOutput := strings.TrimSpace(`

internal/ast/ast.go

@@ -178,9 +178,10 @@ func (st *stbase) StartsBlock() bool {
 type (
 	Opcode struct {
 		stbase
-		Op       string
-		Arg      Expr // Immediate argument for PUSH* / JUMP*.
-		PushSize byte // For PUSH<n>, this is n+1.
+		Op         string
+		Arg        Expr  // Immediate argument for PUSH* / JUMP*.
+		Immediates []int // Immediate arguments in brackets, e.g. dupn[x], exchange[x, y].
+		PushSize   byte  // For PUSH<n>, this is n+1.
 	}
 
 	LabelDef struct {

internal/ast/lexer.go

@@ -70,6 +70,8 @@ const (
 	instMacroIdent                      // macro identifier
 	openBrace                           // open brace
 	closeBrace                          // closing brace
+	openBracket                         // open bracket
+	closeBracket                        // close bracket
 	equals                              // equals sign
 	arith                               // arithmetic operation
 	comment                             // comment
@@ -213,6 +215,14 @@ func lexNext(l *lexer) stateFn {
 			l.emit(closeBrace)
 			return lexNext
 
+		case r == '[':
+			l.emit(openBracket)
+			return lexNext
+
+		case r == ']':
+			l.emit(closeBracket)
+			return lexNext
+
 		case r == ',':
 			l.emit(comma)
 			return lexNext

internal/ast/parse.go

@@ -469,8 +469,13 @@ func parseOpcode(p *Parser, tok token) *Opcode {
 		st.PushSize = byte(size + 1)
 	}
 
-	// Parse optional argument.
+	// Parse optional immediates in brackets.
 	argToken := p.next()
+	if argToken.typ == openBracket {
+		st.Immediates = parseImmediates(p)
+		argToken = p.next()
+	}
+	// Parse optional argument.
 	switch argToken.typ {
 	case lineEnd, eof, comment:
 		p.unread(argToken)
@@ -480,6 +485,38 @@ func parseOpcode(p *Parser, tok token) *Opcode {
 	return st
 }
 
+func parseImmediates(p *Parser) []int {
+	const limit = 2 // how many immediates allowed
+
+	var args []int
+	for {
+		switch tok := p.next(); tok.typ {
+		case numberLiteral:
+			n, _ := lzint.ParseNumberLiteral(tok.text)
+			if n.IntegerBitLen() > 8 {
+				p.throwError(tok, "immediate value > 8 bits")
+			}
+			args = append(args, int(n.Int().Int64()))
+		case lineEnd, eof, comment:
+			p.throwError(tok, "unexpected end of immediates")
+		default:
+			p.throwError(tok, "expected number in immediates list")
+		}
+		switch tok := p.next(); tok.typ {
+		case closeBracket:
+			return args
+		case comma:
+			if len(args) >= limit {
+				p.throwError(tok, "too many immediates")
+			}
+		case lineEnd, eof, comment:
+			p.throwError(tok, "unexpected end of immediates")
+		default:
+			p.throwError(tok, "expected ',' or ']'")
+		}
+	}
+}
+
 var sizedPushRE = regexp.MustCompile("(?i)^PUSH([0-9]*)$")
 
 func parsePushSize(name string) (int, bool) {