evmole 0.8.4

Extracts function selectors and arguments from EVM bytecode
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162

// Package evmole provides EVM bytecode analysis functionality.
//
// EVMole extracts function selectors, arguments, state mutability,
// storage layout, and control flow graphs from Ethereum Virtual Machine bytecode.
//
// Basic usage:
//
//	// Single contract analysis
//	info, err := evmole.ContractInfo(ctx, bytecode, evmole.Options{Selectors: true})
//
//	// Multiple contracts (efficient - compile WASM once)
//	analyzer, err := evmole.NewAnalyzer(ctx)
//	if err != nil {
//		return err
//	}
//	defer analyzer.Close(ctx)
//
//	for _, bytecode := range contracts {
//		info, err := analyzer.ContractInfo(ctx, bytecode, opts)
//		// ...
//	}
package evmole

import (
	"bytes"
	"compress/gzip"
	"context"
	_ "embed"
	"encoding/json"
	"io"
	"sync"

	"github.com/cdump/evmole/go/internal"
)

//go:embed wasm/evmole.wasm.gz
var wasmBinaryGz []byte

var (
	wasmBinary     []byte
	wasmBinaryOnce sync.Once
	wasmBinaryErr  error
)

func getWasmBinary() ([]byte, error) {
	wasmBinaryOnce.Do(func() {
		r, err := gzip.NewReader(bytes.NewReader(wasmBinaryGz))
		if err != nil {
			wasmBinaryErr = err
			return
		}
		defer r.Close()
		wasmBinary, wasmBinaryErr = io.ReadAll(r)
	})
	return wasmBinary, wasmBinaryErr
}

// Options configures which analyses to perform.
type Options struct {
	// Selectors enables extraction of function selectors.
	Selectors bool
	// Arguments enables extraction of function parameter types.
	Arguments bool
	// StateMutability enables detection of function state mutability.
	StateMutability bool
	// Storage enables extraction of storage layout.
	Storage bool
	// Disassemble enables bytecode disassembly.
	Disassemble bool
	// BasicBlocks enables extraction of basic blocks.
	BasicBlocks bool
	// ControlFlowGraph enables generation of control flow graph.
	ControlFlowGraph bool
}

// Options bitmask constants (must match Rust side)
const (
	optSelectors        uint32 = 1
	optArguments        uint32 = 2
	optStateMutability  uint32 = 4
	optStorage          uint32 = 8
	optDisassemble      uint32 = 16
	optBasicBlocks      uint32 = 32
	optControlFlowGraph uint32 = 64
)

func (o Options) toBitmask() uint32 {
	var mask uint32
	if o.Selectors {
		mask |= optSelectors
	}
	if o.Arguments {
		mask |= optArguments
	}
	if o.StateMutability {
		mask |= optStateMutability
	}
	if o.Storage {
		mask |= optStorage
	}
	if o.Disassemble {
		mask |= optDisassemble
	}
	if o.BasicBlocks {
		mask |= optBasicBlocks
	}
	if o.ControlFlowGraph {
		mask |= optControlFlowGraph
	}
	return mask
}

// Analyzer holds the compiled WASM module for reuse.
// Create once with NewAnalyzer(), use for many contracts.
type Analyzer struct {
	runtime *internal.Runtime
}

// NewAnalyzer creates a new analyzer with AOT-compiled WASM.
// This takes ~50ms for compilation, so create once and reuse.
func NewAnalyzer(ctx context.Context) (*Analyzer, error) {
	wasm, err := getWasmBinary()
	if err != nil {
		return nil, err
	}
	rt, err := internal.NewRuntime(ctx, wasm)
	if err != nil {
		return nil, err
	}
	return &Analyzer{runtime: rt}, nil
}

// Close releases all resources. Call when done with the analyzer.
func (a *Analyzer) Close(ctx context.Context) error {
	return a.runtime.Close(ctx)
}

// ContractInfo analyzes EVM bytecode with the given options.
// Safe to call concurrently from multiple goroutines.
func (a *Analyzer) ContractInfo(ctx context.Context, code []byte, opts Options) (*Contract, error) {
	jsonResult, err := a.runtime.ContractInfo(ctx, code, opts.toBitmask())
	if err != nil {
		return nil, err
	}

	var result Contract
	if err := json.Unmarshal(jsonResult, &result); err != nil {
		return nil, err
	}
	return &result, nil
}

// ContractInfo is a convenience function that creates a temporary analyzer.
// For analyzing multiple contracts, use NewAnalyzer() instead.
func ContractInfo(ctx context.Context, code []byte, opts Options) (*Contract, error) {
	a, err := NewAnalyzer(ctx)
	if err != nil {
		return nil, err
	}
	defer a.Close(ctx)
	return a.ContractInfo(ctx, code, opts)
}