From b2276e9b9f33fc513b510763614df176f53ecb1a Mon Sep 17 00:00:00 2001
From: arcoraven <arcoraven@gmail.com>
Date: Thu, 3 Oct 2024 21:56:26 +0000
Subject: [PATCH] chore: move gas and timeout details to Engine FAQ (#4914)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

<!-- start pr-codex -->

## PR-Codex overview
This PR focuses on updating the documentation for transaction settings in the `Engine` feature. It clarifies the structure and usage of `txOverrides` for sending native currency and overriding gas settings, including examples and warnings about transaction timeouts.

### Detailed summary
- Changed keys in `txOverrides` from unquoted to quoted strings in the JSON structure.
- Added a section on sending native currency with examples.
- Introduced a section on overriding gas settings with examples.
- Included a warning about setting a timeout for transactions.
- Added a section on specifying transaction timeouts with examples.

> ✨ Ask PR-Codex anything about this PR by commenting with `/codex {your question}`

<!-- end pr-codex -->
---
 apps/portal/src/app/engine/faq/page.mdx       | 62 +++++++++++++++++++
 .../app/engine/features/contracts/page.mdx    | 26 ++------
 2 files changed, 66 insertions(+), 22 deletions(-)

diff --git a/apps/portal/src/app/engine/faq/page.mdx b/apps/portal/src/app/engine/faq/page.mdx
index b36169a4364..875d8ecdefa 100644
--- a/apps/portal/src/app/engine/faq/page.mdx
+++ b/apps/portal/src/app/engine/faq/page.mdx
@@ -1,3 +1,5 @@
+import { Callout } from "@doc";
+
 # FAQ
 
 ## About Engine
@@ -45,6 +47,66 @@ Here are three ways to determine when the job is mined:
   };
   ```
 
+### How do I send native currency with my transaction?
+
+To send native tokens (e.g. ETH on Ethereum), set `txOverrides.value`.
+This may be required when calling a `payable` contract method.
+
+Here's an example of sending 0.2 ETH:
+
+```json
+{
+  // ...other arguments in the write transaction
+
+  "txOverrides": {
+    "value": "200000000000000000"
+  }
+}
+```
+
+### How do I override gas settings?
+
+To override the gas settings, set relevant `txOverrides` gas fields.
+Each field is optional and will be estimated by Engine if omitted.
+
+Here's an example of setting a gas limit of 210,000 gas units, 1 gwei max fee, and 1 gwei max priority fee:
+
+```json
+{
+  // ...other arguments in the write transaction
+
+  "txOverrides": {
+    "gas": "210000",
+    "maxFeePerGas": "1000000000",
+    "maxPriorityFeePerGas": "1000000000"
+  }
+}
+```
+
+<Callout variant='warning' title="It is highly recommended to set a timeout when setting a maxFeePerGas.">
+
+Otherwise if gas prices don't fall, transactions may be in your queue indefinitely.
+
+</Callout>
+
+### How do I set a timeout on transactions?
+
+To specify a transaction timeout, set `txOverrides.timeoutSeconds`.
+Engine flags transactions as `errored` if they are not sent before the timeout. An `errored` webhook will be sent.
+
+Note: A transaction sent before the timeout may be mined after the timeout.
+
+Here's an example of a 2-hour timeout:
+```json
+{
+  // ...other arguments in the write transaction
+
+  "txOverrides": {
+    "timeoutSeconds": 7200
+  }
+}
+```
+
 ### How do I customize my RPC?
 
 Use [Update Chain Configuration](https://redocly.github.io/redoc/?url=https://demo.web3api.thirdweb.com/json#tag/Configuration/operation/updateChainsConfiguration) to override a chain's settings.
diff --git a/apps/portal/src/app/engine/features/contracts/page.mdx b/apps/portal/src/app/engine/features/contracts/page.mdx
index 705264d7cbd..183f47c6894 100644
--- a/apps/portal/src/app/engine/features/contracts/page.mdx
+++ b/apps/portal/src/app/engine/features/contracts/page.mdx
@@ -75,32 +75,14 @@ To send native tokens to a payable method (e.g. ETH on Ethereum), set `txOverrid
 
 ```json
 {
-  functionName: "...",
-  args: [ ... ],
-  txOverrides: {
-    value: 1000000000000000, // 0.001 ETH in wei
+  "functionName": "...",
+  "args": [ ... ],
+  "txOverrides": {
+    "value": "1000000000000000", // 0.001 ETH in wei
   }
 }
 ```
 
-### Override gas settings
-
-To override the gas settings for your transaction, set `txOverrides` in the request body to any write transaction. Each of these fields are optional and will be estimated by Engine if omitted.
-
-```json
-{
-  functionName: "...",
-  args: [ ... ],
-  txOverrides: {
-    // The limit of gas units to use for this transaction.
-    gas: "530000",
-    // The max fee (e.g. gas price) to use in wei.
-    maxFeePerGas: "1000000000",
-    // The max priority fee to use in wei.
-    maxPriorityFeePerGas: "1000000000",
-}
-```
-
 ## Read from a contract
 
 ```ts