ERC-7845 Generic Orchestrator RPC (Universal Orchestrator RPC)
Draft · Accounts & wallets · created 2024-11-07
Defines a request/response data specification by which any system, such as a wallet or voice assistant, sends an orchestrator a "what I want to do" request (a Problem) in a common format and receives back a bundle of transactions to execute (a Solution).
Why it is needed
Intermediary systems that design asset transfers or swaps across multiple chains on a user's behalf, i.e. orchestrators, can each demand a differently shaped request format. When data specifications vary, wallets and apps must write separate integration code for each orchestrator, and interoperability between orchestrators becomes difficult. The proposal anticipates that the number of orchestrators will keep growing as AI assistants, voice-controlled devices, and XR platforms proliferate, and proposes standardizing the minimum shape and requirements of the request objects wallets send. The motivation is that this would let developers who cannot build onchain transactions themselves or who lack deep knowledge of block-building structures more easily build decentralized apps.
In depth
Request structure: RPC and Problem
The request follows the top-level shape of Ethereum JSON-RPC as-is. The Rpc object has id (an arbitrary number), jsonrpc (typically "2.0"), method (orchestrator_findSolutions can be used as a default), and params, where params is required and is an array of Problem. Problem intentionally has a sparse structure with only one required property, actions, leaving room for future network upgrades or other standards to add properties. If the optional chainId property is omitted, it MUST be treated as 1 (Ethereum mainnet). The orchestrator's external interface MUST use JSON; this standard does not aim to standardize the orchestrator's internal data structures or communication layer.
Action: what is being requested
An Action sets its target via from (the wallet address for this action, required) and towards (an array of Asset or Destination, required), and sets the means of payment via with (an array of Offering the wallet is willing to put up, optional). If with is empty, the orchestrator MUST consider all assets at that address as candidate Offerings. type is a classification hint such as transfer, swap, or call, and MUST be treated as transfer if omitted. If functionCallName is specified, the Action can be treated as a request for a smart contract call, and functionCallData is the data for that call. If functionCallData is present without functionCallName, it SHOULD be ignored. deadline is an optional property letting the wallet set, as a Unix timestamp, the deadline by which a solution must be produced.
Asset and Destination: chain abstraction and fixed targets
towards can take two kinds of values. Asset has symbol, address, and chainId all optional, and favors chain abstraction. If symbol is absent, address MUST be used; if address is absent, the native gas token MUST be used; if chainId is absent, the orchestrator is free to use the corresponding asset on any chain. Destination, by contrast, requires both address and chainId, and is used for a directly specified target that MUST NOT be subject to interpretation by the orchestrator. In the reference implementation example, specifying chainId 137 on a Destination pins the action to that chain.
Offering: what and how much to put up
An Offering is the asset the requester is willing to have the wallet spend to resolve the action. symbol and address SHOULD be specified; if symbol is absent, address MUST be used, and if address is absent, the native gas token MUST be used. amount is optional: if it is a number it is in ether units, if it is a string it is for a BigNumber, and if absent the maximum value for that address/symbol/native gas unit MUST be assumed. When chainId is absent, address MUST NOT be used and symbol MUST be used instead; if the parent Problem also lacks a chainId, the orchestrator may use the corresponding asset on any chain to carry out the action. This is the chain abstraction (ChA) behavior this proposal refers to.
Response structure: Solution and Transaction
The response Rpc's id MUST match the number received in the request, and result is an array of Solution. Solution MUST be in the same order as the requested Problem, and has name (a short, non-technical, user-friendly name, required), description (optional), transactions (required), and deadline (an execution deadline set by the orchestrator, optional). Transaction requires to (of type Destination), chainId, and amount, with calldata optional. Because multi-chain assets exist, the wallet needs to know where to send the asset from, so Transaction's chainId is mandated as required. Parameters such as gas limits and estimates are delegated to the wallet, since the wallet is the party that actually executes the solution.
Design rationale and proposal status
For compatibility, this proposal reuses the Ethereum JSON-RPC wrapper as-is, and uses only generic primitive types in the interface so it is easy to handle in any programming language. Terminology also favors non-technical vocabulary, aiming for broad adoption. Given that each orchestrator will interpret and implement things differently, the parts marked as required (MUST) are meant to guarantee a universal level of service. This document is currently in Draft status. Since it is at a proposal stage where content may still change, implementers should check the latest state of the source.
Things to watch out for
- Orchestrator reputation: Since anyone can build an orchestrator, there may be code errors, degraded service quality, or orchestrators that become abandoned over time. Whether a given orchestrator is trustworthy should be judged by a reputation score, and that judgment should be left to the requesting system or wallet.
- Dishonest solutions: An orchestrator may return an incorrect transaction or attempt to take more than requested. Where possible, the destination address and other data of the returned transaction should be verified.
- Differences in orchestrator incentives: While not strictly a security issue, some orchestrators may skew solutions in favor of their own business goals. Unless this is the intended behavior, the requesting system or wallet should be aware of this.