feat: Path B /api/notify summaries + erc20_overrides for run-node (#627)

Co-authored-by: Antriksh Gwal <antrikshgwal@gmail.com>
Co-authored-by: Will Zimmerman <will@avaprotocol.org>

Author: 3 people

aggregator/rest/generated/types.gen.go

@@ -54,6 +54,9 @@ func (s *Server) RunNode(ctx echo.Context) error {
 		}
 		req.InputVariables = converted
 	}
+	if body.Erc20Overrides != nil {
+		req.Erc20Overrides = openAPIERC20OverridesToProto(*body.Erc20Overrides)
+	}
 
 	resp, err := s.engine.RunNodeImmediatelyRPCWithContext(ctx.Request().Context(), user, req)
 	if err != nil {
@@ -62,6 +65,50 @@ func (s *Server) RunNode(ctx echo.Context) error {
 	return ctx.JSON(http.StatusOK, runNodeRespToOpenAPI(resp))
 }
 
+// openAPIERC20OverridesToProto maps the REST ERC20StateOverride list onto the
+// proto representation consumed by RunNodeImmediately. Slot indices are widened
+// from the spec's int64 to the proto's uint64. A negative slot is invalid (a
+// storage slot is a non-negative index), so it is treated as unset rather than
+// silently coerced to slot 0 — and because the engine requires an explicit slot
+// whenever the corresponding balance/allowance is set, a missing or negative
+// slot surfaces as a clear validation error instead of a wrong-slot seed. The
+// engine validates addresses/values.
+func openAPIERC20OverridesToProto(in []generated.ERC20StateOverride) []*avsproto.ERC20StateOverride {
+	if len(in) == 0 {
+		return nil
+	}
+	out := make([]*avsproto.ERC20StateOverride, 0, len(in))
+	for _, o := range in {
+		po := &avsproto.ERC20StateOverride{
+			TokenAddress: string(o.TokenAddress),
+			OwnerAddress: string(o.OwnerAddress),
+			Balance:      o.Balance,
+			Allowance:    o.Allowance,
+		}
+		if o.SpenderAddress != nil {
+			s := string(*o.SpenderAddress)
+			po.SpenderAddress = &s
+		}
+		po.BalanceSlot = nonNegativeSlotPtr(o.BalanceSlot)
+		po.AllowanceSlot = nonNegativeSlotPtr(o.AllowanceSlot)
+		out = append(out, po)
+	}
+	return out
+}
+
+// nonNegativeSlotPtr widens a spec int64 storage slot to the proto's uint64,
+// returning nil when the slot is absent or negative. A nil slot is then
+// rejected by the engine (an explicit slot is required when balance/allowance
+// is set), so a negative value surfaces as a validation error rather than a
+// silent slot-0 seed.
+func nonNegativeSlotPtr(v *int64) *uint64 {
+	if v == nil || *v < 0 {
+		return nil
+	}
+	u := uint64(*v)
+	return &u
+}
+
 // runNodeRespToOpenAPI maps the engine RunNodeWithInputsResp to the
 // OpenAPI RunNodeResponse. The per-type OutputData oneof is flattened
 // to a generic map[string]interface{} via protojson — the SDK consumes

aggregator/rest/handlers_nodes.go

@@ -1427,6 +1427,46 @@ components:
         node: { $ref: '#/components/schemas/Node' }
         inputVariables: { $ref: '#/components/schemas/InputVariables' }
         chainId: { $ref: '#/components/schemas/ChainId' }
+        erc20Overrides:
+          type: array
+          description: >
+            Optional ERC20 balance/allowance state overrides applied only during
+            this isolated node simulation. Lets callers seed token balances and
+            approvals so contract-write simulations (e.g. Uniswap swaps) don't
+            revert with "transfer amount exceeds allowance/balance" before the
+            approval/funding transactions have been run. Simulation-only: a
+            real-execution request (isSimulated=false) that sets these is rejected
+            with an error, never silently ignored.
+          items: { $ref: '#/components/schemas/ERC20StateOverride' }
+
+    ERC20StateOverride:
+      type: object
+      required: [tokenAddress, ownerAddress]
+      description: >
+        Seeds a token's balanceOf / allowance storage slots for a single
+        simulation. balanceOf[owner] lives at keccak256(abi.encode(owner,
+        balanceSlot)); allowance[owner][spender] at keccak256(abi.encode(spender,
+        keccak256(abi.encode(owner, allowanceSlot)))).
+      properties:
+        tokenAddress: { $ref: '#/components/schemas/EthereumAddress' }
+        ownerAddress: { $ref: '#/components/schemas/EthereumAddress' }
+        spenderAddress: { $ref: '#/components/schemas/EthereumAddress' }
+        balance:
+          type: string
+          description: Balance override (hex 0x… or decimal string).
+        allowance:
+          type: string
+          description: Allowance override (hex 0x… or decimal string).
+        balanceSlot:
+          type: integer
+          format: int64
+          minimum: 0
+          description: 'Storage slot for the balanceOf mapping. Required when balance is set; ERC20 storage layout varies per token (OpenZeppelin 0, USDC FiatToken 9).'
+        allowanceSlot:
+          type: integer
+          format: int64
+          minimum: 0
+          description: 'Storage slot for the allowance mapping. Required when allowance is set; ERC20 storage layout varies per token (OpenZeppelin 1, USDC FiatToken 10).'
 
     RunNodeResponse:
       type: object

api/openapi.yaml

@@ -8,13 +8,30 @@ When simulating contract writes involving ERC20 tokens (like Uniswap swaps), you
 
 This document explains how to calculate and use Tenderly state overrides for ERC20 tokens.
 
+## Status
+
+State overrides are implemented and accumulated by `SimulationStateMap`
+(`simulation_state.go`), applied to every Tenderly call via
+`BuildStateObjects()` (`tenderly_client.go`). There are two ways state overrides
+get populated:
+
+1. **Automatic** — event-trigger / multi-step workflow simulation. A Transfer
+   event replayed during simulation injects a balance delta
+   (`InjectERC20BalanceChange`), and each step's `raw_state_diff` is carried
+   forward (`MergeRawStateDiff`) so later steps see a consistent view.
+2. **User-supplied** — the `erc20_overrides` field on `RunNodeWithInputsReq`
+   (REST: `erc20Overrides` on `POST /api/v1/nodes:run`). This lets a caller
+   testing an isolated `RunNodeImmediately` swap seed an arbitrary balance and
+   allowance up front, with no preceding trigger. See
+   [User-facing API](#user-facing-api-erc20_overrides) below.
+
 ## How ERC20 Storage Works
 
 ERC20 tokens use Solidity mappings to store balances and allowances:
 
 ```solidity
 mapping(address => uint256) public balanceOf;           // Usually at storage slot 0
-mapping(address => mapping(address => uint256)) public allowance;  // Usually at slot 3 or 4
+mapping(address => mapping(address => uint256)) public allowance;  // OpenZeppelin: slot 1 (varies by token)
 ```
 
 ## Calculating Storage Slots
@@ -43,31 +60,35 @@ storage_slot = keccak256(abi.encode(spender_address, inner_hash))
 Where:
 - `owner_address` is the token owner (32 bytes, left-padded)
 - `spender_address` is the approved spender (32 bytes, left-padded)
-- `allowance_mapping_slot` is usually 3 or 4 (check the token contract)
+- `allowance_mapping_slot` is 1 for standard OpenZeppelin ERC20 (varies by token — e.g. USDC FiatToken uses 10; check the token contract)
 
 ## Go Implementation
 
-Example implementation for calculating ERC20 storage slots:
+The slot math lives in `simulation_state.go` as `erc20BalanceSlot` and
+`erc20AllowanceSlot`:
 
 ```go
-func calculateERC20StorageSlots(owner, spender, tokenAddress common.Address, balanceSlot, allowanceSlot uint64) (balanceStorageSlot, allowanceStorageSlot string) {
-	// Balance slot: keccak256(abi.encode(owner, balanceSlot))
-	ownerPadded := common.LeftPadBytes(owner.Bytes(), 32)
-	balanceSlotPadded := common.LeftPadBytes(big.NewInt(int64(balanceSlot)).Bytes(), 32)
-	balanceData := append(ownerPadded, balanceSlotPadded...)
-	balanceHash := crypto.Keccak256Hash(balanceData)
-	
-	// Allowance slot: keccak256(abi.encode(spender, keccak256(abi.encode(owner, allowanceSlot))))
-	allowanceSlotPadded := common.LeftPadBytes(big.NewInt(int64(allowanceSlot)).Bytes(), 32)
-	innerData := append(ownerPadded, allowanceSlotPadded...)
-	innerHash := crypto.Keccak256Hash(innerData)
-	
-	spenderPadded := common.LeftPadBytes(spender.Bytes(), 32)
-	outerData := append(spenderPadded, innerHash.Bytes()...)
-	allowanceHash := crypto.Keccak256Hash(outerData)
-	
-	return balanceHash.Hex(), allowanceHash.Hex()
-}
+// keccak256(abi.encode(holder, mappingSlot))
+func erc20BalanceSlot(holder common.Address, mappingSlot int64) common.Hash
+
+// keccak256(abi.encode(spender, keccak256(abi.encode(owner, mappingSlot))))
+func erc20AllowanceSlot(owner, spender common.Address, mappingSlot int64) common.Hash
+```
+
+To seed a balance and/or allowance directly, use the higher-level helper
+`SimulationStateMap.ApplyUserERC20Override`, which parses hex/decimal values,
+computes the mapping slots from the caller-supplied slot indices, and records
+the storage override. The slot is required whenever the corresponding value is
+set — ERC20 storage layout is not standardized, so there is no safe default:
+
+```go
+err := vm.simulationState.ApplyUserERC20Override(
+    tokenAddress, ownerAddress, spenderAddress,
+    "0x38d7ea4c68000", // balance: 1,000,000,000 USDC
+    "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff", // allowance: max uint256
+    balanceSlotPtr,   // *uint64, required when balance is set (e.g. USDC: 9)
+    allowanceSlotPtr, // *uint64, required when allowance is set (e.g. USDC: 10)
+)
 ```
 
 ## Tenderly API Format
@@ -98,31 +119,81 @@ When calling the Tenderly simulation API, include state overrides in the `state_
 ```
 
 Where:
-- Token balance: `0x38d7ea4c68000` = 1,000,000 USDC (6 decimals)
+- Token balance: `0x38d7ea4c68000` = 1,000,000,000 USDC (6 decimals)
 - Token allowance: `0xffff...ffff` = max uint256 (unlimited approval)
 
 ## Common Token Storage Slots
 
 | Token Type | balanceOf Slot | allowance Slot |
 |------------|----------------|----------------|
-| Standard ERC20 | 0 | 3 |
-| OpenZeppelin ERC20 | 0 | 1 |
+| OpenZeppelin ERC20 (v4/v5) | 0 | 1 |
 | USDC (FiatToken) | 9 | 10 |
 
 **Note:** Always verify the actual storage layout by checking the token's contract source code or using tools like `cast storage` from Foundry.
 
-## Implementation TODO
+## User-facing API: `erc20_overrides`
 
-To enable state overrides in production code, the `TenderlyClient.SimulateContractWrite()` method needs to be enhanced to:
+`RunNodeImmediately` accepts optional ERC20 overrides so an isolated
+contract-write simulation can seed balances/approvals up front. The overrides
+are **simulation-only** — `RunNodeImmediately` rejects them in real-execution
+mode, and they never apply to deployed workflows.
 
-1. Accept optional parameters for ERC20 overrides:
-   - Token addresses to override
-   - Balance and allowance values
-   - Storage slot numbers
+### Request shape
 
-2. Calculate storage slots using the helper function
+Protobuf (`RunNodeWithInputsReq`):
+
+```protobuf
+repeated ERC20StateOverride erc20_overrides = 5;
+
+message ERC20StateOverride {
+  string token_address = 1;            // ERC20 token contract address
+  string owner_address = 2;            // Address whose balance/allowance to override
+  optional string spender_address = 3; // Spender to approve (required for allowance override)
+  optional string balance = 4;         // Balance override (hex 0x… or decimal string)
+  optional string allowance = 5;       // Allowance override (hex 0x… or decimal string)
+  optional uint64 balance_slot = 6;    // Storage slot for the balanceOf mapping (required when balance is set; layout varies per token)
+  optional uint64 allowance_slot = 7;  // Storage slot for the allowance mapping (required when allowance is set; layout varies per token)
+}
+```
+
+REST (`POST /api/v1/nodes:run`, camelCase): `erc20Overrides` is an array of the
+same fields (`tokenAddress`, `ownerAddress`, `spenderAddress`, `balance`,
+`allowance`, `balanceSlot`, `allowanceSlot`).
+
+### SDK example
+
+```javascript
+const result = await client.runNodeWithInputs({
+  node: { /* contractWrite node */ },
+  inputVariables: { settings: { runner: '0x71c8f4D…' } },
+  erc20Overrides: [
+    {
+      tokenAddress: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238', // USDC
+      ownerAddress: '0x71c8f4D7D5291EdCb3A081802e7efB2788Bd232e',
+      spenderAddress: '0x3bFA4769FB09eefC5a80d6E87c3B9C650f7Ae48E', // SwapRouter02
+      balance: '0x38d7ea4c68000',  // 1,000,000,000 USDC (6 decimals)
+      allowance: '0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff', // max uint256
+      balanceSlot: 9,    // USDC FiatToken layout (required — see table below)
+      allowanceSlot: 10, // USDC FiatToken layout (required — see table below)
+    },
+  ],
+});
+```
 
-3. Include the `state_objects` in the Tenderly API payload
+### Validation
+
+- `token_address` / `owner_address` must be valid hex addresses.
+- An allowance override requires a valid `spender_address`.
+- At least one of `balance` / `allowance` must be set.
+- `balance` / `allowance` must be non-negative and fit in a `uint256`.
+- `balance_slot` is required when `balance` is set, and `allowance_slot` is
+  required when `allowance` is set. ERC20 storage layout is not standardized —
+  OpenZeppelin uses `_balances` at slot 0 / `_allowances` at slot 1, USDC
+  (FiatToken) uses 9/10, others differ — so there is no safe default and a
+  missing slot is a validation error (a guessed slot would silently seed the
+  wrong storage word). Look up your token's layout (see the
+  [table below](#common-token-storage-slots)); if unsure, send several overrides
+  for the same token, one per candidate slot.
 
 ## Example Use Case: Uniswap Swap