diff --git a/pages/builders/tools/build/account-abstraction.mdx b/pages/builders/tools/build/account-abstraction.mdx index 8d9bf410c..7cebf8eb5 100644 --- a/pages/builders/tools/build/account-abstraction.mdx +++ b/pages/builders/tools/build/account-abstraction.mdx @@ -19,6 +19,16 @@ import { Callout } from 'nextra/components' * Sponsor the gas fees for transactions * Enable users to pay gas in the token(s) of their choice +## Bundlers + +The OP Stack includes support for the `eth_sendRawTransactionConditional` RPC method to assist bundlers on shared 4337 mempools. See the [specification](/stack/protocol/features/send-raw-transaction-conditional) for how this method is implemented in op-geth. + +If enabled by the chain operator, also see the supplemental [op-txproxy](/stack/operators/features/op-txproxy) service, if applied, as this enforces request authentication for this method. + + + As of today, this endpoint is not enabled by default in the stack. The operator must explicitly configure this. + + ## Superchain Paymaster The Superchain paymaster is an ERC-4337 verifying paymaster that sponsors transactions for smart accounts on the Superchain. Use the Superchain Paymaster to get your transactions sponsored to remove friction from your app experience. [View the implementation guide and tutorials here.](https://github.com/ethereum-optimism/ecosystem/tree/main/docs/superchain-paymaster) diff --git a/pages/stack/operators/features/_meta.json b/pages/stack/operators/features/_meta.json index 91f5e9e5c..754729f73 100644 --- a/pages/stack/operators/features/_meta.json +++ b/pages/stack/operators/features/_meta.json @@ -1,3 +1,4 @@ { - "proxyd": "proxyd" -} \ No newline at end of file + "proxyd": "proxyd", + "op-txproxy": "op-txproxy" +} diff --git a/pages/stack/operators/features/op-txproxy.mdx b/pages/stack/operators/features/op-txproxy.mdx new file mode 100644 index 000000000..525519dbe --- /dev/null +++ b/pages/stack/operators/features/op-txproxy.mdx @@ -0,0 +1,97 @@ +--- +title: op-txproxy +lang: en-US +description: A passthrough proxy service that can apply additional constraints on transactions prior to reaching the sequencer. +--- + +import { Callout, Steps } from 'nextra/components' + +# op-txproxy + +A [passthrough proxy](https://github.com/ethereum-optimism/infra/tree/main/op-txproxy) for the execution engine endpoint. This proxy does not forward all RPC traffic and only exposes a specific set of methods. Operationally, the ingress router should only re-route requests for these specific methods. + + + [proxyd](./proxyd) as an ingress router supports the mapping of specific methods to unique backends. + +## Methods + +### **eth_sendRawTransactionConditional** + +To safely expose this endpoint publicly, additional stateless constraints are applied. These constraints help scale validation rules horizontally and preemptively reject conditional transactions before they reach the sequencer. + +Various metrics are emitted to guide necessary adjustments. +#### Authentication + +The caller authenticates using any valid ECDSA-secp256k1 key, such as an Ethereum key. The signature is computed over the [EIP-191](https://eips.ethereum.org/EIPS/eip-191) hash of the request body. The calling address does **not need to hold an Ethereum balance**; it is simply used for identification. + +With the signature and signing address, the request is authenticated under the `X-Optimism-Signature` header with the value `: `. + +* Requests with a missing authentication header fail with the `-32003` (transaction rejected) json rpc error code. +* Requests with a mismatch in recovered signer and supplied public key will have the http request failed with status code `400 - Bad Request`. + +Currently, no authorization policies are implemented on this endpoint. However, the authentication mechanism is in place to allow for future implementation of policies such as allowlists, localized rate limits, and other potential restrictions. +#### Runtime Shutoff + +This service can be configured with a flag or environment variable to reject conditional transactions without needing to interrupt the execution engine. This feature is useful for diagnosing issues. + +`--sendRawTxConditional.enabled (default: true) ($OP_TXPROXY_SENDRAWTXCONDITIONAL_ENABLED)` + +When disabled, requests will fail with the `-32003` (transaction rejected) json rpc error code with a message stating that the method is disabled. +#### Rate Limits + +Even though the op-geth implementation of this endpoint includes rate limits, it is instead applied here to terminate these requests early. + +`--sendRawTxConditional.ratelimit (default: 5000) ($OP_TXPROXY_SENDRAWTXCONDITIONAL_RATELIMIT)` + +#### Stateless Validation + +* Conditional cost is below the max +* Conditional values are valid (i.e min \< max) +* Transaction target are only 4337 Entrypoint contracts + + + The motivating factor for this endpoint is to enable permissionless 4337 mempools, hence the restricted usage of this methods to just [Entrypoint](https://github.com/eth-infinitism/account-abstraction/blob/develop/contracts/core/EntryPoint.sol) transactions. + + Please open up an issue if you'd like this restriction to be optional via configuration to broaden usage of this endpoint. + + +When the request passes validation, it is passed through to the configured backend URL + +`--sendRawTxConditional.backend ($OP_TXPROXY_SENDRAWTXCONDITIONAL_BACKENDS)` + + + + Per the [specification](/stack/protocol/features/send-raw-transaction-conditional), conditional transactions are not gossiped between peers. Thus, if you use replicas in an active/passive sequencer setup, this request must be broadcasted to all replicas. + + [proxyd](./proxyd) as an egress router for this method supports this broadcasting functionality. + + +## How it works + +To start using `op-txproxy`, follow these steps: + + + ### Build the Binary or Pull the Docker Image + + 1. Run the following command to build the binary + ```bash + make build + ``` + 2. This will build and output the binary under `/bin/op-txproxy`. + + The image for this binary is also available as a [docker artifact](https://us-docker.pkg.dev/oplabs-tools-artifacts/images/op-txproxy). + + ### Configure + + The binary accepts configuration through CLI flags, which also settable via environment variables. Either set the flags explicitly when starting the binary or set the environment variables of the host starting the proxy. + + See [methods](#methods) on the configuration options available for each method. + + ### Start + + start the service with the following command + + ```bash + op-txproxy // ... with flags if env variables are not set + ``` + diff --git a/pages/stack/protocol/features/_meta.json b/pages/stack/protocol/features/_meta.json index bcc657416..b9221d748 100644 --- a/pages/stack/protocol/features/_meta.json +++ b/pages/stack/protocol/features/_meta.json @@ -1,4 +1,5 @@ { "custom-gas-token": "Custom Gas Token", - "alt-da-mode": "Alt-DA Mode" -} \ No newline at end of file + "alt-da-mode": "Alt-DA Mode", + "send-raw-transaction-conditional": "SendRawTransactionConditional" +} diff --git a/pages/stack/protocol/features/send-raw-transaction-conditional.mdx b/pages/stack/protocol/features/send-raw-transaction-conditional.mdx new file mode 100644 index 000000000..ae8b14175 --- /dev/null +++ b/pages/stack/protocol/features/send-raw-transaction-conditional.mdx @@ -0,0 +1,63 @@ +--- +title: SendRawTransactionConditional Explainer +lang: en-US +description: Learn about the eth_sendRawTransactionConditional RPC method for conditional transaction inclusion on the OP Stack. +--- + +import { Callout } from 'nextra/components' + +# SendRawTransactionConditional Explainer + +A sequencer rpc, `eth_sendRawTransactionConditional`, allowing callers to conditionally include a transaction based on a set of provided options. + +This feature is meant to unblock use cases that require atomic inclusion, otherwise possible on Ethereum through specialized block builders like Flashbots. Some examples: + +* 4337 Bundlers utilizing a shared mempool of UserOperations. Reverted transactions due to conflicting UserOperations would make it too costly for bundlers to operate on L2, forcing the use of private mempools. + +## Specification + +This endpoint is an extension of `eth_sendRawTransaction`, with an extra parameter of "options" with the following structure: + +``` +{ + "knownAccounts": [optional] A map of accounts with expected storage. The key is account address + If the value is hex string, it is the known storage root hash of that account. + If the value is an object, then each member is in the format of "slot": "value", which are explicit slot values within that account storage. + "blockNumberMin": [optional] minimal block number for inclusion + "blockNumberMax": [optional] maximum block number for inclusion + "timestampMin": [optional] minimum block timestamp for inclusion + "timestampMax": [optional] maximum block timestamp for inclusion +} +``` + +The "cost" of a given conditional is *approximately* determined by the number of storage lookups that would be incurred by validating this conditional. There's a predefined max of `1000` that is allowed to prevent DoS. + + + Since the sequencer is not compensated for the additional state checks, otherwise through the GAS of the transaction, a configured rate limit is applied to this cost. + + To also disincentive the use of this endpoint for MEV in comparison to `eth_sendRawTransaction`, the conditional is checked against the parent of the latest block. + + +This conditional is checked once at the RPC layer prior to mempool submission. If rejected against chain state, the RPC will return an error with the following spec + +* error code `-32003` (transaction rejected) with a reason string as to the specific failed check +* error code `-32005` (conditional cost) with a reason string if the conditional cost exceeded the maximum OR the cost was rate limited due to network conditions. + +Successful submission does **NOT** guarantee inclusion! The caller must observe the chain for a receipt with some timeout to determine non-inclusion. The conditional is also re-checked in the block building phase to handle intra-block conflicts. + + + Conditional transactions are tied to the block builder they are submitted to. This means that these transactions **are not gossiped between configured peers!!!** + + If you are running an active/passive setup with replicas that gossip txs to an active sequencer, this endpoint should be fronted by a proxy that can broadcast the request to all replicas. + + +## How To Enable + +This feature can be enabled with the addition of a flag to op-geth. + +* `--rollup.sequencertxconditionalenabled` (default: false) a boolean flag which enables the rpc. +* `--rollup.sequencertxconditionalcostratelimit` (default: 5000) an integer flag that sets the rate limit for cost observable per second. + + + It is not advised to publicly expose this sequencer endpoint due to DoS concerns. This supplemental proxy, [op-txproxy](/stack/operators/features/op-txproxy), should be used to apply additional constraints on this endpoint prior to passing through to the sequencer. + diff --git a/words.txt b/words.txt index 53e4d2a99..38f10aee6 100644 --- a/words.txt +++ b/words.txt @@ -104,6 +104,7 @@ farcaster FDLIMIT fdlimit featureset +Flashbots forkable forkchoice FPVM @@ -342,7 +343,6 @@ syncmode SYNCTARGET synctarget syscalls -Terraform therealbytes Thirdweb threadcreate @@ -355,6 +355,7 @@ txfeecap txmgr TXPOOL txpool +txproxy uncountered Unprotect unsubmitted