### Overview
The onchain infrastructure that powers Porto consists of the following contracts:
#### Porto Account
The Porto Account is a keychain that holds user funds, enforces permissions via [Keys](/contracts/account#keys), manages nonces to prevent replay attacks, and enables secure executions from the account.
#### Orchestrator
The Orchestrator is a [privileged](/contracts/account#orchestrator-integration) contract that facilitates trustless interactions between the relay and the account.
#### Simulator
The Simulator is a peripheral utility that enables offchain services to obtain accurate gas estimates for intents in a single RPC call.
#### Settlement System
The Settlement System enables cross-chain transaction finality through native merkle signature verification. It provides trustless settlement mechanisms for multi-chain intents with interop features including fund transfers, merkle signature verification, and funder interface integration for cross-chain execution.
## Interoperability
The Porto Stack provides native cross-chain interoperability through a comprehensive settlement system, enabling trustless multi-chain operations and secure token escrow capabilities.
### Overview
Porto's interoperability layer consists of three main components that work together to facilitate cross-chain transactions:
#### Settlement System
The settlement system enables cross-chain transaction finality through merkle signature verification and messaging protocols. Porto supports multiple settlement mechanisms:
* **SimpleSettler**: Signature-based settlement for trusted environments
* **LayerZeroSettler**: Cross-chain messaging using LayerZero v2 protocol for decentralized settlement
#### Escrow
The escrow system provides secure token holding with configurable settlement conditions and automatic refunds. Key features include:
* Multi-token support with native and ERC20 tokens
* Configurable refund amounts and deadlines
* Integration with any settlement provider
* Atomic settlement verification
#### Cross-Chain Execution
The Porto Account includes native support for multi-chain operations:
* **Multichain Nonces**: Special nonce prefix (`0xc1d0`) enables signature replay across chains
* **Merkle Signature Verification**: Built-in support for merkle proofs in multi-chain executions
* **Cross-Chain Fund Transfers**: Secure token transfers with strictly ordered addresses
### Funder Interface
The Funder interface enables cross-chain execution funding, allowing relayers and third parties to sponsor transactions across multiple chains.
#### Interface
```solidity
interface IFunder {
struct Transfer {
address token;
uint256 amount;
}
function fund(
bytes32 digest,
Transfer[] memory transfers,
bytes memory funderSignature
) external;
}
```
#### SimpleFunder Implementation
Porto provides a reference implementation that demonstrates:
* **Pull-based funding model**: Authorized relayers can pull funds on-demand
* **Signature verification**: Ensures only authorized funding requests are processed
* **Risk management**: Separate controls for token and native currency withdrawals
* **Multi-chain support**: Coordinates funding across different chains for interop operations
The SimpleFunder serves as both a production-ready contract and a template for custom funder implementations tailored to specific use cases.
### Architecture Benefits
#### Trustless Operations
* No dependency on centralized bridges
* Cryptographic verification of cross-chain messages
* Automatic fallback mechanisms with time-based refunds
#### Flexibility
* Pluggable settlement providers
* Support for multiple messaging protocols
* Customizable escrow conditions
#### Security
* Atomic settlement guarantees
* Protected refund mechanisms
* Signature verification at every step
### Use Cases
#### Cross-Chain DeFi
Execute swaps and provide liquidity across multiple chains with guaranteed settlement or automatic refunds.
#### Multi-Chain NFT Purchases
Purchase NFTs on one chain using tokens from another, with escrow protection ensuring delivery.
#### Cross-Chain Subscriptions
Manage recurring payments across different chains with automatic settlement verification.
#### Interchain Governance
Participate in governance across multiple chains with unified signature schemes.
### Getting Started
Explore the detailed documentation for each component:
* [Escrow System](/contracts/interop/escrow) - Learn about secure token escrow with cross-chain settlement
* [Settlement Providers](/contracts/interop/settlement) - Understand different settlement mechanisms and their trade-offs
For implementation examples and integration guides, refer to the test suite in the [account repository](https://github.com/ithacaxyz/account).
## Orchestrator
The Orchestrator is a privileged contract that facilitates trustless interactions between the relay and the account.
### Concepts
#### Intents
The orchestrator accepts executions in the form of an intent.
An `intent` struct contains all the relevant data that allows a 3rd party like the relay to make an execution on behalf of the user, and get paid for it.
The intent has to be signed by one of the [Keys](/contracts/account#keys) authorized in the user's account. Optionally, the intent can use a `paymaster` to pay on behalf of the user, in which case the intent also needs to be signed by the paymaster.
```solidity
struct Intent {
////////////////////////////////////////////////////////////////////////
// EIP-712 Fields
////////////////////////////////////////////////////////////////////////
/// @dev The user's address.
address eoa;
/// @dev An encoded array of calls, using ERC7579 batch execution encoding.
/// `abi.encode(calls)`, where `calls` is of type `Call[]`.
/// This allows for more efficient safe forwarding to the EOA.
bytes executionData;
/// @dev Per delegated EOA.
/// This nonce is a 4337-style 2D nonce with some specializations:
/// - Upper 192 bits are used for the `seqKey` (sequence key).
/// The upper 16 bits of the `seqKey` is `MULTICHAIN_NONCE_PREFIX`,
/// then the Intent EIP712 hash will exclude the chain ID.
/// - Lower 64 bits are used for the sequential nonce corresponding to the `seqKey`.
uint256 nonce;
/// @dev The account paying the payment token.
/// If this is `address(0)`, it defaults to the `eoa`.
address payer;
/// @dev The ERC20 or native token used to pay for gas.
address paymentToken;
/// @dev The maximum amount of the token to pay.
uint256 paymentMaxAmount;
/// @dev The combined gas limit for payment, verification, and calling the EOA.
uint256 combinedGas;
/// @dev Optional array of encoded SignedCalls that will be verified and executed
/// before the validation of the overall Intent.
/// A PreCall will NOT have its gas limit or payment applied.
/// The overall Intent's gas limit and payment will be applied, encompassing all its PreCalls.
/// The execution of a PreCall will check and increment the nonce in the PreCall.
/// If at any point, any PreCall cannot be verified to be correct, or fails in execution,
/// the overall Intent will revert before validation, and execute will return a non-zero error.
bytes[] encodedPreCalls;
/// @dev Only relevant for multi chain intents.
/// There should not be any duplicate token addresses. Use address(0) for native token.
/// If native token is used, the first transfer should be the native token transfer.
/// If encodedFundTransfers is not empty, then the intent is considered the output intent.
bytes[] encodedFundTransfers;
/// @dev The settler address.
address settler;
/// @dev The expiry timestamp for the intent. The intent is invalid after this timestamp.
/// If expiry timestamp is set to 0, then expiry is considered to be infinite.
uint256 expiry;
////////////////////////////////////////////////////////////////////////
// Additional Fields (Not included in EIP-712)
////////////////////////////////////////////////////////////////////////
/// @dev Whether the intent should use the multichain mode - i.e verify with merkle sigs
/// and send the cross chain message.
bool isMultichain;
/// @dev The funder address.
address funder;
/// @dev The funder signature.
bytes funderSignature;
/// @dev The settler context data to be passed to the settler.
bytes settlerContext;
/// @dev The actual payment amount, requested by the filler. MUST be less than or equal to `paymentMaxAmount`
uint256 paymentAmount;
/// @dev The payment recipient for the ERC20 token.
/// Excluded from signature. The filler can replace this with their own address.
/// This enables multiple fillers, allowing for competitive filling, better uptime.
address paymentRecipient;
/// @dev The wrapped signature.
/// `abi.encodePacked(innerSignature, keyHash, prehash)`.
bytes signature;
/// @dev Optional payment signature to be passed into the `compensate` function
/// on the `payer`. This signature is NOT included in the EIP712 signature.
bytes paymentSignature;
/// @dev Optional. If non-zero, the EOA must use `supportedAccountImplementation`.
/// Otherwise, if left as `address(0)`, any EOA implementation will be supported.
/// This field is NOT included in the EIP712 signature.
address supportedAccountImplementation;
}
```
Let's go through each of these fields, to discuss the features enabled by intents.
##### Gas Abstraction
One of the most powerful use cases of executing through intents is that the Relay can abstract gas for users and get compensated in any token the user holds.
We've removed the need for gas refunds. Instead, Relay uses the `pay` function on the account to request payment in two almost identical tranches:
1. **paymentAmount** (after intent validation):
* If successful, the account's **nonce is incremented** and will pay for the transaction, even if the call bundle fails during execution.
Here's how the flow works:
1. The user sends their calls to the relay.
2. The relay analyzes the calls and determines the amount they want to be paid, in the `paymentToken` specified in the intent.
3. The relay simulates this operation and runs sophisticated griefing checks to assess risk, and returns a `paymentAmount` that the operation would cost.
4. The relay can also set the `supportedAccountImplementation` field in the intent when sending it onchain, to reduce the risk of the user frontrunning them by upgrading their account.
:::warning
Beyond this, the contracts do not provide native griefing protection. It is up to the relay to simulate the call and evaluate the risk associated with each intent.
Relay may choose to:
* Only support accounts that follow ERC-4337 validation rules.
:::
Our recommendations:
1. Relay should build sophisticated offchain griefing defenses, such as reputation systems and risk premiums for new users and implementations that have custom validation paths.
2. Relayers that are less sophisticated can opt to rely on the `supportedAccountImplementation` check provided by the orchestrator.
##### Paymasters
On the topic of payments, DApps might want to sponsor payments for their users.
This means that instead of the payment to the relay being collected from the user's porto account, it can be collected from any third-party contract that implements the [pay()](/contracts/account#pay) function.
To sponsor an intent, you just need to set the `payer` field to the paymaster contract's address.
:::note
If left empty, the payer field is substituted with the intent's eoa address.
This is done for a gas optimization, related to calldata compression.
:::
We've allowed porto accounts to act as paymasters for other porto accounts. This makes it extremely simple to spin up paymasters to sponsor gas for your users.
:::note
Paymasters should check that account implementations they sponsor gas for have a nonce implementation that invalidates nonces. Otherwise, an account could replay a paymaster signature infinitely many times to drain a paymaster.
:::
##### Execution
The intent contains the following execution information:
###### nonce
Same as the nonce mechanic detailed [here](/contracts/account#nonce-management) in the account.
All nonces are stored and incremented in the storage of the account. The orchestrator just has special privilege to access these storage slots.
###### executionData
Since all the data like nonce and signature is added in their corresponding fields in the intent.
The executionData requires no additional `opData` and uses the `0x0100...` single batch encoding described [here](/contracts/account#modes).
#### PreCalls
PreCalls are an optional sequence of operations that can be embedded within an Intent. They are executed *after* account initialization, but *before* the main Intent's signature is validated and before any of payment tranches are processed by the Orchestrator.
This makes `preCalls` particularly suited to perform key operations for the user, before the main intent is validated.
Although we don't enforce any onchain constraints about the contents of a preCall, it is recommended that relays only allow the following calls to be added as preCalls:
* Authorizing a key (`Account.authorize`)
* Revoking a key (`Account.revoke`)
* Setting call permissions on a key (`Account.setCanExecute`)
* Setting spend limits on a key (`Account.setSpendLimit`)
* Removing spend limits on keys (`Account.removeSpendLimit`)
* Upgrading the account (`Account.upgradeProxyAccount`)
This restriction is recommended because `preCalls` do not have their own payment or gas limits. Although the cost of `preCalls` is expected to be included in the main intent's payment figures, they are executed *before* the main payment is processed.
Therefore, allowing arbitrary calls within `preCalls` would increase the Relay's vulnerability to griefing attacks.
**The `SignedCall` Struct**
PreCalls are added to the `Intent.encodedPreCalls` field as an array of ABI-encoded `SignedCall` structs.
```solidity
struct SignedCall {
/// @dev The user's address.
/// This can be set to `address(0)`, which allows it to be
/// coalesced to the parent Intent's EOA.
address eoa;
/// @dev An encoded array of calls, using ERC7579 batch execution encoding.
/// `abi.encode(calls)`, where `calls` is of type `Call[]`.
bytes executionData;
/// @dev Per delegated EOA. Same logic as the `nonce` in Intent.
uint256 nonce;
/// @dev The wrapped signature.
bytes signature;
}
```
* `eoa`: The target EOA for this PreCall. If set to `address(0)`, it defaults to the `eoa` of the parent Intent. As mentioned, this resolved EOA must match the parent Intent's `eoa`.
* `executionData`: The actual operations (calls) to be performed by this PreCall. Execution Data can be calculated as
```solidity
bytes memory executionData = abi.encode(calls)
```
* `nonce`: A dedicated nonce for this PreCall, specific to the `eoa`. It follows the same 2D nonce scheme as described [here](/contracts/account#nonce-management)\
It is recommended to always use a separate sequence key for PreCalls.
* `signature`: The signature authorizing this specific `SignedCall`, typically created using a key already authorized on the `eoa`.
#### Flow Diagram
### Endpoints
#### Core Execution
These are the main entry points for submitting and executing Intents.
##### `execute` (Single Intent)
```solidity
function execute(bytes calldata encodedIntent) public payable virtual nonReentrant returns (bytes4 err)
```
* **Description:** Executes a single encoded Intent. An Intent is a structured set of operations to be performed on behalf of an EOA, potentially including calls to other contracts and gas payment details. This function handles the entire lifecycle: payment, verification, and execution of the Intent.
* **Usage:**
* `encodedIntent`: ABI-encoded `Intent` struct. The `Intent` struct includes fields like `eoa` (the target EOA), `executionData` (encoded calls to perform), `nonce`, `payer`, `paymentToken`, `paymentMaxAmount`s, `combinedGas`, and `encodedPreCalls`.
* The function is `payable` to receive gas payments if the EOA or a designated payer is covering transaction costs with the native token.
* Returns `err`: A `bytes4` error selector. Non-zero if there's an error during payment, verification, or execution. A zero value indicates overall success of the Intent processing through the Orchestrator's flow.
* Emits an `IntentExecuted` event.
##### `execute` (Batch Intents)
```solidity
function execute(bytes[] calldata encodedIntents) public payable virtual nonReentrant returns (bytes4[] memory errs)
```
* **Description:** Executes an array of encoded Intents atomically.
* **Usage:**
* `encodedIntents`: An array of ABI-encoded `Intent` structs.
* Returns `errs`: An array of `bytes4` error selectors, one for each Intent in the batch.
* Each Intent is processed sequentially.
***
#### Simulation
##### `simulateExecute`
```solidity
function simulateExecute(bool isStateOverride, uint256 combinedGasOverride, bytes calldata encodedIntent) external payable returns (uint256 gasUsed)
```
* **Description:** Simulates the execution of an Intent. This is primarily used for off-chain gas estimation and validation without actually changing state or consuming real funds (unless `isStateOverride` is true and specific conditions are met for on-chain simulation with logs).
* Signature verification steps are still performed for accurate gas measurement but will effectively pass.
* Errors during simulation are bubbled up.
* **Usage:**
* `isStateOverride`:
* If `false` (typical off-chain simulation): The function will *always* revert. If successful, it reverts with `SimulationPassed(uint256 gUsed)`. If failed, it reverts with the actual error from the execution flow.
* If `true` (for on-chain simulation that generates logs, e.g., `eth_simulateV1`): The function will *not* revert on success if `msg.sender.balance == type(uint256).max` (proving a state override environment). Returns `gasUsed`. Otherwise, reverts with `StateOverrideError`.
* `combinedGasOverride`: Allows overriding the `combinedGas` specified in the `Intent` for simulation purposes.
* `encodedIntent`: The ABI-encoded `Intent` struct to simulate.
* Returns `gasUsed`: The amount of gas consumed by the execution if `isStateOverride` is true and conditions are met. Otherwise, relies on revert data.
***
#### Helpers
##### `accountImplementationOf`
```solidity
function accountImplementationOf(address eoa) public view virtual returns (address result)
```
* **Description:** Returns the implementation address of an EOA if it's an EIP-7702 proxy. It checks the EOA's bytecode to determine if it's a valid EIP-7702 proxy and then retrieves its current implementation.
#### Events
##### `IntentExecuted`
```solidity
event IntentExecuted(address indexed eoa, uint256 indexed nonce, bool incremented, bytes4 err);
```
* **Description:** Emitted when an Intent (including PreCalls that use nonces) is processed via the `_execute` flow.
* `eoa`: The target EOA of the Intent.
* `nonce`: The nonce of the Intent.
* `incremented`: Boolean indicating if the nonce's sequence was successfully incremented on the account. This generally implies successful verification and pre-payment.
* `err`: The `bytes4` error selector resulting from the Intent's processing. `0` indicates no error *from the Orchestrator's perspective for that phase*. A non-zero `err` along with `incremented == true` means the verification and pre-payment were likely okay, but the main execution or post-payment failed. If `incremented == false`, an earlier stage (like verification) failed.
***
## Security
⚠️ Contracts have been audited by Riley H, Kaden & Milotruck.
### Bug Bounty
We're opening up a live bug bounty program to encourage responsible security research and battle-test our contracts in the real world. We’re inviting white hat hackers, tinkerers, and security researchers to probe our account implementation.
***
#### 🪙 Bounty Rewards
| Severity | Reward | Examples |
| -------- | ------------- | ------------------------------------------------------------------- |
| Critical | Up to 5 ETH | Successfully drain one of the live accounts using any vulnerability |
| High | Up to 2.5 ETH | Prevent a user from accessing funds |
| Medium | Discretionary | - |
-The exact severity of bugs is determined from a combination of security impact, and the likelihood of this attack occuring, at the discretion of the Ithaca team.
-We currently don’t have any open bounties for low & info bugs, or gas optimizations. But if you find one, feel free to open an issue in [the account repo](https://github.com/ithacaxyz/account), for good karma.
#### Scope
The current bug bounty covers the smart contracts in the [account repo with the version tag at v0.5.4 or above](https://github.com/ithacaxyz/account/releases/tag/v0.5.4). Previous releases and other code are considered out-of-scope.
#### Criteria for Bug Bounty eligibility
1. The bug must be novel. It must not be a previously known issue to us (github issue, or surfaced by a previous audit), or revealed/exploited via an on-chain transaction.
2. Security vulnerability reports must be sent to [`security@ithaca.xyz`](mailto\:security@ithaca.xyz) to be eligible for a bounty.
3. Public disclosure of the bug must be after written approval by the Ithaca team.
## Simulator
The Simulator is a versatile utility designed to help offchain services and Relays obtain accurate gas estimates for intents efficiently.
It functions like an advanced multicall, enabling sophisticated operations such as searching for optimal `combinedGas` values, generating custom execution traces, and providing clearer error messages for transaction reverts.
It uses the primitive [simulateExecute](/contracts/orchestrator#simulation) function exposed by the orchestrator, and adds custom logic on top of it.
Developers have the flexibility to utilize the default `Simulator` provided by Ithaca or deploy a custom one tailored to their specific needs.
Simulators operate without any special onchain privileges and any simulator can be used with any Orchestrator instance.
### State Override Convention
Certain simulation modes, especially those designed to generate detailed logs for tools like `eth_simulateV1`, depend on specific state overrides to operate correctly.
A general principle for enabling special simulation behaviors, such as skipping signature verification checks, involves checking the native token balance of `msg.sender`. If this balance is `type(uint256).max`, it signals a trusted simulation environment where certain validation steps can be relaxed.
* **For `simulateV1Logs`:**
* The [simulateExecute](/contracts/orchestrator#simulation) function, when invoked with `isStateOverride = true`, requires its direct caller (`msg.sender`) to possess a native token balance equal to `type(uint256).max`.
* When `simulateV1Logs` calls the Orchestrator, the Simulator contract acts as the `msg.sender`.
* **Crucially, for `simulateV1Logs` to successfully produce a non-reverting trace, the Simulator contract's native token balance must be externally set to `type(uint256).max` *before* calling `simulateV1Logs`.**
* Failure to meet this condition will typically cause the Orchestrator to revert with `StateOverrideError()`, which is then propagated by the Simulator.
:::info
**Paymaster Considerations:**
If an Intent utilizes a paymaster, the simulation might also need to bypass paymaster signature verification.
In this scenario, the Orchestrator is the `msg.sender` to the paymaster contract. Consequently, the Orchestrator's balance must also be set to `type(uint256).max` to facilitate this.
Developers creating paymasters should ensure their contracts can skip signature verification when called by an entity with a maximum balance (signifying a trusted simulation context) to maintain compatibility with the Simulator.
:::
### Endpoints
#### `simulateGasUsed`
* **Signature:**
```solidity
function simulateGasUsed(
address oc,
bool overrideCombinedGas,
bytes calldata encodedIntent
) public payable virtual returns (uint256 gasUsed);
```
* **Description:**
This function simulates the gas usage for a single encoded Intent. It calls the `simulateExecute` function on the specified Orchestrator contract with `isStateOverride` set to `false`.
If the underlying simulation within the Orchestrator fails, this function will revert.
* **Usage:**
* **Parameters:**
* `oc`: Address of the Orchestrator contract.
* `overrideCombinedGas`: Boolean indicating how `combinedGas` is handled:
* If `true`: The `combinedGas` field in the `encodedIntent` is overridden to `type(uint256).max` for the simulation. This helps determine the raw gas cost without constraints from the Intent's specified gas limit.
* If `false`: The `combinedGas` value from the `encodedIntent` is respected.
* `encodedIntent`: The ABI-encoded [Intent](/contracts/orchestrator#intents)
* **Returns:**
* `gasUsed`: The amount of gas consumed by the simulated execution. This is extracted from the `SimulationPassed(uint256 gasUsed)` revert data from the Orchestrator.
* **Reverts:**
* If the simulation fails (e.g., due to an error in Intent logic or insufficient gas if `overrideCombinedGas` is `false`), it reverts with the Orchestrator's error.
#### `simulateCombinedGas`
* **Signature:**
```solidity
function simulateCombinedGas(
address oc,
bool isPrePayment,
uint8 paymentPerGasPrecision,
uint256 paymentPerGas,
uint256 combinedGasIncrement,
bytes calldata encodedIntent
) public payable virtual returns (uint256 gasUsed, uint256 combinedGas);
```
* **Description:**
This function simulates an Intent's execution to iteratively find the minimum `combinedGas` value required for it to pass successfully. The process involves two main stages:
1. **Baseline Simulation:**
* Performs a primary simulation run by calling the Orchestrator's `simulateExecute` function.
* `isStateOverride` is set to `false`.
* `combinedGasOverride` is set to `type(uint256).max`.
* This initial run establishes a baseline `gasUsed` for the Intent.
2. **Iterative Search:**
* Iteratively increases the `combinedGas` field in a copy of the Intent.
* Starts from `baseline_gasUsed + original_Intent.combinedGas`.
* Associated payment amounts (`prePaymentAmount`, `totalPaymentAmount`) are adjusted accordingly in each iteration.
* Continues until a call to the Orchestrator's `simulateExecute` (with `isStateOverride = false` and no `combinedGasOverride`) succeeds by reverting with `SimulationPassed`.
* **Usage:**
* **Parameters:**
* `oc`: Address of the Orchestrator contract.
* `isPrePayment`: Boolean indicating how payment is handled:
* If `true`: The gas-based payment is added to `prePaymentAmount` (and `totalPaymentAmount`).
* If `false`: The gas-based payment is added only to `totalPaymentAmount`.
* `paymentPerGasPrecision`: Defines precision for `paymentPerGas`.
* Example: If `paymentPerGas` is in Gwei, `paymentToken` has 18 decimals, and you want `paymentPerGas` to represent units with 9 decimal places of precision, this field would be `9`.
* Payment amount is calculated as: `gas * paymentPerGas / (10 ** paymentPerGasPrecision)`.
* `paymentPerGas`: Amount of `paymentToken` added to Intent's payment fields per unit of gas.
* `combinedGasIncrement`: Basis points value for `combinedGas` increment step (e.g., `100` for 1%, `10000` for 100%).
* `combinedGas` is updated in each iteration by: `current_combinedGas * combinedGasIncrement / 10000`
* Ensure this value is greater than `10000` (e.g., `10100` for a 1% increment) to guarantee `combinedGas` increases.
* `encodedIntent`: The ABI-encoded [Intent](/contracts/orchestrator#intents)
* **Returns:**
* `gasUsed`: Gas consumed in the first successful simulation identified during the iterative search (extracted from `SimulationPassed` revert data).
* `combinedGas`: The `combinedGas` value from the Intent that resulted in the first successful simulation.
* **Reverts:**
* If the initial baseline simulation (with maximum `combinedGas`) fails.
* If a `PaymentError` is encountered during the iterative search (increasing `combinedGas` and payments won't resolve this).
#### `simulateV1Logs`
* **Signature:**
```solidity
function simulateV1Logs(
address oc,
bool isPrePayment,
uint8 paymentPerGasPrecision,
uint256 paymentPerGas,
uint256 combinedGasIncrement,
uint256 combinedGasVerificationOffset,
bytes calldata encodedIntent
) public payable virtual returns (uint256 gasUsed, uint256 combinedGas);
```
* **Description:**
* Extends the functionality of `simulateCombinedGas`.
* After determining `combinedGas` and `gasUsed` iteratively, it introduces a `combinedGasVerificationOffset`.
* A final simulation run is performed by calling `simulateExecute` on the Orchestrator with `isStateOverride` set to `true`.
* Goal: Generate a successful, non-reverting simulation trace compatible with tools like `eth_simulateV1` for detailed execution log retrieval.
* Payment amounts in the Intent are updated based on the determined `combinedGas` (including the offset).
* **Usage:**
* State override requirements are detailed [here](#state-override-convention).
* **Parameters:**
* `combinedGasVerificationOffset`: A static gas amount added to the `combinedGas` value found by the iterative search. This helps account for minor gas variations (e.g., with P256 signature schemes).
* All other parameters function identically to those in [`simulateCombinedGas`](#simulatecombinedgas).
* **Returns:**
* `gasUsed`: Gas consumed during the final verification run.
* `combinedGas`: Final `combinedGas` used in the verification run.
* **Reverts:**
* If any underlying simulation step fails.
* If the necessary state override for the `Simulator` contract's balance is not in place, the final call to Orchestrator will likely revert with `StateOverrideError()`.
## `health`
Health check for the Relay. Returns the version of the server.
### Request
```ts
type Request = {
method: 'health',
}
```
### Response
```ts
type Response = {
status: string;
version: string;
}
```
### Example
```sh
cast rpc --rpc-url https://rpc.porto.sh health
```
```json
{
"status": "rpc ok",
"version": "21.0.2 (93ade40)"
}
```
## Overview
The Relay uses JSON-RPC 2.0 to facilitate communication between the Porto SDK and the blockchain. The RPC is responsible for building, simulating and sending intents to the contracts on behalf of a user.
Execution is paid for in one of the fee tokens accepted by the RPC on a given network. You can get the supported fee tokens for a chain by querying [`wallet_getCapabilities`].
:::note
We'd love to hear your feedback. Report any issues or feature suggestions [on the issue tracker](https://github.com/ithacaxyz/relay/issues).
:::
### Endpoints
#### Chain support
The Relay exposes a unified JSON-RPC endpoint: `https://rpc.porto.sh`.
You can query supported chains, contracts, and fee tokens via `wallet_getCapabilities`.
Example:
```sh
cast rpc --rpc-url https://rpc.porto.sh wallet_getCapabilities
```
**Supported Networks:**
| Network | Chain ID | Fee Token Support | Interop Support |
| -------------------- | -------- | ----------------- | ---------------- |
| **Base** | 8453 | ETH, USDC, USDT | ETH, USDC, USDT |
| **Optimism** | 10 | ETH, USDC, USDT | ETH, USDC, USDT |
| **Arbitrum** | 42161 | ETH, USDC, USDT | ETH, USDC, USDT |
| **Ethereum** | 1 | ETH, USDC, USDT | ETH, USDC, USDT |
| **Celo** | 42220 | CELO, USDC, USDT | USDC, USDT |
| **BNB Chain** | 56 | BNB, USDT | No |
| **Polygon** | 137 | POL, USDC, USDT | USDC, USDT |
| **Katana** | 747474 | ETH | No |
| **Base Sepolia** | 84532 | tETH, EXP1, EXP2 | tETH, EXP1, EXP2 |
| **Optimism Sepolia** | 11155420 | tETH, EXP1, EXP2 | tETH, EXP1, EXP2 |
| **Arbitrum Sepolia** | 421614 | tETH | No |
* **Fee Token Support**: Tokens accepted to pay execution fees on that chain.
* **Interop Support**: Cross-chain supported tokens (from the Relay interop dashboard).
### Local Development
To run the Relay locally, you can use the following command:
```sh
curl -sSL s.porto.sh/docker | docker compose -f - up -d
```
Once complete, the Relay will be available at `http://localhost:9200`:
```sh
cast rpc --rpc-url http://localhost:9200 wallet_getCapabilities "[31337]"
```
::::tip
If you have [OrbStack](https://orbstack.dev/) installed, you can also query the Relay at `https://relay.local`.
:::note
Production RPC URL: `https://rpc.porto.sh` (JSON-RPC 2.0 over HTTP). All examples on this page target this endpoint unless stated otherwise.
:::
::::
### Testnet Faucet (dev)
Need test funds for Dialog/Playground flows? Use the development faucet RPC.
See: [`wallet_addFaucetFunds`](/relay/wallet_addFaucetFunds)
### Account management
Accounts are managed through the RPC using the following methods:
#### Account upgrade
Upgrading an existing EOA is split into two steps:
* [`wallet_prepareUpgradeAccount`]: Prepares an account for upgrade.
* [`wallet_upgradeAccount`]: Upgrades the account on chain.
#### Account information
* [`wallet_getKeys`]: Get all keys attached to an account.
For more details on how accounts work, see the [Account documentation](#TODO).
### Intent execution
Intents are executed in two steps. First, [`wallet_prepareCalls`] is called to simulate the call and estimate fees. A context is returned with the built intent, which also includes a quote signed by the Relay, which expires after some time. The built intent is verified and signed by the user's key, and the quote plus the signed intent is sent to the Relay with [`wallet_sendPreparedCalls`].
The Relay will validate that the quote is still valid, that the intent was signed, and will then include it in a transaction on the destination chain. [`wallet_sendPreparedCalls`] returns an opaque identifier that is the equivalent of a transaction hash. To get the status of an intent, plus any transaction receipts for the intent, you must use [`wallet_getCallsStatus`]. For historical activity across bundles, paginate with [`wallet_getCallsHistory`].
[`wallet_getCapabilities`]: /relay/wallet_getCapabilities
[`wallet_prepareUpgradeAccount`]: /relay/wallet_prepareUpgradeAccount
[`wallet_upgradeAccount`]: /relay/wallet_upgradeAccount
[`wallet_getKeys`]: /relay/wallet_getKeys
[`wallet_prepareCalls`]: /relay/wallet_prepareCalls
[`wallet_sendPreparedCalls`]: /relay/wallet_sendPreparedCalls
[`wallet_getCallsStatus`]: /relay/wallet_getCallsStatus
[`wallet_getCallsHistory`]: /relay/wallet_getCallsHistory
## `wallet_addFaucetFunds`
Development-only JSON-RPC to request faucet funds on supported testnets. Intended for local/testing flows and not for production usage.
* Availability: testnets only (subject to rate limits)
* Supported networks: Base Sepolia (`84532`), Optimism Sepolia (`11155420`)
### Request
```ts
import { Address } from 'viem'
type Request = {
method: 'wallet_addFaucetFunds',
params: [{
address: Address
chainId: number
/** Token to mint (required) */
tokenAddress: Address
/** Amount to mint (defaults to 25) */
value?: number
}]
}
```
### Response
```ts
import { Hash } from 'viem'
type Response = {
/** Mint transaction hash */
id: Hash
}
```
### Examples
```sh
cast rpc --rpc-url https://rpc.porto.sh \
wallet_addFaucetFunds '[{"address":"0xYourAddress","chainId":84532,"tokenAddress":"0x3a9b126bf65c518f1e02602bd77bd1288147f94c","value":25}]' --raw
```
```sh
cast rpc --rpc-url https://rpc.porto.sh \
wallet_addFaucetFunds '[{"address":"0xYourAddress","chainId":11155420,"tokenAddress":"0x6795f10304557a454b94a5c04e9217677cc9b598"}]' --raw
```
### Notes
* Development-only; expect rate limiting per address and IP.
* Backed by the Service faucet. See implementation reference in `apps/service/src/routes/faucet.ts`.
## `wallet_getAssets`
Get assets for an account across supported chains.
Implements [EIP-7811](https://eips.ethereum.org/EIPS/eip-7811) asset discovery standard.
### Request
```ts
type Request = {
method: 'wallet_getAssets',
params: [{
/** Account address */
account: `0x${string}`,
/** Optional filter for specific assets */
assetFilter?: {
[chainId: `0x${string}`]: {
address: `0x${string}` | 'native',
type: 'native' | 'erc20' | 'erc721' | string,
}[],
},
/** Optional filter for asset types */
assetTypeFilter?: ('native' | 'erc20' | 'erc721' | string)[],
/** Optional filter for specific chains */
chainFilter?: `0x${string}`[],
}],
}
```
### Response
```ts
type Response = {
[chainId: `0x${string}`]: {
address: `0x${string}` | 'native',
balance: bigint,
metadata: {
decimals: number,
name: string,
symbol: string,
} | null,
type: 'native' | 'erc20' | 'erc721' | string,
}[]
}
```
### Example
```sh
cast rpc --rpc-url https://rpc.porto.sh wallet_getAssets '[{"account": "0x1234567890123456789012345678901234567890"}]' --raw
```
```json
{
"0x2105": [
{
"address": "native",
"balance": "0x1bc16d674ec80000",
"metadata": {
"decimals": 18,
"name": "Ethereum",
"symbol": "ETH"
},
"type": "native"
},
{
"address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
"balance": "0xf4240",
"metadata": {
"decimals": 6,
"name": "USD Coin",
"symbol": "USDC"
},
"type": "erc20"
}
]
}
```
## `wallet_getCallsHistory`
Retrieve historical call bundles for an account. Results are returned in reverse chronological order by default.
Use this method to render activity feeds, audit execution history, or inspect which bundles were signed with a given key. For the current status of a specific bundle, prefer [`wallet_getCallsStatus`].
### Request
```ts
type Request = {
method: 'wallet_getCallsHistory'
params: [{
/** Address to fetch call bundles for. */
address: `0x${string}`
/** Index to start from (cursor). Defaults to 0 for ascending and latest index for descending. */
index?: number
/** Maximum number of bundles to return. */
limit: number
/** Sort direction. Use 'desc' for most recent first. */
sort: 'asc' | 'desc'
}]
}
```
### Response
```ts
type Response = {
/** Capabilities snapshot recorded for the bundle. */
capabilities: {
assetDiffs?: AssetDiffs
feeTotals?: FeeTotals
quotes?: Quote[]
}
/** Bundle identifier. */
id: `0x${string}`
/** Index of the bundle within the account's history. */
index: number
/** Hash of the key that signed the bundle. */
keyHash: `0x${string}`
/** Status code for the bundle (see [`wallet_getCallsStatus`]). */
status: number
/** UNIX timestamp (seconds) when the bundle was included. */
timestamp: number
/** Transactions broadcast as part of the bundle. */
transactions: {
chainId: number
transactionHash: `0x${string}`
}[]
}[]
```
### Example
```sh
cast rpc --rpc-url https://rpc.porto.sh \
wallet_getCallsHistory '[{ "address": "0x391a3bFbd6555E74c771513b86A2e2a0356Ae1A0", "limit": 5, "sort": "desc" }]' --raw | jq
```
The `status` codes match the table documented on [`wallet_getCallsStatus`]. Use the `capabilities` object to render fee totals, asset diffs, and quotes captured at execution time.
See [`wallet_prepareCalls`](/relay/wallet_prepareCalls#response) for detailed capability schemas.
[`wallet_getCallsStatus`]: /relay/wallet_getCallsStatus
[`wallet_prepareCalls`]: /relay/wallet_prepareCalls
## `wallet_getCallsStatus`
Get the status of a call bundle. This method is modeled after [ERC-5792](https://eips.ethereum.org/EIPS/eip-5792), but with slight modifications to better suit a multi-chain wallet, namely `chainId` is not a property of the bundle itself, but of the receipts in the bundle.
If the bundle failed off-chain, or if it is pending, there may be no receipts.
### Status Codes
The purpose of the `status` field is to provide a short summary of the current status of the bundle.
It provides some off-chain context to the array of inner transaction `receipts`.
| Code | Description |
| ---- | --------------------------------------------------------------------------------------------------------------------------------- |
| 100 | Batch has been received by the wallet but has not completed execution onchain (pending) |
| 200 | Batch has been included onchain without reverts, receipts array contains info of all calls (confirmed) |
| 300 | Batch has not been included onchain and wallet will not retry (offchain failure) |
| 400 | Batch reverted **completely** and only changes related to gas charge may have been included onchain (chain rules failure) |
| 500 | Batch reverted **partially** and some changes related to batch calls may have been included onchain (partial chain rules failure) |
### Request
The parameter is a call bundle ID, as returned by e.g. [`wallet_sendPreparedCalls`].
```ts twoslash
import { Hex } from 'viem'
// ---cut---
type Request = {
method: 'wallet_getCallsStatus',
// the call bundle ID
params: [Hex],
}
```
### Response
```ts twoslash
import { Address, Hash, Hex } from 'viem'
// ---cut---
type Response = {
id: Hex,
status: number, // See "Status Codes"
receipts: {
logs: {
chainId: Hex,
address: Address,
data: Hex,
topics: Hex[],
}[],
status: Hex, // Hex 1 or 0 for success or failure, respectively
blockHash?: Hash,
blockNumber?: Hex,
gasUsed: Hex,
transactionHash: Hash,
}[],
/** Optional capabilities for cross-chain bundles */
capabilities?: {
/** Interop bundle status if this is an interop bundle */
interopStatus?: 'pending' | 'confirmed' | 'failed',
},
}
```
[`wallet_sendPreparedCalls`]: /relay/wallet_sendPreparedCalls
## `wallet_getCapabilities`
Gets supported [EIP-5792 Capabilities](https://eips.ethereum.org/EIPS/eip-5792#wallet_getcapabilities) of the Relay.
### Request
```ts twoslash
import { Hex } from 'viem'
// ---cut---
type Request = {
method: 'wallet_getCapabilities',
// the chain ids
params: Hex[],
}
```
### Response
A map of chain IDs to the capabilities supported by the Relay on those chains, which includes:
* contract addresses (`contracts`)
* fee configuration (`fees`), such as supported fee tokens (`fees.tokens`), and quote lifetimes (`fees.quoteConfig.ttl`)
```ts twoslash
import { Address, Hex } from 'viem'
// ---cut---
type Response = {
// the chain ID as hex
[chainId: Hex]: {
contracts: {
/** Account implementation address. */
accountImplementation: {
address: Address,
version?: string | null,
},
/** Account proxy address. */
accountProxy: {
address: Address,
version?: string | null,
},
/** Legacy account implementation addresses. */
legacyAccountImplementations: {
address: Address,
version?: string | null,
}[],
/** Legacy orchestrator addresses. */
legacyOrchestrators: {
address: Address,
version?: string | null,
}[],
/** Orchestrator address. */
orchestrator: {
address: Address,
version?: string | null,
},
/** Simulator address. */
simulator: {
address: Address,
version?: string | null,
},
/** Funder contract address. */
funder: {
address: Address,
version?: string | null,
},
/** Escrow contract address. */
escrow: {
address: Address,
version?: string | null,
},
},
fees: {
quoteConfig: {
/** Sets a constant rate for the price oracle. Used for testing. */
constantRate?: number | null,
/** Gas estimate configuration. */
gas: {
/** Extra buffer added to Intent gas estimates. */
intentBuffer: number,
/** Extra buffer added to transaction gas estimates. */
txBuffer: number,
},
/** The lifetime of a price rate. */
rateTtl: number,
/** The lifetime of a fee quote. */
ttl: number,
},
/** Fee recipient address. */
recipient: Address,
/** Tokens the fees can be paid in. */
tokens: {
address: Address,
decimals: number,
interop?: boolean,
/** The rate of the fee token to native tokens. */
nativeRate?: bigint,
symbol: string,
uid: string
}[],
},
}
}
```
### Example
```sh
cast rpc --rpc-url https://rpc.porto.sh wallet_getCapabilities '["0x14a34"]'
```
```json
{
"0x14a34": {
"contracts": {
"orchestrator": {
"address": "0xb447ba5a2fb841406cdac4585fdc28027d7ae503",
"version": "0.4.6"
},
"accountImplementation": {
"address": "0xc4e1dc6045234b913db45e8f51e770d6d12e42a1",
"version": "0.4.11"
},
"legacyOrchestrators": [],
"legacyAccountImplementations": [],
"accountProxy": {
"address": "0x5874f358359ee96d2b3520409018f1a6f59a2cdc",
"version": null
},
"simulator": {
"address": "0xcb80788813c39d90c48c2733b43b3e47e23a2d3f",
"version": null
},
"funder": {
"address": "0x665efbf4b831aac6b712471c6bbfdb11e1721b4f",
"version": null
},
"escrow": {
"address": "0x55626138525a47af075322aafe1df8f68993b11d",
"version": null
}
},
"fees": {
"recipient": "0x665efbf4b831aac6b712471c6bbfdb11e1721b4f",
"quoteConfig": {
"constantRate": null,
"gas": {
"intentBuffer": 20000,
"txBuffer": 10000
},
"ttl": 30,
"rateTtl": 300
},
"tokens": [
{
"uid": "exp2",
"address": "0x2ace05bcb50b49953aaa4c00f318db908a512d99",
"decimals": 18,
"feeToken": true,
"interop": true,
"symbol": "EXP2",
"nativeRate": "0xc536acbc02a4"
},
{
"uid": "exp1",
"address": "0x74e294e9d05bace256796040ca6dc0c47efb9fff",
"decimals": 18,
"feeToken": true,
"interop": true,
"symbol": "EXP",
"nativeRate": "0xc536acbc02a4"
},
{
"uid": "teth",
"address": "0x0000000000000000000000000000000000000000",
"decimals": 18,
"feeToken": true,
"interop": true,
"symbol": "ETH",
"nativeRate": "0xde0b6b3a7640000"
}
]
}
}
}
```
## `wallet_getKeys`
Get all keys for an account.
### Request
```ts twoslash
import { Address, Hex } from 'viem'
// ---cut---
type Request = {
method: 'wallet_getKeys',
params: [{
address: Address,
chainIds?: Hex[] | undefined,
}],
}
```
### Response
Each key associated with an account, along with the permissions set on the keys.
```ts twoslash
import { Address, Hash, Hex } from 'viem'
// ---cut---
type Response = {
[chainId: `0x${string}`]: {
// key hash
hash: Hash
key: {
expiry?: number
type: 'p256' | 'webauthnp256' | 'secp256k1'
role: 'admin' | 'normal' | 'session'
publicKey: Hex
}
permissions: (
| {
type: 'call'
selector: string
to: Address
}
| {
type: 'spend'
limit: number
period: 'minute' | 'hour' | 'day' | 'week' | 'month' | 'year'
// defaults to the native token (address zero)
token?: Address
}
)[]
}[]
}
```
import Keys from './snippets/keys.mdx'
import Fees from './snippets/fees.mdx'
import Selectors from './snippets/selectors.mdx'
## `wallet_prepareCalls`
Prepares a call bundle. The calls are simulated and a quote for executing the bundle by the server is provided. The quote lives for a certain amount of time, after which it expires.
:::tip
This method is intended to be used in conjunction with [`wallet_sendPreparedCalls`](/relay/wallet_sendPreparedCalls).
:::
### PreCalls
PreCalls are calls that are executed prior to pre-verification of the signature of the bundle, and before any payment is made.
Only certain types of calls are allowed in precalls:
* Authorizing a key (`Delegation.authorize`)
* Revoking a key (`Delegation.revoke`)
* Setting call permissions on a key (`Delegation.setCanExecute`)
* Setting spend limits on a key (`Delegation.setSpendLimit`)
* Removing spend limits on keys (`Delegation.removeSpendLimit`)
* Upgrading the delegation (`Delegation.upgradeProxyDelegation`)
PreCalls have their own signatures, and they must be signed with a key that is already attached to the account. The `from` and `key` fields can be omitted when building a precall (`precall: true`).
More details about preCalls can be found [in the Orchestrator documentation](/contracts/orchestrator#precalls)
#### Usage
```ts twoslash
import { Porto, Mode } from 'porto'
const porto = Porto.create({
mode: Mode.dialog(), // [!code focus]
})
```
#### Options
##### fallback
* **Type**: `Mode.Mode`
* **Default**: `Mode.relay()`
Mode to fall back to if the renderer does not support background operations (e.g. popups and web views).
##### host
* **Type**: `string`
* **Default**: `"https://id.porto.sh/dialog"`
URL of the dialog embed.
:::tip
While the application uses `Mode.dialog` to communicate to the Dialog, the dialog host (e.g. `https://id.porto.sh/dialog`) utilizes the `Mode.relay` mode to [communicate](#diagram-1) with the Relay.
:::
```ts twoslash
import { Porto, Mode } from 'porto'
const porto = Porto.create({
mode: Mode.dialog({
host: 'https://account.my-wallet.com/dialog', // [!code focus]
}),
})
```
##### renderer
* **Type**: `Dialog.Dialog`
* **Default**: `Dialog.iframe()`
The [renderer](/sdk/api/dialog) to use for the dialog. Available: [`Dialog.iframe`](/sdk/api/dialog#dialogiframe), [`Dialog.popup`](/sdk/api/dialog#dialogpopup)
```ts twoslash
import { Dialog, Porto, Mode } from 'porto'
const porto = Porto.create({
mode: Mode.dialog({
renderer: Dialog.popup(), // [!code focus]
}),
})
```
##### theme
* **Type**: `ThemeFragment | undefined`
A custom theme to apply to the dialog, where only `colorScheme` is required. See the [Theme](/sdk/api/theme) API for the list of styling properties that can be defined.
##### themeController
* **Type**: `Dialog.ThemeController | undefined`
A controller to manage the dialog theme, created by `Dialog.createThemeController()`. It can be used to change the theme of the dialog without reinitializing it, with `themeController.setTheme()`. This is intended for advanced use cases, `theme` should be sufficient in regular scenarios.
### Mode.reactNative
React Native mode is used to communicate with React Native applications. Setup assumes the use of [`expo`](https://expo.dev).
#### Usage
Install required dependencies:
```sh
pnpm expo install expo-web-browser expo-auth-session expo-crypto
```
Since we rely on a few Web Crypto APIs such as [`crypto.randomUUID`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID)
and [`crypto.getRandomValues`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues),
we need to polyfill those at the earliest possible stage. So in your entrypoint file (i.e., root `index.ts` / `index.native.ts`):
```ts
import 'porto/react-native/register'
// ...
```
Then import `Porto` anywhere in your application:
```ts twoslash
import { Porto, Mode } from 'porto'
const porto = Porto.create({
mode: Mode.reactNative(), // [!code focus]
})
```
or
```ts twoslash
import { Porto } from 'porto/react-native'
const porto = Porto.create()
```
##### Wagmi usage
```ts twoslash
import { baseSepolia } from 'porto/core/Chains'
import { Mode } from 'porto/react-native'
import { porto } from 'porto/wagmi'
import { Platform } from 'react-native'
import { createConfig, http } from 'wagmi'
const config = createConfig({
chains: [baseSepolia],
connectors: [
porto({
...Platform.select({
web: { mode: Mode.dialog() },
default: { mode: Mode.reactNative() },
})
})
],
multiInjectedProviderDiscovery: false,
transports: {
[baseSepolia.id]: http(),
},
})
```
:::tip
Use [`expo-sqlite/kv-store`](https://docs.expo.dev/versions/latest/sdk/sqlite) or [`@react-native-async-storage/async-storage`](https://react-native-async-storage.github.io/async-storage) for storage.
You can use it for both Wagmi's config and [`@tanstack/react-query`](https://tanstack.com/query/latest/docs/framework/react/plugins/createAsyncStoragePersister) persisted query client.
:::
#### Examples
* [Porto x `Mode.reactNative` (dialog) x Wagmi](https://github.com/ithacaxyz/porto/tree/main/examples/react-native)
* [Porto x `Mode.relay` (headless) x SIWE](https://github.com/ithacaxyz/porto/tree/main/examples/react-native-relay-mode)
#### Options
##### host
* **Type**: `string`
* **Default**: `"https://id.porto.sh/dialog"`
URL of the dialog embed.
##### redirectUri
* **Type**: `{ scheme: string, path?: string } | undefined`
Where to redirect the user after operations are completed.
Defaults to the result of [`AuthSession.makeRedirectUri({ path: '/' })`](https://docs.expo.dev/versions/latest/sdk/auth-session/#authsessionmakeredirecturioptions) if no value is passed.
##### requestOptions
* **Type**: `WebBrowser.AuthSessionOpenOptions | undefined`
Configure style, presentation and certain behaviors of the browser auth session for Android, iOS, and Web. [See details](https://docs.expo.dev/versions/latest/sdk/webbrowser/#authsessionopenoptions).
##### theme
* **Type**: `ThemeFragment | undefined`
A custom theme to apply to the dialog, where only `colorScheme` is required. See the [Theme](/sdk/api/theme) API for the list of styling properties that can be defined.
##### themeController
* **Type**: `Dialog.ThemeController | undefined`
A controller to manage the dialog theme, created by `Dialog.createThemeController()`. It can be used to change the theme of the dialog without reinitializing it, with `themeController.setTheme()`. This is intended for advanced use cases, `theme` should be sufficient in regular scenarios.
### Mode.relay
Interacts with the **Porto Relay** directly. Signing is performed via the SDK. Account management, chain interop, and transaction management is orchestrated on the Relay.
:::tip
The `Mode.relay` mode is used internally by the Porto Dialog (`id.porto.sh`). It is possible
for Wallet vendors to use `Mode.relay` to create their own Dialog.
:::
#### Diagram
In the diagram below, `Mode.relay` is utilized within the Porto Dialog (`id.porto.sh`) to communicate with the Relay.
#### Usage
```ts twoslash
import { Porto, Mode } from 'porto'
const porto = Porto.create({
mode: Mode.relay(), // [!code focus]
})
```
#### Caveats
* When you run `Mode.relay` the Passkey Host (WebAuthn Relying Party) becomes **your domain**, not `id.porto.sh`. Credentials created here cannot be asserted on other domains, which means **users cannot reuse their Porto account** created on `id.porto.sh`.
#### Options
##### keystoreHost
* **Type**: `string`
* **Default**: `"self"`
Keystore host (WebAuthn relying party).
```ts twoslash
import { Porto, Mode } from 'porto'
const porto = Porto.create({
mode: Mode.relay({
keystoreHost: 'https://account.my-wallet.com', // [!code focus]
}),
})
```
##### webAuthn
##### webAuthn.createFn
* **Type**: `WebAuthnP256.createCredential.Options['createFn']`
WebAuthn create credential function. Defaults to `navigator.credentials.create`.
:::tip
You can override this with a custom implementation of the WebAuthn API.
For example, you can use [`react-native-passkeys`](https://github.com/peterferguson/react-native-passkeys) for React Native.
:::
##### webAuthn.getFn
* **Type**: `WebAuthnP256.sign.Options['getFn']`
WebAuthn get credential function. Defaults to `navigator.credentials.get`.
:::tip
You can override this with a custom implementation of the WebAuthn API.
For example, you can use [`react-native-passkeys`](https://github.com/peterferguson/react-native-passkeys) for React Native.
:::
## Router
Instantiates a server framework-agnostic router for Porto.
{/* [!code ++] */}
{/* [!code ++] */}
