Skip to content

Commit bc59a4b

Browse files
avitenzerclaude
andauthored
docs(api): a pinned write goes to the pinned node only (MAG-4382) (#82)
Product decision A on MAG-4382: a pin means "only this node" for reads and writes alike, so a write carrying lava-select-provider or lava-stickiness is sent to the pinned node only and gives up the broadcast to every node. That is the router's behaviour today; the docs never said it. directives.md: a note under the pin section, a sentence in the sticky section, and a lava-fast-tx-participants row in the response headers (it was not documented), which is how a caller sees who got the write. sticky-sessions.md: the read-your-own-write row says the write itself then goes to one node, and how to keep the broadcast. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
1 parent 2d9f6b9 commit bc59a4b

2 files changed

Lines changed: 11 additions & 2 deletions

File tree

‎docs/api/directives.md‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,14 @@ curl -X POST http://127.0.0.1:3360 \
7373

7474
If the node is unreachable, the request then fails with an error instead of returning a cached answer.
7575

76+
!!! note "A pinned write goes to the pinned node only"
77+
A write, such as `eth_sendRawTransaction`, is normally sent to every node at once, so one
78+
node dropping the transaction does not lose it. A pin means "only this node" for reads and
79+
writes alike: a write that carries `lava-select-provider` (or [`lava-stickiness`](#keep-a-session-on-one-node))
80+
is sent to the pinned node only and gives up that broadcast. The reply's
81+
[`lava-fast-tx-participants`](#response-headers) header names the nodes that received the write.
82+
To keep the broadcast, send writes without a pin.
83+
7684
## Keep a session on one node
7785

7886
```
@@ -96,7 +104,7 @@ curl -X POST http://127.0.0.1:3360 \
96104
-d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
97105
```
98106

99-
To work across replicas, the header needs a cache backend and `--shared-state`. Without them, it only applies within a single replica. If the chosen node cannot serve a request, the request fails. No other node serves it. See [Sticky sessions](../configuration/sticky-sessions.md) for the full behaviour and limits.
107+
To work across replicas, the header needs a cache backend and `--shared-state`. Without them, it only applies within a single replica. If the chosen node cannot serve a request, the request fails. No other node serves it. A write in the session goes to that node only, without the usual broadcast to every node (see [A pinned write](#pin-to-a-specific-node)). See [Sticky sessions](../configuration/sticky-sessions.md) for the full behaviour and limits.
100108

101109
## Force a cache refresh
102110

@@ -236,6 +244,7 @@ Smart Router adds metadata to every response about how the relay was served. The
236244
| `Lava-Provider-Address` | The node that finally served the response. The literal value **`Cached`** means the [cache](../deployment/cache/index.md) answered and the router contacted *no* node, even when the request named one with `lava-select-provider`. |
237245
| `Lava-Retries` | Number of retry attempts made for this relay. |
238246
| `Provider-Latest-Block` | Latest block the serving node reported. |
247+
| `lava-fast-tx-participants` | On a write only: the nodes the router sent it to, in brackets and space-separated, e.g. `[node-a node-b]`. A single name means the write was not broadcast, for example because it was [pinned](#pin-to-a-specific-node). |
239248
| `Lava-Guid` | Unique request id. Use it to find the request in logs and traces. |
240249
| `Lava-Errored-Providers` | Nodes that errored on this request. |
241250
| `Lava-Node-Errors-providers` | Nodes that returned a node-level error. |

‎docs/configuration/sticky-sessions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,7 @@ A session's choice lasts about two router epochs (30 minutes at the default `--e
7777
|---|---|
7878
| Two or more calls that must agree: read the head, then fetch that block | **Yes**. This is what it is for |
7979
| Node-side state tied to one node, such as an `eth_newFilter` id or a subscription handle | **Yes** |
80-
| Read-your-own-write after `eth_sendRawTransaction` | **Yes** |
80+
| Read-your-own-write after `eth_sendRawTransaction` | **Yes**. The write itself then goes to the session's node only, not to every node: a sticky write gives up the broadcast. Send the write without the header if you want the broadcast, and the follow-up reads with it |
8181
| Independent single reads with no relationship to each other | No. Pinning gives up the optimizer's choice with no benefit |
8282
| A specific node you already know by name | No. Use [`lava-select-provider`](../api/directives.md#pin-to-a-specific-node) |
8383

0 commit comments

Comments
 (0)