Skip to content

Commit 2ef9c0a

Browse files
AlvaroLukenAlvaroLuken
authored
add monadNewHeads and monadLogs types to subscription API (#627)
* add monadnewheads and monadlogs types to subscription API * remove duplicate titles in types * add to main page
1 parent d958aac commit 2ef9c0a

File tree

6 files changed

+234
-4
lines changed

6 files changed

+234
-4
lines changed

‎fern/api-reference/websockets/subscription-api-endpoints/alchemy-minedtransactions.mdx‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,6 @@ url: https://docs.alchemy.com/reference/alchemy-minedtransactions
66
slug: reference/alchemy-minedtransactions
77
---
88

9-
# alchemy\_minedTransactions
10-
119
The `alchemy_minedTransactions` subscription type subscribes to mined transactions via WebSockets, and filters those transactions based on specified `from` and/or `to` addresses. The subscription will return either full transaction objects or just transaction hashes depending on the request. It will also optionally include re-orged or removed transactions if specified.
1210

1311
# Supported Networks

‎fern/api-reference/websockets/subscription-api-endpoints/alchemy-pendingtransactions.mdx‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,6 @@ url: https://docs.alchemy.com/reference/alchemy-pendingtransactions
55
slug: reference/alchemy-pendingtransactions
66
---
77

8-
# alchemy\_pendingTransactions
9-
108
The `alchemy_pendingTransactions` subscription type subscribes to pending transactions via WebSockets, and filters those transactions based on specified `from` and/or `to` addresses. The subscription will return either full transaction objects or just transaction hashes depending on the request. It will also optionally include re-orged or removed transactions if specified.
119

1210
<Info>

‎fern/api-reference/websockets/subscription-api-endpoints/monadlogs.mdx‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
title: monadLogs
3+
description: Returns logs (that match a given filter) as soon as the block is Proposed.
4+
subtitle: Returns logs (that match a given filter) as soon as the block is Proposed.
5+
url: https://docs.alchemy.com/reference/monadlogs
6+
slug: reference/monadlogs
7+
---
8+
9+
The `monadLogs` subscription type emits logs that match a specified topic filter as soon as the block is Proposed and the node has speculatively executed the transactions. This provides earlier access to log data compared to regular [`logs`](/reference/logs) subscriptions which wait for block finalization.
10+
11+
# Supported Networks
12+
13+
<Info>
14+
Check the [Chains](https://dashboard.alchemy.com/chains) page for details about product and chain support!
15+
16+
![](523fb8a9a9d899921ee1046d0ff1b389967a9976d1c6112ebbbe071ddd1ef374-image.png)
17+
</Info>
18+
19+
# Parameters
20+
21+
An object with the following fields:
22+
23+
* `address` (optional): `string` or `array of strings` Singular address or array of addresses. Only logs created from one of these addresses will be emitted.
24+
25+
* `topics`: an array of topic specifiers (**up to 4 topics allowed per address**).
26+
27+
* Each topic specifier is either `null`, a single string, or an array of strings.
28+
* For every non `null` topic, a log will be emitted when activity associated with that topic occurs.
29+
30+
<Info>
31+
To learn more about how log topics work, check out [this tutorial](/docs/how-to-listen-to-nft-mints).
32+
</Info>
33+
34+
# Request
35+
36+
<CodeGroup>
37+
```shell javascript
38+
// initiate websocket stream first
39+
wscat -c wss://eth-mainnet.g.alchemy.com/v2/demo
40+
41+
// then call subscription
42+
{"jsonrpc":"2.0","id": 1, "method": "eth_subscribe", "params": ["logs", {"address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]}]}
43+
```
44+
45+
```javascript alchemy-sdk
46+
import { Alchemy, Network } from "alchemy-sdk";
47+
import { ethers } from "ethers";
48+
49+
const settings = {
50+
apiKey: "demo", // Replace with your Alchemy API Key.
51+
network: Network.ETH_MAINNET, // Replace with your network.
52+
};
53+
const alchemy = new Alchemy(settings);
54+
55+
// This filter could also be generated with the Contract or
56+
// Interface API. If address is not specified, any address
57+
// matches and if topics is not specified, any log matches
58+
const filter = {
59+
address: "dai.tokens.ethers.eth",
60+
topics: [ethers.utils.id("Transfer(address,address,uint256)")],
61+
};
62+
63+
alchemy.ws.on(filter, (log, event) => {
64+
// Emitted whenever a DAI token transfer occurs
65+
});
66+
67+
// Notice this is an array of topic-sets and is identical to
68+
// using a filter with no address (i.e. match any address)
69+
const topicSets = [
70+
ethers.utils.id("Transfer(address,address,uint256)"),
71+
null,
72+
[address1, address2],
73+
];
74+
75+
alchemy.ws.on(topicSets, (log, event) => {
76+
// Emitted any token is sent TO either address
77+
});
78+
```
79+
</CodeGroup>
80+
81+
# Result
82+
83+
<CodeGroup>
84+
```json result
85+
{
86+
"jsonrpc":"2.0",
87+
"method":"eth_subscription",
88+
"params": {
89+
"subscription":"0x4a8a4c0517381924f9838102c5a4dcb7",
90+
"result":{
91+
"blockId": "0x71ce47f39a1eb490354166f762d78bf6e2acaf80b24b4bcd756118d93ef81be0",
92+
"commitState": "Proposed",
93+
"address":"0x8320fe7702b96808f7bbc0d4a888ed1468216cfd",
94+
"blockHash":"0x61cdb2a09ab99abf791d474f20c2ea89bf8de2923a2d42bb49944c8c993cbf04",
95+
"blockNumber":"0x29e87",
96+
"data":"0x00000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000003",
97+
"logIndex":"0x0",
98+
"topics":["0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902"],
99+
"transactionHash":"0xe044554a0a55067caafd07f8020ab9f2af60bdfe337e395ecd84b4877a3d1ab4",
100+
"transactionIndex":"0x0"
101+
}
102+
}
103+
}
104+
```
105+
</CodeGroup>
106+
107+
Below you can find the explanation for individual properties of the response:
108+
109+
* **`jsonrpc`**: The `jsonrpc` property specifies the version of the JSON-RPC protocol that is being used, which in this case is "2.0".
110+
* **`method`**: The `method` property specifies the method that was called, which in this case is `eth_subscription`.
111+
* **`params`**: The `params` property contains the parameters of the method call. In this case, it contains a `subscription` property, which specifies the subscription identifier, and a `result` property, which contains the result of the subscription.
112+
* **`result`**: The `result` property contains information about a specific transaction on the Ethereum blockchain.
113+
* **`address`**: The `address` property specifies the address from which this log originated.
114+
* **`blockhash`**: The `blockHash` property specifies the hash of the block in which the transaction was included.
115+
* **`blockNumber`**: The `blockNumber` property specifies the number of the block in which the transaction was included. It is encoded as a hexadecimal string.
116+
* **`data`**: Contains one or more 32 Bytes non-indexed arguments of the log.
117+
* **`logIndex`**: The `logIndex` property specifies the index or position of the log entry within the block. It is encoded as a hexadecimal string.
118+
* **`topics`**: An array of 0 to 4 32 bytes topic hashes of indexed log arguments (up to 4 topics allowed per address).
119+
* **`transactionHash`**: The `transactionHash` property specifies the hash of the transaction.
120+
* **`transactionIndex`**: The `transactionIndex` property specifies the index or position of the transaction within the block. It is encoded as a hexadecimal string.

‎fern/api-reference/websockets/subscription-api-endpoints/monadnewheads.mdx‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
---
2+
title: monadNewHeads
3+
description: Fires a notification each time as soon as a block is Proposed and the node has a chance to speculatively execute.
4+
subtitle: Fires a notification each time as soon as a block is Proposed and the node has a chance to speculatively execute.
5+
url: https://docs.alchemy.com/reference/monadnewheads
6+
slug: reference/monadnewheads
7+
---
8+
9+
The `monadNewHeads` is the same as the [`newHeads`](/reference/newheads) subscription type, but the notification emits as soon as the block is `Proposed` and the node has a chance to [speculatively execute](https://docs.monad.xyz/monad-arch/realtime-data/spec-realtime).
10+
11+
# Supported Networks
12+
13+
<Info>
14+
Check the [Chains](https://dashboard.alchemy.com/chains) page for details about product and chain support!
15+
16+
![](523fb8a9a9d899921ee1046d0ff1b389967a9976d1c6112ebbbe071ddd1ef374-image.png)
17+
</Info>
18+
19+
# Parameters
20+
21+
* None
22+
23+
# Response
24+
25+
A `monadNewHeads` update looks the same as a `newHeads` update except that it contains the additional `blockId` and `commitState` fields:
26+
27+
* `result`
28+
29+
* `blockId`: DATA, 32 Bytes - The unique identifier of the block. Example: "0x71ce47f39a1eb490354166f762d78bf6e2acaf80b24b4bcd756118d93ef81be0"
30+
* `commitState`: string - The current state of the block. Example: "Proposed"
31+
* `number`: QUANTITY - The block number. Null when it's a pending block.
32+
* `parentHash`: DATA, 32 Bytes - Hash of the parent block.
33+
* `nonce`: DATA, 8 Bytes - Hash of the generated proof-of-work. Null when it's a pending block.
34+
* `sha3Uncles`: DATA, 32 Bytes - SHA3 of the uncles data in the block.
35+
* `logsBloom`: DATA, 256 Bytes - The bloom filter for the logs of the block. Null when it's a pending block.
36+
* `transactionsRoot`: DATA, 32 Bytes - The root of the transaction trie of the block.
37+
* `stateRoot`: DATA, 32 Bytes - The root of the final state trie of the block.
38+
* `receiptsRoot`: DATA, 32 Bytes - The root of the receipts trie of the block.
39+
* `miner`: DATA, 20 Bytes - The address of the beneficiary to whom the mining rewards were given.
40+
* `difficulty`: QUANTITY - Integer of the difficulty for this block.
41+
* `extraData`: DATA - The "extra data" field of this block.
42+
* `gasLimit`: QUANTITY - The maximum gas allowed in this block.
43+
* `gasUsed`: QUANTITY - The total used gas by all transactions in this block.
44+
* `timestamp`: QUANTITY - The Unix timestamp for when the block was collated.
45+
46+
* `subscription`: `string` - Subscription ID
47+
48+
# Request
49+
50+
<CodeGroup>
51+
```shell wscat
52+
// initiate websocket stream first
53+
wscat -c wss://eth-mainnet.g.alchemy.com/v2/demo
54+
55+
// then call subscription
56+
{"jsonrpc":"2.0","id": 1, "method": "eth_subscribe", "params": ["monadNewHeads"]}
57+
```
58+
59+
```javascript alchemy-sdk
60+
// Installation: npm install alchemy-sdk
61+
import { Alchemy, Network } from "alchemy-sdk";
62+
63+
const settings = {
64+
apiKey: "demo", // Replace with your Alchemy API Key.
65+
network: Network.ETH_MAINNET, // Replace with your network.
66+
};
67+
const alchemy = new Alchemy(settings);
68+
69+
// Subscribe to new blocks, or monadNewHeads
70+
alchemy.ws.on("block", (blockNumber) =>
71+
console.log("Latest block:", blockNumber)
72+
);
73+
```
74+
</CodeGroup>
75+
76+
# Result
77+
78+
<CodeGroup>
79+
```json result
80+
{"jsonrpc":"2.0", "id":1, "result":"0x9ce59a13059e417087c02d3236a0b1cc"}
81+
82+
{
83+
"jsonrpc": "2.0",
84+
"method": "eth_subscription",
85+
"params": {
86+
"result": {
87+
"difficulty": "0x15d9223a23aa",
88+
"extraData": "0xd983010305844765746887676f312e342e328777696e646f7773",
89+
"gasLimit": "0x47e7c4",
90+
"gasUsed": "0x38658",
91+
"logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
92+
"miner": "0xf8b483dba2c3b7176a3da549ad41a48bb3121069",
93+
"nonce": "0x084149998194cc5f",
94+
"number": "0x1348c9",
95+
"parentHash": "0x7736fab79e05dc611604d22470dadad26f56fe494421b5b333de816ce1f25701",
96+
"receiptRoot": "0x2fab35823ad00c7bb388595cb46652fe7886e00660a01e867824d3dceb1c8d36",
97+
"sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",
98+
"stateRoot": "0xb3346685172db67de536d8765c43c31009d0eb3bd9c501c9be3229203f15f378",
99+
"timestamp": "0x56ffeff8",
100+
"transactionsRoot": "0x0167ffa60e3ebc0b080cdb95f7c0087dd6c0e61413140e39d94d3468d7c9689f"
101+
},
102+
"subscription": "0x9ce59a13059e417087c02d3236a0b1cc"
103+
}
104+
}
105+
```
106+
</CodeGroup>

‎fern/api-reference/websockets/subscription-api.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,8 @@ For a full list of Subscription API endpoints and supported chains see the [Subs
2929
| [newPendingTransactions](/reference/newpendingtransactions) | Emits transaction hashes that are sent to the network and marked as "pending". |
3030
| [newHeads](/reference/newheads) | Emits new blocks that are added to the blockchain. |
3131
| [logs](/reference/logs) | Emits logs attached to a new block that match certain topic filters. |
32+
| [monadNewHeads](/reference/monadnewheads) | Fires a notification each time as soon as a block is Proposed and the node has a chance to speculatively execute. |
33+
| [monadLogs](/reference/monadlogs) | Emits logs attached to a new block that match certain topic filters as soon as the block is Proposed and the node has a chance to speculatively execute. |
3234

3335
# What are WebSockets and how do they differ from HTTP?
3436

‎fern/docs.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1022,6 +1022,12 @@ navigation:
10221022
api-reference/websockets/subscription-api-endpoints/newheads.mdx
10231023
- page: logs
10241024
path: api-reference/websockets/subscription-api-endpoints/logs.mdx
1025+
- page: monadNewHeads
1026+
path: >-
1027+
api-reference/websockets/subscription-api-endpoints/monadnewheads.mdx
1028+
- page: monadLogs
1029+
path: >-
1030+
api-reference/websockets/subscription-api-endpoints/monadlogs.mdx
10251031
slug: subscription-api-endpoints
10261032
slug: websockets
10271033
- section: Trace API

0 commit comments

Comments
 (0)