Add hydrate lib (#353)

* Move abicalldata to own package

* Add hydrate lib

* Fix address offset

* bytes32 size validation

Author: ScreamingHawk

lib/abicalldata/README.md

@@ -0,0 +1,36 @@
+# ABI calldata
+
+Helpers for **Ethereum ABI-encoded calldata**: head layout, static argument words, and dynamic `bytes`/`string` tails. Also defines **`ByteRange`** and **`Selector`** for locating byte spans inside a v3 **`CallsPayload`**.
+
+## Calldata layout
+
+Offsets are **from the start of calldata** (bytes `0..3` are the 4-byte function selector).
+
+- **`AbiHeadWords(t)`** — number of 32-byte words an ABI type occupies in the **head** (dynamic types count as one offset word).
+- **`CalldataStaticWord(method, argIndex)`** — `start` and `length` (multiple of 32) for a **static** argument’s encoded words in `calldata`.
+- **`CalldataBytesContent(calldata, method, argIndex)`** — `start`/`length` of the **raw** `bytes`/`string` payload (no length word, no tail padding).
+- **`CalldataBytesEncoded(calldata, method, argIndex)`** — `start`/`length` of the full **tail slice**: 32-byte length word + content + padding to 32-byte boundary.
+
+```go
+method := contractABI.Methods["transfer"]
+start, length, err := abicalldata.CalldataStaticWord(method, 1) // e.g. uint256 amount
+if err != nil {
+    return err
+}
+argBytes := calldata[start : start+length]
+```
+
+For nested calldata (e.g. a `bytes` argument whose body is another contract call), slice to the inner calldata and call these helpers again with the inner method’s `abi.Method`.
+
+## Calls payload selectors
+
+- **`ByteRange`** — `{CallIndex, Offset, Size}` into `payload.Calls[CallIndex].Data` (that field is the call’s calldata, typically including the inner 4-byte selector).
+- **`Selector`** — `Resolve(*v3.CallsPayload) ([]ByteRange, error)` plus `String()` for errors.
+- **`NewRangeSelector(callIndex, offset, size)`** — fixed range, validated on resolve.
+
+```go
+sel := abicalldata.NewRangeSelector(0, 0x24, 32)
+ranges, err := sel.Resolve(payload)
+```
+
+**`Selector`** is implemented by types in other packages that walk `CallsPayload` and nested calldata; they typically use the functions above to turn `abi.Method` + argument index into `ByteRange` updates. **`NewRangeSelector`** is the built-in implementation for a fixed call index, offset, and length.

lib/sapient/malleable/locators_abi.go lib/abicalldata/calldata.golib/sapient/malleable/locators_abi.go renamed to lib/abicalldata/calldata.go

@@ -1,4 +1,4 @@
-package malleable
+package abicalldata
 
 import (
 	"fmt"
@@ -8,25 +8,25 @@ import (
 	"github.com/0xsequence/ethkit/go-ethereum/accounts/abi"
 )
 
-// abiHeadWords returns the number of 32-byte words this type occupies in the
+// AbiHeadWords returns the number of 32-byte words this type occupies in the
 // ABI calldata head. Dynamic types (bytes, string, slice, and tuples/arrays
 // that contain them) occupy 1 word (offset); static types use their encoded size.
-func abiHeadWords(t abi.Type) int {
+func AbiHeadWords(t abi.Type) int {
 	switch t.T {
 	case abi.BytesTy, abi.StringTy, abi.SliceTy:
 		return 1
 	case abi.ArrayTy:
 		if t.Size == 0 || isDynamicType(t) {
 			return 1
 		}
-		return t.Size * abiHeadWords(*t.Elem)
+		return t.Size * AbiHeadWords(*t.Elem)
 	case abi.TupleTy:
 		if isDynamicType(t) {
 			return 1
 		}
 		n := 0
 		for _, e := range t.TupleElems {
-			n += abiHeadWords(*e)
+			n += AbiHeadWords(*e)
 		}
 		return n
 	default:
@@ -43,7 +43,7 @@ func calldataArgHeadOffset(method abi.Method, argIndex int) (int, error) {
 	}
 	offset := 4
 	for j := 0; j < argIndex; j++ {
-		offset += abiHeadWords(method.Inputs[j].Type) * 32
+		offset += AbiHeadWords(method.Inputs[j].Type) * 32
 	}
 	return offset, nil
 }
@@ -53,7 +53,7 @@ func CalldataStaticWord(method abi.Method, argIndex int) (start, length int, err
 	if err != nil {
 		return 0, 0, err
 	}
-	words := abiHeadWords(method.Inputs[argIndex].Type)
+	words := AbiHeadWords(method.Inputs[argIndex].Type)
 	return start, words * 32, nil
 }
 
@@ -123,3 +123,21 @@ func calldataBytesTail(calldata []byte, method abi.Method, argIndex int) (tailSt
 	}
 	return tailStart, dataLen, nil
 }
+
+func isDynamicType(t abi.Type) bool {
+	switch t.T {
+	case abi.BytesTy, abi.StringTy, abi.SliceTy:
+		return true
+	case abi.ArrayTy:
+		return t.Size == 0 || isDynamicType(*t.Elem)
+	case abi.TupleTy:
+		for _, elem := range t.TupleElems {
+			if isDynamicType(*elem) {
+				return true
+			}
+		}
+		return false
+	default:
+		return false
+	}
+}

…b/sapient/malleable/locators_abi_test.go lib/abicalldata/calldata_test.golib/sapient/malleable/locators_abi_test.go renamed to lib/abicalldata/calldata_test.go lib/sapient/malleable/locators_abi_test.go renamed to lib/abicalldata/calldata_test.go

@@ -1,4 +1,4 @@
-package malleable
+package abicalldata
 
 import (
 	"math"

lib/sapient/malleable/spans.go lib/abicalldata/payload_selector.golib/sapient/malleable/spans.go renamed to lib/abicalldata/payload_selector.go

@@ -1,22 +1,19 @@
-package malleable
+package abicalldata
 
 import (
 	"fmt"
 
 	v3 "github.com/0xsequence/go-sequence/core/v3"
 )
 
-type Span struct {
-	Start int
-	Len   int
-}
-
+// ByteRange identifies a contiguous slice of one call's calldata (data field) in a CallsPayload.
 type ByteRange struct {
 	CallIndex int
 	Offset    int
 	Size      int
 }
 
+// Slice returns the referenced bytes from payload.Calls[CallIndex].Data.
 func (r ByteRange) Slice(payload *v3.CallsPayload) ([]byte, error) {
 	if payload == nil {
 		return nil, fmt.Errorf("payload is nil")
@@ -34,10 +31,18 @@ func (r ByteRange) Slice(payload *v3.CallsPayload) ([]byte, error) {
 	return data[r.Offset : r.Offset+r.Size], nil
 }
 
+// Selector resolves one or more byte ranges in a calls payload (e.g. ABI paths or fixed ranges).
+type Selector interface {
+	Resolve(payload *v3.CallsPayload) ([]ByteRange, error)
+	String() string
+}
+
+// RangeSelector is a Selector backed by a fixed ByteRange (validated on Resolve).
 type RangeSelector struct {
 	Range ByteRange
 }
 
+// NewRangeSelector returns a Selector for an explicit call index, offset, and size within that call's data.
 func NewRangeSelector(callIndex, offset, size int) RangeSelector {
 	return RangeSelector{
 		Range: ByteRange{

lib/hydrate/README.md

@@ -0,0 +1,74 @@
+# Hydrate
+
+Build `hydratePayload` bytes for **HydrateProxy** (`hydrateExecute` / `hydrateExecuteAndSweep` in trails-contracts) by resolving patch targets with [`abicalldata`](https://github.com/0xsequence/go-sequence/tree/master/lib/abicalldata) **`Selector`** and **`ByteRange`** instead of hand-counting calldata offsets.
+
+`hydrate` depends only on `abicalldata` for selector types. The example below builds an `abicalldata.Selector` using `Path` from `lib/sapient/malleable`; fixed offsets can use `abicalldata.NewRangeSelector` instead.
+
+## Usage
+
+```go
+payload := v3.NewCallsPayload(...)
+
+// Selector must resolve to exactly one range on the target call (same index as ForCall).
+permitOwner := malleable.NewPath().
+    CallData(0).
+    ABI(trailsABI, "hydrateExecute").
+    ArgBytesData("packedPayload").
+    EncodedCallsPayload().
+    EncodedCallData(0).
+    ABI(erc2612ABI, "permit").
+    ArgSlot("owner").
+    AsSelector()
+
+b := hydrate.NewBuilder(&payload)
+
+if err := b.ForCall(0).DataAddress(permitOwner, hydrate.SourceSelf()); err != nil {
+    return err
+}
+
+hydratePayload, err := b.Build()
+if err != nil {
+    return err
+}
+// nil/empty hydratePayload means "no hydration" (contract skips hydration).
+
+calldata, err := hydrate.PackHydrateExecute(packedPayload, hydratePayload)
+```
+
+With sweep after execution:
+
+```go
+calldata, err := hydrate.PackHydrateExecuteAndSweep(
+    packedPayload,
+    hydratePayload,
+    sweepTarget,
+    tokensToSweep,
+    sweepNative,
+)
+```
+
+If ABI parameters are unnamed, use index-based steps such as `ArgSlotIndex` / `ArgBytesDataIndex` when your path builder provides them.
+
+## Call sections and ordering
+
+- Use `ForCall(tindex)` for each packed call you want to hydrate. Multiple methods on the same `ForCall` append commands to that call's section.
+- `Build()` emits sections in **ascending** `tindex` order, each as: `[tindex byte][commands…][0x00]`. That order matches how the proxy walks the stream while executing calls; sections must not be reordered arbitrarily.
+
+## Address sources
+
+Data patches and `CallTo` / `CallValue` use a low nibble on the command byte; optional literals append 20 bytes when needed:
+
+| Helper | Meaning at execution time |
+|--------|---------------------------|
+| `SourceSelf()` | `address(this)` (the proxy) |
+| `SourceMsgSender()` | `msg.sender` |
+| `SourceTxOrigin()` | `tx.origin` |
+| `SourceAddress(a)` | fixed `a` (encoded after the flag) |
+
+## Selectors
+
+Each `Data*` method requires an `abicalldata.Selector` that resolves to **exactly one** `abicalldata.ByteRange`, and that range's `CallIndex` must equal the `ForCall` index. The range's offset within that call's `data` becomes the patch offset (`uint16`); the builder checks that 20-byte (address) or 32-byte (uint256) replacements fit.
+
+For unit tests or fixed layouts, `abicalldata.NewRangeSelector(callIndex, offset, size)` returns a selector backed by an explicit range.
+
+When using a multi-step path into nested calldata, ABI context is cleared after any step that narrows the active range or switches to a new byte frame (including `.Slice`, `.ArgBytesData`, `.ArgBytesDataIndex`, `.ArgBytesEncoded`, `.EncodedCallsPayload`, `.EncodedCallData`). Call `.ABI(contractABI, method)` again before `.ArgSlot`, `.ArgSlotIndex`, `.ArgBytesData`, `.ArgBytesDataIndex`, or `.ArgBytesEncoded` on that frame.

lib/hydrate/abi.go

@@ -0,0 +1,34 @@
+package hydrate
+
+import (
+	"bytes"
+	_ "embed"
+	"fmt"
+
+	"github.com/0xsequence/ethkit/go-ethereum/accounts/abi"
+	"github.com/0xsequence/ethkit/go-ethereum/common"
+)
+
+//go:embed abis/HydrateProxy.abi.json
+var hydrateProxyABIJSON []byte
+
+// ABI is the parsed HydrateProxy contract ABI (from trails-contracts artifact).
+var ABI abi.ABI
+
+func init() {
+	var err error
+	ABI, err = abi.JSON(bytes.NewReader(hydrateProxyABIJSON))
+	if err != nil {
+		panic(fmt.Sprintf("hydrate: parse embedded HydrateProxy ABI: %v", err))
+	}
+}
+
+// PackHydrateExecute ABI-encodes a call to HydrateProxy.hydrateExecute.
+func PackHydrateExecute(packedPayload, hydratePayload []byte) ([]byte, error) {
+	return ABI.Pack("hydrateExecute", packedPayload, hydratePayload)
+}
+
+// PackHydrateExecuteAndSweep ABI-encodes hydrateExecuteAndSweep.
+func PackHydrateExecuteAndSweep(packedPayload, hydratePayload []byte, sweepTarget common.Address, tokensToSweep []common.Address, sweepNative bool) ([]byte, error) {
+	return ABI.Pack("hydrateExecuteAndSweep", packedPayload, hydratePayload, sweepTarget, tokensToSweep, sweepNative)
+}