Added example project

.github/dependabot.yml

@@ -3,4 +3,8 @@ updates:
   - package-ecosystem: "gomod"
     directory: "/"
     schedule:
-      interval: "daily"
+      interval: "weekly"
+  - package-ecosystem: "gomod"
+    directory: "/example"
+    schedule:
+      interval: "weekly"

README.md

@@ -5,7 +5,7 @@
 
 `go-huffc` provides an easy way to compile [Huff](https://github.com/huff-language/huff-rs) contracts from Go.
 
-> **Note**
+> [!NOTE]
 > `go-huffc` requires the `huffc` binary to be installed. See [huff.sh](https://huff.sh) for installation instructions.
 
 ```
@@ -16,12 +16,20 @@ go get github.com/project-blanc/go-huffc
 
 ```go
 // Compile a contract with default compiler settings
-c := huffc.New(nil)
-contract, err := c.Compile("contract.huff")
+c := huffc.New()
+contract, err := c.Compile("contract.huff", nil)
 
 // Compile a contract with custom compiler settings
-c := huffc.New(&huff.Options{
+c := huffc.New()
+contract, err := c.Compile("contract.huff", &huffc.Options{
     EVMVersion: huffc.EVMVersionIstanbul,
 })
-contract, err := c.Compile("contract.huff")
 ```
+
+## Example Project
+
+See the [example project](https://github.com/project-blanc/go-huffc/tree/main/example) for a basic reference on how to test and fuzz a Huff contract in Go.
+
+
+> [!WARNING]
+> This package is pre-1.0. There might be breaking changes between minor versions.

example/add.huff

@@ -0,0 +1,20 @@
+// Add two numbers, or revert on overflow
+#define function add(uint256, uint256) nonpayable returns (uint256)
+
+#define macro MAIN() = {
+   0x04 calldataload  // a        //     // load numbers from calldata
+   0x24 calldataload  // b a      //     //
+                                  //     //
+   dup2               // a b a    //     //
+   add                // a+b=c a  //     // add numbers
+   swap1              // a c      //     //
+   dup2               // c a c    //     //
+   lt                 // c<a c    //     //
+   _overflow jumpi    // c        // >─╮ // jump to _overflow if c<a
+                                  //   │ //
+   0x0 mstore         //          //   │ // store c in memory[0:32]
+   0x20 0x0 return    //          //   │ // return memory[0:32]
+                                  //   │ //
+_overflow:            //          // <─╯ //
+   0x0 0x0 revert     // c        //     // revert
+}

example/add_test.go

@@ -0,0 +1,133 @@
+package examples_test
+
+import (
+	"errors"
+	"math/big"
+	"testing"
+
+	"github.com/lmittmann/w3"
+	"github.com/lmittmann/w3/w3types"
+	"github.com/lmittmann/w3/w3vm"
+	"github.com/project-blanc/go-huffc"
+)
+
+var (
+	compiler = huffc.New()
+
+	// address of the contract
+	contractAddr = w3vm.RandA()
+
+	// ABI binding for the add function
+	funcAdd = w3.MustNewFunc("add(uint256,uint256)", "uint256")
+
+	maxBig256 = new(big.Int).Sub(
+		new(big.Int).Exp(w3.Big2, big.NewInt(256), nil),
+		w3.Big1,
+	)
+)
+
+func TestAdd(t *testing.T) {
+	tests := []struct {
+		A, B    *big.Int
+		WantC   *big.Int // C = A + B
+		WantErr error
+	}{
+		{A: big.NewInt(0), B: big.NewInt(0), WantC: big.NewInt(0)},
+		{A: big.NewInt(0), B: big.NewInt(1), WantC: big.NewInt(1)},
+		{A: big.NewInt(1), B: big.NewInt(0), WantC: big.NewInt(1)},
+		{A: big.NewInt(1), B: big.NewInt(2), WantC: big.NewInt(3)},
+		{A: maxBig256, B: big.NewInt(0), WantC: maxBig256},
+		{A: big.NewInt(0), B: maxBig256, WantC: maxBig256},
+		{A: maxBig256, B: maxBig256, WantErr: w3vm.ErrRevert},
+	}
+
+	contract, err := compiler.Compile("add.huff", &huffc.Options{EVMVersion: huffc.EVMVersionShanghai})
+	if err != nil {
+		t.Fatalf("Failed to compile contract: %v", err)
+	}
+
+	for _, test := range tests {
+		// construct a VM for testing with the runtime code of the contract
+		// deployed to `contractAddr`
+		vm, _ := w3vm.New(
+			w3vm.WithState(w3types.State{
+				contractAddr: {Code: contract.Code},
+			}),
+		)
+
+		// apply the add function
+		receipt, err := vm.Apply(&w3types.Message{
+			From: w3vm.RandA(),
+			To:   &contractAddr,
+			Args: []any{test.A, test.B},
+			Func: funcAdd,
+		})
+
+		// check for error
+		if !errors.Is(err, test.WantErr) {
+			t.Fatalf("Err: want %q, got %q", test.WantErr, err)
+		} else if err != nil {
+			continue
+		}
+
+		// check the return value
+		var gotC *big.Int
+		if err := receipt.DecodeReturns(&gotC); err != nil {
+			t.Fatalf("Failed to decode return value: %v", err)
+		}
+		if test.WantC.Cmp(gotC) != 0 {
+			t.Fatalf("C: want %v, got %v", test.WantC, gotC)
+		}
+	}
+}
+
+func FuzzAdd(f *testing.F) {
+	contract, err := compiler.Compile("add.huff", &huffc.Options{EVMVersion: huffc.EVMVersionShanghai})
+	if err != nil {
+		f.Fatalf("Failed to compile contract: %v", err)
+	}
+
+	preState := w3vm.WithState(w3types.State{
+		contractAddr: {Code: contract.Code},
+	})
+
+	f.Fuzz(func(t *testing.T, aBytes, bBytes []byte) {
+		if len(aBytes) > 32 || len(bBytes) > 32 {
+			t.Skip()
+		}
+		var (
+			a     = new(big.Int).SetBytes(aBytes[:])
+			b     = new(big.Int).SetBytes(bBytes[:])
+			wantC = new(big.Int).Add(a, b)
+		)
+
+		vm, _ := w3vm.New(preState)
+
+		receipt, err := vm.Apply(&w3types.Message{
+			From: w3vm.RandA(),
+			To:   &contractAddr,
+			Args: []any{a, b},
+			Func: funcAdd,
+		})
+
+		if wantC.Cmp(maxBig256) <= 0 {
+			// gotC does NOT overflow, we expect correct addition
+			if err != nil {
+				t.Fatalf("Err: want nil, got %q", err)
+			}
+
+			var gotC *big.Int
+			if err := receipt.DecodeReturns(&gotC); err != nil {
+				t.Fatalf("Failed to decode return value: %v", err)
+			}
+			if wantC.Cmp(gotC) != 0 {
+				t.Fatalf("C: want %v+%v=%v, got %v", a, b, wantC, gotC)
+			}
+		} else {
+			// gotC overflows, we expect a revert
+			if wantErr := w3vm.ErrRevert; !errors.Is(err, wantErr) {
+				t.Fatalf("Err: want %q, got %q", wantErr, err)
+			}
+		}
+	})
+}

example/go.mod

@@ -0,0 +1,72 @@
+module examples
+
+go 1.21
+
+require (
+	github.com/lmittmann/w3 v0.14.4
+	github.com/project-blanc/go-huffc v0.0.0
+)
+
+replace github.com/project-blanc/go-huffc => ../
+
+require (
+	github.com/DataDog/zstd v1.5.2 // indirect
+	github.com/Microsoft/go-winio v0.6.1 // indirect
+	github.com/StackExchange/wmi v1.2.1 // indirect
+	github.com/VictoriaMetrics/fastcache v1.12.1 // indirect
+	github.com/beorn7/perks v1.0.1 // indirect
+	github.com/bits-and-blooms/bitset v1.7.0 // indirect
+	github.com/btcsuite/btcd/btcec/v2 v2.2.0 // indirect
+	github.com/cespare/xxhash/v2 v2.2.0 // indirect
+	github.com/cockroachdb/errors v1.9.1 // indirect
+	github.com/cockroachdb/logtags v0.0.0-20230118201751-21c54148d20b // indirect
+	github.com/cockroachdb/pebble v0.0.0-20230928194634-aa077af62593 // indirect
+	github.com/cockroachdb/redact v1.1.3 // indirect
+	github.com/cockroachdb/tokenbucket v0.0.0-20230807174530-cc333fc44b06 // indirect
+	github.com/consensys/bavard v0.1.13 // indirect
+	github.com/consensys/gnark-crypto v0.12.1 // indirect
+	github.com/crate-crypto/go-kzg-4844 v0.7.0 // indirect
+	github.com/deckarep/golang-set/v2 v2.1.0 // indirect
+	github.com/decred/dcrd/dcrec/secp256k1/v4 v4.0.1 // indirect
+	github.com/ethereum/c-kzg-4844 v0.4.0 // indirect
+	github.com/ethereum/go-ethereum v1.13.5 // indirect
+	github.com/getsentry/sentry-go v0.18.0 // indirect
+	github.com/go-ole/go-ole v1.2.6 // indirect
+	github.com/go-stack/stack v1.8.1 // indirect
+	github.com/gofrs/flock v0.8.1 // indirect
+	github.com/gogo/protobuf v1.3.2 // indirect
+	github.com/golang/protobuf v1.5.3 // indirect
+	github.com/golang/snappy v0.0.5-0.20220116011046-fa5810519dcb // indirect
+	github.com/gorilla/websocket v1.5.0 // indirect
+	github.com/holiman/bloomfilter/v2 v2.0.3 // indirect
+	github.com/holiman/uint256 v1.2.3 // indirect
+	github.com/klauspost/compress v1.15.15 // indirect
+	github.com/kr/pretty v0.3.1 // indirect
+	github.com/kr/text v0.2.0 // indirect
+	github.com/mattn/go-runewidth v0.0.14 // indirect
+	github.com/matttproud/golang_protobuf_extensions v1.0.4 // indirect
+	github.com/mmcloughlin/addchain v0.4.0 // indirect
+	github.com/olekukonko/tablewriter v0.0.5 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
+	github.com/prometheus/client_golang v1.14.0 // indirect
+	github.com/prometheus/client_model v0.3.0 // indirect
+	github.com/prometheus/common v0.39.0 // indirect
+	github.com/prometheus/procfs v0.9.0 // indirect
+	github.com/rivo/uniseg v0.4.2 // indirect
+	github.com/rogpeppe/go-internal v1.9.0 // indirect
+	github.com/shirou/gopsutil v3.21.4-0.20210419000835-c7a38de76ee5+incompatible // indirect
+	github.com/supranational/blst v0.3.11 // indirect
+	github.com/syndtr/goleveldb v1.0.1-0.20210819022825-2ae1ddf74ef7 // indirect
+	github.com/tklauser/go-sysconf v0.3.12 // indirect
+	github.com/tklauser/numcpus v0.6.1 // indirect
+	golang.org/x/crypto v0.14.0 // indirect
+	golang.org/x/exp v0.0.0-20230905200255-921286631fa9 // indirect
+	golang.org/x/mod v0.12.0 // indirect
+	golang.org/x/sync v0.5.0 // indirect
+	golang.org/x/sys v0.13.0 // indirect
+	golang.org/x/text v0.13.0 // indirect
+	golang.org/x/time v0.5.0 // indirect
+	golang.org/x/tools v0.13.0 // indirect
+	google.golang.org/protobuf v1.28.1 // indirect
+	rsc.io/tmplfunc v0.0.3 // indirect
+)