ERC-8313: Protocol Interaction Manifest

Abstract

A Protocol Interaction Manifest (PIM) is a structured, machine-readable JSON document that describes how to interact with a smart contract protocol. It is not just a list of available functions but the full workflow required to safely and correctly fulfil a user's intent while interacting with a smart contract protocol.

Motivation

Protocol interaction knowledge exists primarily in websites and SDKs and not on-chain or in a portable machine-readable format. The websites set up to support dApps are a centralisation risk that depend upon developer team availability for regular maintenance.

Every DeFi protocol exposes functionality through smart contract ABIs. While an ABI can tell you the function names, parameter types and returned values, it does not tell you anything about how to use them.

The more complex protocols, such as UniSwap and ENS, are a system of smart contracts where one contract may be used to discover details while a different contract is used to complete an action. To use these protocols, a user must either connect their wallet to a dApp's webpage or write code using an SDK.

As more protocols are introduced, the ability to maintain wallets supporting these protocols becomes more difficult. Every new protocol would require a new integration. Any update to a protocol would require updating code. Supporting 50 protocols means maintaining 50 integrations where none of the logic is portable, auditable, or shareable.

As an example, if an autonomous agent is instructed to “lend 500 USDC on Aave”, it would have to determine that it must call getReserveData first, check the health factor, approve an allowance for the pool contract, call supply with the right referral code, and then confirm that the aToken balance has increased. That knowledge is currently not available in a form that a generic agent can read.

This problem becomes even more significant for generic wallet software, automation systems, and autonomous agents which cannot rely on bespoke integrations for every protocol.

Specification

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.

Top-level Objects

A PIM MUST include all nine top-level objects in the table below.

metadata

A PIM MUST include a completed metadata section. The section MAY include validFrom and/or validUntil fields. The notes field is OPTIONAL. All other fields MUST be included. Fields MUST only appear once.

The metadata section identifies the protocol, scopes the PIM to specific chains and contracts, and defines any temporal windows when the manifest is valid.

Execution engines MUST reject PIMs with expired validity windows or whose chainId does not match the current network.

contracts

A PIM MUST include a completed contracts section. A contract entry MUST NOT have both address and lookup fields. An execution engine MUST NOT interact with any contracts that are not defined in this section.

The contract section is the address registry for the PIM. Every contract address referenced anywhere in the manifest, whether lookups, buildTransaction steps, or calculations, MUST be declared here first. The execution engine validates all referenced addresses against this registry before execution begins.

Each key in the contracts object is a logical name (example “pool”, “router”, “factory”) that the rest of the manifest references using template syntax: {{contracts.pool.address}}.

Each logical name object MUST include a type definition object using the fields defined in the table below.

As some protocols may use factories that can create new contracts that cannot be defined in advance, or a protocol may manage a large number of template contracts that would make the contract section unmanageable, a contract MAY use a “lookup” field instead of an “address” field. The “lookup” MUST match a lookup in the PIM.

types

It is RECOMMENDED that a PIM includes a completed types section.

Each key in the types section is a named type and the value is an object that MUST include the required fields defined in the tables below.

The types section mirrors Solidity structs and is used to define the data types and tuples used in PIMs. They are used to define contract inputs and outputs for use in encoding calldata for buildTransaction steps that accept tuple parameters as well as decode return values from lookup steps that return tuples.

Types are referenced by name in lookups and intents. The execution engine MUST be able to ABI-encode any type defined here using the standard Solidity encoding rules.

Tuple kinds

Field definition objects

lookups

The completion of the lookup section is OPTIONAL.

Each key in the lookups section is a named type and the value is an object that MUST include the required fields defined in the table below.

The lookups section defines named on-chain read operations or simulated write operations. If a reference function is not read-only, the execution engine MUST simulate the transaction only.

Each lookup describes a function call: which contract to call, what arguments to pass, and what structure to expect in the return value. Lookups are referenced by name in intent steps and contracts using the action: “lookup” directive.

Lookups MUST NOT trigger state changes.

The iterate pattern

Many protocols may deploy multiple pools or fee tiers for the same token pair. The iterate pattern allows a single lookup definition to fan out across multiple values and collect all results. As an example:

"pool": {
 "contract": "factory",
 "function": "getPool",
 "args": ["{{tokenIn}}", "{{tokenOut}}", "{{fee}}"],
 "iterate": { "fee": [100, 500, 3000, 10000] },
 "filter": { "notEqual": "0x0000000000000000000000000000000000000000" },
 "select": "all"
}

The above partial sample runs getPool four times, once per fee tier, and only returns the results where a pool actually exists (non-zero address). The returned results are an array of results keyed by the iteration values. As an example of possible output from the fee iteration from above:

[
 {"100":"0x0000000000000000000000000000000000000001"},
 {"500":"0x0000000000000000000000000000000000000002"},
 {"3000":"0x0000000000000000000000000000000000000003"},
 {"10000":"0x0000000000000000000000000000000000000004"}
]

Validate assertions

Lookups can include field-level assertions that gate further execution. If a reserve is frozen, if borrow capacity is zero, if a health factor is critically low, the validate array can catch these transactions before any transaction is built.

Referenced values can either be literal values or named types from the type section.

By convention, a validate object MUST contain at least one of the “notEqual”, “equals”, “greaterThan”, or “lessThan” fields. More than one of these fields MAY be used in combination (for example, if a value needs to be within a range of 1 – 10, then the validation can include “greaterThan”: “0” and “lessThan”: “11”).

All values keyed to the operator fields MUST be strings and the execution engine MUST use the type to correctly read the data.

Validate assertions MUST only be applied to returned values.

calculations

It is RECOMMENDED that a PIM includes a completed calculations section.

Each key in the calculations section is a named type and the value is an object that MUST include the required fields defined in the table below.

The calculations section defines named off-chain computations. These are mathematical operations that the execution engine performs locally without making any RPC calls. Common uses can include computing deadlines, applying slippage tolerances, encoding multi-hop paths, and formatting display values.

The formula field MUST reference only variables listed in the types section, the intents section, or recognized global variables such as block.timestamp or msg.sender; best practice is to include variables (except global) in the inputs field.

Instruction objects

Instruction objects use a key:value method where the key indicates the operation to be done and the value is the scalar used in the operation.

The formula field MUST include one "set" object. The "set" object is always the first instruction and indicates the initial value; it can be a scalar value or a variable.

The "op" key MAY be used in place of a value for inner calculations (similar to using brackets in mathematical equations). An "op" key's inner calculation MUST include its own "set" object.

The formula field MUST NOT have more than one "set" object except for within inner "op" objects. "op" objects MUST NOT have more than one "set" object except for within inner "op" objects.

intents

The intents section is the operational core of the PIM. A PIM MUST contain at least one intent object.

Each intent is a named, executable workflow. When a user or agent expresses a goal (swap, borrow, register), the execution engine finds the matching intent, binds the user's inputs to the intent's variables, and executes each step in order.

Each key in the intents section is a named type and the value is an object that MUST include the required fields defined in the table below. Every intent MUST have a corresponding intentDescription object in the ui section.

Step objects

Each step in the steps object has an action field that determines what the execution engine does.

Step fields (all step types)

Step fields (buildTransactions only):

Template variables

Step arguments use double-bracket template syntax to reference values from the execution context. Examples include:

| Syntax | Resolves to | | {{userAddress}} | The wallet address of the user initiating the event. | | {{asset}} | An intent input variable named 'asset'. | | {{asset.symbol}} | The symbol of the intent input variable names 'asset'. |

ui

The ui (user interface) section provides human-readable labels and display strings. It is consumed by wallets and agent interfaces to present intent results in plain English. Nothing in the ui section affects execution logic.

The ui section MUST include intentDescriptions for all named intents from the intent section.

signatures

It is RECOMMENDED to include a completed signatures section.

Unsigned PIMs MUST be treated as Level 0 - Unverified.

The signatures section includes the cryptographic signature of the PIM content. Each signature enables the Trust Resolver to assign a trust level to the manifest. If the signature section is included, it MUST include either a signer field or a signerHashed field as well as all required fields listed in the table below.

What is signed

The signature MUST be of the keccak256 hash of the entire PIM excluding the signatures section. Any spacing, new lines or hidden characters added for human-readability MUST be removed before the hash is generated.

Trust level assignment

An execution engine MUST include a trust resolver that assigns a trust level to a PIM.

Chain Specifics

A PIM can be created for multiple chains but all chains MUST have the same contract addresses. If a chain has a different set of contract addresses, even if it is only one contract out of many that does not match other chains, it MUST have a separate PIM.

Rationale

TBD

Backwards Compatibility

This ERC does not change the consensus layer, so there are no backwards compatibility issues for Ethereum as a whole.

Reference Implementation

No reference implementation is provided in this draft.

TBD

Security Considerations

Threat model

PIMs are untrusted inputs. Even a level 2 protocol-signed PIM can only be trusted to the extent of its verified content. The threat model assumes:

• A PIM may be crafted by a malicious actor attempting to steal funds
• A legitimate PIM may be compromised if the protocol's signing key is stolen
• A community PIM may be well-intentioned but contain errors

The security model assumes zero trust in the PIM content and derives safety entirely from the execution engine's enforcement rules and simulation results.

Attack vectors and mitigations

Simulation requirement

Simulation is the final line of defence. No matter how well the PIM is written, nor how high its trust level is, nor how clean its static analysis, the actual execution must be verified before the use signs.

A compliant engine must:

• Simulate every transaction in the proposed sequence via eth_call against the current block state.
• Compute the actual token balance delta for every address that appears in the transaction.
• Compare the actual delta against the expected outcome declared in the intent.
• Block submission if any delta deviates beyond a defined tolerance (typically 0.1%)
• Show the user the simulated outcome, not the PIM-declared outcome

Security: If simulation is unavailable (RPC failure, rate limit), execution MUST NOT proceed. The user SHOULD be informed that pre-flight verification could not be completed.

User experience model

Design principles

• Users see outcomes, not calldata. The confirmation screen shows what token moves, in what amount, and to whom - never raw hex.
• Complexity is hidden, risk is not. Fee tiers, routing, and path encoding are invisible. Slippage, price impact, and health factor risk are prominent.
• Deterministic previews. The confirmation screen MUST reflect what will actually happen on-chain, verified by simulation.
• Trust is visible. The trust level of the active PIM MUST always be shown. A level 0 PIM should feel meaningfully different from a level 2.
• Multi-step is sequential. If an intent requires multiple transactions (e.g. approve then swap), each is confirmed individually by the user. Subsequent steps never proceed without confirmation.

Confirmation screen requirements

Every intent execution must display a confirmation screen before any transaction is submitted. The screen MUST include:

Copyright

Copyright and related rights waived via CC0.