Skip to content

Commit

Permalink
Engine doc: webhook updates, remove v2 beta banner (#4296)
Browse files Browse the repository at this point in the history
  • Loading branch information
@arcoraven
arcoraven authored Aug 27, 2024
1 parent 1ef1921 commit a8e2bc5
Show file tree
Hide file tree
Showing 4 changed files with 154 additions and 92 deletions.
17 changes: 9 additions & 8 deletions apps/portal/src/app/engine/faq/page.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,15 @@

## About Engine

### Which contracts work with Engine?

Engine supports reads and writes to any contract verified on the blockchain explorer, including any contract deployed via thirdweb.
_Note: Some endpoints allow providing the contract ABI to support any unverified contract._

Engine also supports deploys for thirdweb [prebuilt contracts](https://thirdweb.com/explore) including NFTs, tokens, marketplaces, and smart accounts.

If you have a question about a particular contract type, [contact us](https://thirdweb.com/support).

### How are Engine and the thirdweb Contract SDK different?

Engine is a server that manages your backend wallets and how they interact with contracts. This difference unlocks capabilities that thirdweb and other web3 SDKs, including:
Expand All @@ -14,14 +23,6 @@ Engine is a server that manages your backend wallets and how they interact with

Additionally, Engine is built on top of the thirdweb SDK and has the same capabilities.

### Does Engine work with all thirdweb smart contracts?

Yes. Engine has intuitive interfaces to deploy prebuilt contracts, manage smart accounts, run a marketplace, and more.

### Does Engine work with my non-thirdweb smart contract?

Yes. Engine can read and write to any EVM contract with low-level API calls, including providing raw calldata. ERC-721 and ERC-1155 APIs can also be used for [contracts imported to thirdweb](https://support.thirdweb.com/smart-contracts/rtHYyzspnPaHmmANmJQz1k/importing-non-thirdweb-contracts-into-the-dashboard/hELLjgTc8TWrMdMEQkm2Es).

## Using Engine

### How do I wait for a transaction to be mined?
Expand Down
211 changes: 144 additions & 67 deletions apps/portal/src/app/engine/features/webhooks/page.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import webhooksImage from "../../assets/engine-webhooks.webp";
import { createMetadata, DocImage } from "@doc";
import { createMetadata, Details, DocImage } from "@doc";

export const metadata = createMetadata({
title: "Webhooks | thirdweb Engine",
Expand All @@ -15,20 +15,34 @@ Configure webhooks in Engine to notify your backend server of transaction or bac

### Transactions

| Event | Description |
| --------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `queued_transaction` | A transaction is added to the Engine queue. |
| `sent_transaction` | A transaction is submitted to an RPC provider. A transaction hash is provided, but it may not be mined onchain yet. |
| `mined_transaction` | A transaction is mined on the blockchain. A transaction hash is provided, and it is mined onchain. |
| `errored_transaction` | A transaction is unable to be submitted. There may be an error in the transaction params, backend wallet, or server. |
| `all_transaction` | All the above events. The `status` field will be one of: `queued`, `sent`, `mined`, `errored`. |
Handle when a blockchain transaction is sent and mined onchain.

| Event | Description |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sent_transaction` | A transaction is submitted to RPC. A transaction hash is provided, but it may not be mined onchain yet. |
| `mined_transaction` | A transaction is mined on the blockchain. **Note: The transaction may have reverted onchain. Check the `onchainStatus` field to confirm if the transaction was successful.** |
| `errored_transaction` | A transaction is unable to be submitted. There may be an error in the transaction params, backend wallet, or server. |
| `all_transaction` | All the above events. |

<DocImage
src={webhooksImage}
alt="Webhooks lifecycle"
className="max-w-[500px] mx-auto"
/>

The transaction payload contains a `status` field which is one of: `sent`, `mined`, `errored`

Depending on the transaction, your backend will receive one of these webhook sequences:
| Transaction statuses | Description |
|-|-|
| `sent` + `mined` | The transaction was sent and mined onchain. |
| `errored` | The transaction errored before being sent. Common reasons: The transaction failed simulation, the backend wallet is out of funds, the network is down, or another internal error, transaction with a gas ceiling timed out. The errorMessage field will contain further details. |
| `sent` + `errored` | The transaction was sent but was not mined onchain after some duration. Common reasons: The transaction was dropped from RPC mempool, another transaction was mined with the same nonce, or the nonce was too far ahead of the onchain nonce. |
| `cancelled` | The transaction was in queue (not sent yet) and cancelled. |
| `sent` + `cancelled` | The transaction was sent and waiting to be mined, but cancelled. |

**Note:** Webhooks may come out of order. Treat later statuses as higher priority than earlier ones. For example if your backend receives a `sent` webhook after a `mined` webhook, treat this transaction as `mined`.

### Wallets

| Event | Description |
Expand All @@ -45,6 +59,128 @@ Configure webhooks in Engine to notify your backend server of transaction or bac

Webhook URLs must start with `https://`.

## Payload format

Method: `POST`

Headers:

- `Content-Type: application/json`
- `X-Engine-Signature: <payload signature>`
- `X-Engine-Timestamp: <Unix timestamp in seconds>`

<Details id="sample-sent-transaction-payload" summary="Example sent transaction">

```json
{
// Queue details
"queueId": "1411246e-b1c8-4f5d-9a25-8c1f40b54e55",
"status": "sent",
"onchainStatus": null,
"queuedAt": "2023-09-29T22:01:31.031Z",
"sentAt": "2023-09-29T22:01:41.580Z",
"minedAt": null,
"errorMessage": null,
"cancelledAt": null,
"retryCount": 0,

// Onchain details
"chainId": 80001,
"fromAddress": "0x3ecdbf3b911d0e9052b64850693888b008e18373",
"toAddress": "0x365b83d67d5539c6583b9c0266a548926bf216f4",
"data": "0xa9059cbb0000000000000000000000003ecdbf3b911d0e9052b64850693888b008e183730000000000000000000000000000000000000000000000000000000000000064",
"value": "0x00",
"nonce": 1786,
"gasLimit": "39580",
"maxFeePerGas": "2063100466",
"maxPriorityFeePerGas": "1875545856",
"gasPrice": "1875545871",
"transactionType": null,
"transactionHash": "0xc3ffa42dd4734b017d483e1158a2e936c8a97dd1aa4e4ce11df80ac8e81d2c7e",
"sentAtBlockNumber": 40660021,
"blockNumber": null,

// User operation (account abstraction) details
"signerAddress": null,
"accountAddress": null,
"target": null,
"sender": null,
"initCode": null,
"callData": null,
"callGasLimit": null,
"verificationGasLimit": null,
"preVerificationGas": null,
"paymasterAndData": null,
"userOpHash": null,

// Off-chain details
"functionName": "transfer",
"functionArgs": "0x3ecdbf3b911d0e9052b64850693888b008e18373,100",
"extension": "none",
"deployedContractAddress": null,
"deployedContractType": null
}
```

</Details>

<Details id="sample-mined-transaction-payload" summary="Example mined transaction">

Tip: Check the `onchainStatus` field. "success" means the transaction is mined onchain with no errors. "reverted" means the transaction or userOp was reverted.

```json
{
// Queue details
"queueId": "1411246e-b1c8-4f5d-9a25-8c1f40b54e55",
"status": "mined",
"onchainStatus": "success",
"queuedAt": "2023-09-29T22:01:31.031Z",
"sentAt": "2023-09-29T22:01:41.580Z",
"minedAt": "2023-09-29T22:01:44.000Z",
"errorMessage": null,
"cancelledAt": null,
"retryCount": 0,

// Onchain details
"chainId": 80001,
"fromAddress": "0x3ecdbf3b911d0e9052b64850693888b008e18373",
"toAddress": "0x365b83d67d5539c6583b9c0266a548926bf216f4",
"data": "0xa9059cbb0000000000000000000000003ecdbf3b911d0e9052b64850693888b008e183730000000000000000000000000000000000000000000000000000000000000064",
"value": "0x00",
"nonce": 1786,
"gasLimit": "39580",
"maxFeePerGas": "2063100466",
"maxPriorityFeePerGas": "1875545856",
"gasPrice": "1875545871",
"transactionType": 2,
"transactionHash": "0xc3ffa42dd4734b017d483e1158a2e936c8a97dd1aa4e4ce11df80ac8e81d2c7e",
"sentAtBlockNumber": 40660021,
"blockNumber": 40660026,

// User operation (account abstraction) details
"signerAddress": null,
"accountAddress": null,
"target": null,
"sender": null,
"initCode": null,
"callData": null,
"callGasLimit": null,
"verificationGasLimit": null,
"preVerificationGas": null,
"paymasterAndData": null,
"userOpHash": null,

// Off-chain details
"functionName": "transfer",
"functionArgs": "0x3ecdbf3b911d0e9052b64850693888b008e18373,100",
"extension": "none",
"deployedContractAddress": null,
"deployedContractType": null
}
```

</Details>

## Webhook verification (recommended)

Since any outside origin can call your webhook endpoint, it is recommended to verify the webhook signature to ensure a request comes from your Engine instance.
Expand Down Expand Up @@ -145,62 +281,3 @@ app.listen(port, () => {
console.log(`Server started on http://localhost:${port}`);
});
```

## Payload format

The webhook request to your backend follows this format.

Method: `POST`

Headers:

- `Content-Type`: `application/json`
- `X-Engine-Signature`: &lt;payload signature&gt;
- `X-Engine-Timestamp`: &lt;Unix timestamp in seconds&gt;

```json
{
"chainId": 80001,
"data": "0xa9059cbb0000000000000000000000003ecdbf3b911d0e9052b64850693888b008e183730000000000000000000000000000000000000000000000000000000000000064",
"value": "0x00",
"gasLimit": "39580",
"nonce": 1786,
"maxFeePerGas": "2063100466",
"maxPriorityFeePerGas": "1875545856",
"fromAddress": "0x3ecdbf3b911d0e9052b64850693888b008e18373",
"toAddress": "0x365b83d67d5539c6583b9c0266a548926bf216f4",
"gasPrice": "1875545871",
"transactionType": 2,
"transactionHash": "0xc3ffa42dd4734b017d483e1158a2e936c8a97dd1aa4e4ce11df80ac8e81d2c7e",
"signerAddress": null,
"accountAddress": null,
"target": null,
"sender": null,
"initCode": null,
"callData": null,
"callGasLimit": null,
"verificationGasLimit": null,
"preVerificationGas": null,
"paymasterAndData": null,
"userOpHash": null,
"functionName": "transfer",
"functionArgs": "0x3ecdbf3b911d0e9052b64850693888b008e18373,100",
"extension": "none",
"deployedContractAddress": null,
"deployedContractType": null,
"queuedAt": "2023-09-29T22:01:31.031Z",
"processedAt": "2023-09-29T22:01:38.754Z",
"sentAt": "2023-09-29T22:01:41.580Z",
"minedAt": "2023-09-29T22:01:44.000Z",
"cancelledAt": null,
"retryCount": 0,
"retryGasValues": false,
"retryMaxPriorityFeePerGas": null,
"retryMaxFeePerGas": null,
"errorMessage": null,
"sentAtBlockNumber": 40660021,
"blockNumber": 40660026,
"queueId": "1411246e-b1c8-4f5d-9a25-8c1f40b54e55",
"status": "mined"
}
```
10 changes: 1 addition & 9 deletions apps/portal/src/app/engine/page.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,10 @@
import OverviewImage from "./assets/engine-overview.png";
import { Callout, DocImage, OpenSourceCard } from "@doc";
import { DocImage, OpenSourceCard } from "@doc";

# Engine

Engine is an open-source, backend server that reads, writes, and deploys contracts at production scale.

<Callout variant='info' title="Engine v2 in public beta">

Engine v2 redesigns the worker architecture to dramatically increase onchain throughput.

[Read the blog post](https://blog.thirdweb.com/changelog/engine-v2-public-beta/) for benchmarks and upgrade instructions.

</Callout>

## Why use Engine?

Engine enables your app to:
Expand Down
8 changes: 0 additions & 8 deletions apps/portal/src/app/engine/self-host/page.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,6 @@ dashboard](https://thirdweb.com/dashboard/engine).

</Callout>

<Callout variant='info' title="Engine v2 in public beta">

Engine v2 redesigns the worker architecture to dramatically increase onchain throughput.

[Read the blog post](https://blog.thirdweb.com/changelog/engine-v2-public-beta/) for benchmarks and upgrade instructions.

</Callout>

### Requirements

- [Docker](https://docs.docker.com/get-docker/)
Expand Down

0 comments on commit a8e2bc5

Please sign in to comment.