“Assistant, how much USDC can I buy with what’s in my wallet?”
“Send 10 OP to Vitalik and 5 PEPE to Deimantas”
The Universal Orchestrator RPC aims to standardise the minimum shape and requirements of a request for a solutionfrom an arbitrary system managing an Ethereum wallet to, ultimately, an Orchestrator.
An arbitrary system could be a website, device, app, server program etc - anything that manages an Ethereum wallet, speaks Ethereum JSON-RPC and is looking to request solutions from an Orchestrator.
All solutions from an Orchestrator are ChA¹ (Chain Abstraction-first) by default.
Motivation
Data model standards can be written in any shape. A system will often expose their external interface but require that the request to the aforementioned interface is modelled in a way that the service understands. This creates a huge level of inconsistency and in turn makes Orchestrator interoperability more difficult.
Orchestrators will become more widespread and numerous over time. This is especially true with the advent of Artificial Intelligence (AI) driven systems, the continued advancement of Human Computer Interaction (HCI) devices (especially those that are voice controlled) and the emergence of Extended Reality (XR) platforms.
Standardising the request object that an Orchestrator can understand from a wallet will drive adoption and make decentralised app development easier for developers that don’t know how to make on-chain transactions or have the required technical understanding of block building systems.
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.
The Orchestrator’s external interface(s) that expose functionality to an end-user application or another system MUST use JavaScript Object Notation (JSON).
The following data definitions are available and MUST prefer chain abstraction (ChA¹), unless stated. Chain abstraction means that, where possible, should an asset span multiple chains - expect a solution from an Orchestrator to use and send assets to and from the supported chains to deliver a complete and cost-effective solution.
The following sequence diagram shows the flow of events in this proposal:
This specification follows the top level data shape of Ethereum JSON-RPC requests, as shown below:
Request
The request definition is what a wallet sends to an Orchestrator for solutions to one or more problems. The request follows the specification from Ethereum JSON-RPC.
The Problem definition has just one REQUIRED property, actions. The Problem interface leaves space for additional properties in future network upgrades and existing or emerging standards.
The actions property takes an array of Action objects, defined below, and is REQUIRED.
The chainId takes a number, representing the chain ID, and is OPTIONAL.
The Action definition has several properties that indicate the desired action. The set properties determine the action that needs to be solved.
The from property is REQUIRED, takes a string and represents the wallet that this Action is for.
The towards property is REQUIRED, takes an array of either an Asset or a Destination type and represents where this Action is targeted towards.
The with property is OPTIONAL, takes an array of Offering type and represents what assets the wallet is prepared to offer to facilitate this Action
If the with property contains no Offering entries, then the Orchestrator MUST consider all assets available in the address space for an Offering.
The type property is OPTIONAL, takes a string and is intended to help classify this action. Examples might include, but are not limited to - transfer, swap, call etc and is intended to assist the Orchestrator with the action.
If no type is provided, then ‘transfer’ MUST be assumed
The functionCallName property is OPTIONAL, takes a string and represents the function name to call against the towards property. If this is defined, the Orchestrator can be assumed that this Action desires to call a smart contract as part of the action.
The functionCallData property is OPTIONAL, takes a string and represents the data payload for functionCallName. If this is defined but functionCallName is not, this property SHOULD be ignored.
The deadline property is OPTIONAL, takes a number and represents a wallet-defined unix timestamp for when an action should have a solution by. Useful for high throughput systems, or time sensitive actions.
The Asset definition defines an asset in question. This definition prefers chain abstraction.
The symbol property is OPTIONAL, takes a string and represents the symbol of the Asset in question.
if no symbol is provided, address must be used
The address property is OPTIONAL, takes a string and represents the address of the smart contract for this Asset.
if no address is provided, the native gas token MUST be used
The chainId property is OPTIONAL, takes a number and represents the chain that this asset resides on. Useful for direct targeting of an Asset on a particular chain.
If no chainId is provided: - The Orchestrator is free to use any corresponding asset on any chain to facilitate the action
The Offering definition defines what the requester is willing to spend from their wallet in order to facilitate the action being solved.
The symbol property SHOULD be specified and represents the symbol of the Offering in question
If no symbol is provided, the address MUST be used
The address property SHOULD be specified and takes a string that represents the address space for this Offering.
If no address is provided, the native gas token MUST be used
The amount property is OPTIONAL and represents the amount to be offered as part of the Action. Accepts either a number, which represents an ether unit, or a string which can be used for BigNumbers.
If no amount is provided, the maximum value of the address, symbol or native gas unit must be assumed
The chainId property is OPTIONAL and takes a number that represents the chain the above address property resides on.
If no chainId is provided:
address MUST NOT be used
symbol MUST be used (ChA¹)
If no higher level chainId property exists in the Problem property
The Orchestrator is free to use any corresponding asset on any chain to facilitate the action (ChA¹)
Response
The response definition is what an Orchestrator sends back as a response to the request for solutions from a wallet. The response, like the request, follows the specification from Ethereum JSON-RPC.
The above Solution interface is the solution to a problem requested above. The Solution MUST be in the same order to a Problem that was requested.
The name property is REQUIRED, takes a string and represents a short, non-technical and user-friendly, name of the solution.
The description property is OPTIONAL, takes a string and represents a longer, non-technical and user-friendly, description of the solution.
The transactions property is REQUIRED, takes an array of Transaction objects and represents one or more transactions needed for the user to execute the solution.
The deadline property is OPTIONAL, takes a number and represents a unix timestamp by which this Solution should be executed. This is defined by the Orchestrator.
The above Transaction interface is a transaction definition that allows a wallet to perform their solution to a problem. There may be 1 or more transactions for a Solution.
The to property is REQUIRED, takes a Destination type and represents the target for this Solution.
The chainId property is REQUIRED, takes a number and represents the chain that this Transaction is targeted at. The chainId is REQUIRED here because the wallet MUST know where to send assets from as an origin due to the existence of multichain assets.
The amount property is REQUIRED and represents the amount to be sent as part of the Transaction. Accepts either a number, which represents an ether unit, or a string which can be used for BigNumbers.
Rationale
Uses the Ethereum JSON-RPC JSON wrapper for greater compatibility.
The interface definitions use only generic primitive types to ensure wide compatibility for any programming language.
The interface definitions defined in this ERC attempts to cover as many scenarios as possible, from an Orchestrator perspective that a wallet may ask for, but focuses on core blockchain functionality.
Certain high-level definitions, such as the Problem object definition, are sparse by design to allow space for future features introduced by other ERC’s or network upgrades.
Terminology is targeted towards a non-technical lexicon to aid in wider adoption and understanding.
Nearly all options are REQUIRED, SHOULD and OPTIONAL to allow for both wallet and Orchestrator flexibility in providing solutions for the wallet request.
It’s understood that the Orchestrator interpretations and implementations will vary, so where possible the specification enforces REQUIRED and MUST to provide a universal level of service to an end-user or another service.
The specification is NOT intended to standardise or modify the internal data structure or communication layer of an Orchestrator.
Other parameters that could be considered, such as gas limits and estimations, are delegated back to the wallet as ultimately it is the wallet that will execute the solution(s).
Backwards Compatibility
No backward compatibility issues found.
Reference Implementation
Example requests and responses for solutions
The following examples show a few common scenarios with their requests to, and from, an Orchestrator. All examples are chain abstracted (ChA¹) by default, unless specified.
towards address 0x50840CE036eEf2005d3c4d6f6Eb65f8116a01629
with symbol USDC, amount 5
[!NOTE]
Notes: All requests for solutions should be chain abstracted (ChA¹) by default. The Orchestrator > > can check for 5 USDC on any chain for the above “from” address, and send a solution that receives > the 5 USDC on any other chain.
{"id":1234,"jsonrpc":"2.0","result":[{"name":"Send 5 USDC","description":"Send 5 USDC from 0xbafB4E1EFA94B359e2E175CF6156AedA2cACa165 to 0x50840CE036eEf2005d3c4d6f6Eb65f8116a01629","transactions":[{"to":"0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48","chainId":1,"calldata":"0x0...","value":0}]}]}
Swapping native token to USDC
The following request performs an action:
from 0xbafB4E1EFA94B359e2E175CF6156AedA2cACa165
towards symbol USDC
with: 0.1
[!NOTE]
Notes: All requests for solutions should be chain abstracted (ChA¹) by default. The Orchestrator
can take 0.1 native asset from any chain in return for USDC on any chain.
{"id":1337,"jsonrpc":"2.0","result":[{"name":"Swap 0.1 ETH for 371.498 USDC","description":"Swapping 0.1 ETH from 0xbafB4E1EFA94B359e2E175CF6156AedA2cACa165 to 371.498 USDC via Uniswap","transactions":[{"to":"0x...","chainId":1,"calldata":"0x0...","value":0},{"to":"0x...","chainId":1,"calldata":"0x...","value":0.1}]}]}
Swapping multiple tokens to USDC
The following request performs an action:
from 0xbafB4E1EFA94B359e2E175CF6156AedA2cACa165
towards symbol USDC
with SHIB and / or Pillar
[!NOTE]
Notes: All requests for solutions should be chain abstracted (ChA¹) by default. The Orchestrator
can take any amount of SHIB and / or Pillar from any chain in return for an exchanged amount of
USDC on any chain.
{"id":1337,"jsonrpc":"2.0","result":[{"name":"Swap 171,246 SHIB and 1004.72 Pillar for 10 USDC","description":"Swapping 171,246 SHIB and 1004.72 Pillar from 0xbafB4E1EFA94B359e2E175CF6156AedA2cACa165 to 10 USDC via Uniswap","transactions":[{"to":"0x...","chainId":1,"calldata":"0x0...","value":0},{"to":"0x...","chainId":1,"calldata":"0x0...","value":0},{"to":"0x...","chainId":1,"calldata":"0x...","value":0.1}]}]}
The following request performs the following actions:
Action 1
from 0xbafB4E1EFA94B359e2E175CF6156AedA2cACa165
towards address 0x50840CE036eEf2005d3c4d6f6Eb65f8116a01629
with 5 USDC
Action 2
from 0xbafB4E1EFA94B359e2E175CF6156AedA2cACa165
towards address 0xFCd239451346238B5560511Ae47A0b82b1bbE9f0
with 100 PLR
[!NOTE]
Notes: All requests for solutions should be chain abstracted (ChA¹) by default. The Orchestrator
can move the specified asset amounts on any chain where the asset exists in the “from” address.
{"id":1000,"jsonrpc":"2.0","result":[{"name":"Send 5 USDC to 0x...629 and 100 PLR to 0x...9f0","description":"Send 5 USDC to 0x50840CE036eEf2005d3c4d6f6Eb65f8116a01629 and 100 PLR to 0xFCd239451346238B5560511Ae47A0b82b1bbE9f0","transactions":[{"to":"0x...","chainId":1,"calldata":"0x0...","value":0},{"to":"0x...","chainId":1,"calldata":"0x...","value":0}]}]}
Calling a Smart Contract function on Polygon: Inscribing a message which costs 1 USDC
The following request performs an action:
from 0xbafB4E1EFA94B359e2E175CF6156AedA2cACa165
towards address 0x50840CE036eEf2005d3c4d6f6Eb65f8116a01629 on chain 137
with 1 USDC
calling “inscribe” with “0x…”
[!NOTE]
Notes: All requests for solutions should be chain abstracted (ChA¹) by default - HOWEVER in this
example, the chainId property on the Destination interface has been specified. The operation
should now be locked to the specified chain. Because functionCallName and functionCallData
exist, the Orchestrator can infer that this is a smart contract call and act accordingly.
{"id":420,"jsonrpc":"2.0","result":[{"name":"Inscribe with 1 USDC","description":"Call the Inscribe function with 1 USDC on Polygon","transactions":[{"to":"0x...","chainId":137,"calldata":"0x0...","value":0},{"to":"0x...","chainId":137,"calldata":"0x...","value":0}]}]}
Security Considerations
Orchestrator reputation
The ability for anyone to build an Orchestrator inherently brings the opportunity for code errors and therefore a degraded service. Orchestrators may also be abandoned over time. A reputation score should be leveraged by the Orchestrator to determine if the Orchestrator is fit for purpose. This should be up to the requesting system or wallet to determine.
Orchestrator producing dishonest solutions
An Orchestrator may return transactions as part of a solution that are wrong or attempt to take more than what was asked of it. Where possible, the Orchestrator should validate returned transaction address destinations and any other data.
Orchestrator personality variations
Whilst not a security consideration per-se, some Orchestrators may gravitate towards their own business targets which may skew the outcome of Orchestrator solutions. The systems or wallets requesting solutions from Orchestrators should be mindful of this unless it is intended.