Merge remote-tracking branch 'origin/main' into tyler/pro-394-docs-no-safe-on-chain-randomness-document-mandate-vrforacle

# Conflicts:
#	plugins/radius/skills/radius-dev/SKILL.md

Author: TJ-Frederick

plugins/radius/skills/radius-dev/SKILL.md

@@ -20,7 +20,7 @@ Use this Skill when the user asks for:
 - Radius network configuration, RPC endpoints, contract addresses
 - Production gotchas (wallet compatibility, nonce management, decimal handling)
 - Hardhat or ethers.js integration with Radius
-- JSON-RPC differences and Radius-specific extensions (EIP-7966, `rad_getBalanceRaw`)
+- JSON-RPC differences, the EIP-7966 sync method (`eth_sendRawTransactionSync`), and Radius-specific extensions (`rad_getBalanceRaw`)
 
 ## Default stack decisions (opinionated)
 
@@ -158,10 +158,12 @@ Always keep these in mind when writing code for Radius:
 | `eth_blockNumber` | Monotonic block height | Current timestamp in milliseconds |
 | Reconstructed blocks | N/A | Contain all txs executed within the same ms |
 | Block hash | Hash of block header | Equals block number (timestamp-based) |
-| `transactionIndex` | Position in block | Can be `0` for multiple txs in same ms |
+| `transactionIndex` | Position in block | Receipt always reports `0` — not a unique key; use `transactionHash` |
 | On-chain randomness (`blockhash`, `prevrandao`, `difficulty`) | `prevrandao` carries RANDAO mix | Not a randomness source: `prevrandao`/`difficulty` = `0`, `blockhash` predictable, no EIP-2935 — use off-chain entropy |
 | `eth_getLogs` | Address filter optional | Address filter **required** (error `-33014`) |
-| `eth_sendRawTransactionSync` | N/A | EIP-7966: sync tx+receipt (~50% less latency) |
+| `eth_getProof` | Merkle state proofs | Unsupported (error `-33000`) — instant-final state model, no proofs needed |
+| `eth_getBlockReceipts` | All receipts in a block | Unsupported (error `-33000`) — txs executed individually, not in blocks |
+| `eth_sendRawTransactionSync` | EIP-7966 sync tx submission (returns the receipt directly) | On Radius the receipt is **instant + final** (~100ms, no reorg) vs an L2 inclusion receipt (~460ms, reorg-able) |
 | `rad_getBalanceRaw` | N/A | Raw RUSD only (excludes convertible SBC) |
 | State queries | Historical state by block tag | `latest`/`pending`/`safe`/`finalized` return current state; historical block numbers rejected (error `-32000`) |
 | SBC decimals | — | 6 decimals (NOT 18) |
@@ -220,7 +222,7 @@ Always be explicit about:
 ### 4. Watch for production gotchas
 Before shipping, review [gotchas.md](references/gotchas.md) for:
 - Wallet compatibility (MetaMask is the only wallet that reliably adds Radius)
-- Nonce collision handling under concurrent load
+- Nonce management for unmanaged concurrent sends from one wallet (contiguous-nonce batches like `forge script --broadcast` need no special handling)
 - Block number is a timestamp (use BigInt, never parseInt)
 - Transaction receipts can be null even for confirmed transactions
 - EIP-2612 permit domain must match exactly: `{ name: "Stable Coin", version: "1" }`

plugins/radius/skills/radius-dev/references/gotchas.md

@@ -132,11 +132,13 @@ if (!receipt) {
 
 ---
 
-## 7. Nonce collisions under concurrent load
+## 7. Nonce management for concurrent sends from one wallet
 
-When sending multiple transactions from the same wallet (hot wallet, settlement wallet), concurrent sends cause nonce errors. Radius enforces strict sequential nonces.
+Batches with pre-assigned contiguous nonces land fine — Radius's pseudo-mempool accepts and orders them. A single `forge script --broadcast` deploying many contracts confirms all of them in one run (verified: a 29-transaction script landed with contiguous nonces, 29/29 successful). **You do not need to deploy one contract at a time, run `--slow`, or add fixed delays between transactions.**
 
-**Solution: serial queue + nonce retry.**
+The one case that still needs care is firing *unmanaged concurrent* transactions from the same wallet — e.g. a hot/settlement wallet that calls `sendTransaction` from many requests at once without coordinating nonces. As on any EVM chain, those can race and collide because each read of the pending nonce returns the same value before the earlier tx is accounted for.
+
+For that case, let viem manage nonces (it tracks them per account by default), or serialize sends through a queue and retry on the occasional collision:
 
 ```typescript
 function isNonceError(err: any): boolean {
@@ -172,7 +174,7 @@ async function sendWithRetry(
 }
 ```
 
-Also add a ~200ms delay between consecutive transactions. Without it, the RPC sometimes returns stale nonce values.
+This applies only to unmanaged concurrent sends from a single wallet — not to normal sequential sends or pre-signed contiguous-nonce batches, both of which land without special handling.
 
 ---
 
@@ -422,6 +424,15 @@ Best practice: read chain ID dynamically from the connected provider rather than
 
 ---
 
+## 22. Some standard read methods are unsupported (`eth_getProof`, `eth_getBlockReceipts`)
+
+Two standard Ethereum read methods return error `-33000` on Radius:
+
+- **`eth_getProof`** — Radius stores state across a parallelized, sharded infrastructure with no single global Merkle-Patricia trie, so it does not issue state proofs; its instant, deterministic finality removes the need for them. Read state directly with `eth_getBalance`, `eth_getCode`, and `eth_getStorageAt`.
+- **`eth_getBlockReceipts`** — Radius executes transactions individually, not in blocks (the block number is wall-clock time for tooling compatibility), so "every receipt in a block" is not a meaningful unit. To fetch a block's receipts, enumerate its transactions with `eth_getBlockByNumber` (full) and call `eth_getTransactionReceipt` for each; for event indexing of known contracts, use address-filtered `eth_getLogs` (see #18).
+
+---
+
 ## Quick reference: environment variables
 
 | Variable | Required | Description |

plugins/radius/skills/radius-dev/references/resources.md

@@ -80,7 +80,7 @@
 - [EIP-2930](https://eips.ethereum.org/EIPS/eip-2930) — Access lists
 - [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844) — Blob transactions
 - [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702) — Set EOA account code
-- [EIP-7966](https://eips.ethereum.org/EIPS/eip-7966) — `eth_sendRawTransactionSync` (synchronous tx submission; supported on Radius)
+- [EIP-7966](https://eips.ethereum.org/EIPS/eip-7966) — `eth_sendRawTransactionSync` (synchronous tx submission; on Radius the sync receipt is instant + final, no reorg)
 
 ## Wallet Integration
 

plugins/radius/skills/radius-dev/references/typescript-viem.md

@@ -327,7 +327,7 @@ const recipients = [
   '0x90F79bf6EB2c4f870365E785982E1f101E93b906',
 ] as const;
 
-// Send sequentially (safer — avoids nonce collisions)
+// Send sequentially (simplest — no nonce coordination needed)
 const hashes: `0x${string}`[] = [];
 for (const to of recipients) {
   const hash = await walletClient.sendTransaction({
@@ -343,7 +343,7 @@ const receipts = await Promise.all(
 );
 ```
 
-> **Gotcha:** If you send concurrent transactions from the same wallet, you will hit nonce collisions. Radius enforces strict sequential nonces. Always send sequentially from a single wallet, or use a nonce-aware queue. See [gotchas.md](gotchas.md#7-nonce-collisions-under-concurrent-load).
+> **Gotcha:** *Unmanaged* concurrent sends from the same wallet can collide on the nonce — as on any EVM chain, parallel calls may each read the same pending nonce before the earlier tx is accounted for. Let viem manage nonces (its default), serialize through a queue, or pre-assign contiguous nonces. Pre-signed contiguous-nonce batches (e.g. `forge script --broadcast`) land fine — you do **not** need to send one at a time or add delays. See [gotchas.md](gotchas.md#7-nonce-management-for-concurrent-sends-from-one-wallet).
 
 For batching **reads**, use Multicall3 (deployed at `0xcA11bde05977b3631167028862bE2a173976CA11`):
 
@@ -511,6 +511,8 @@ async function transfer(
 
 Radius supports `eth_sendRawTransactionSync` (EIP-7966), which submits a transaction and waits for the receipt in a single RPC call — roughly 50% less latency than the standard `sendTransaction` + `waitForTransactionReceipt` polling pattern.
 
+On Radius, what makes `eth_sendRawTransactionSync` valuable is what the returned receipt means: because Radius has instant finality, the sync receipt is fast **and final** (~100ms, no reorg). On a typical L2 the equivalent sync receipt reflects only inclusion (~460ms in our testing) and can reorg until it settles on L1.
+
 ```typescript
 import { serializeTransaction, signTransaction } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';

plugins/radius/skills/x402/SKILL.md

@@ -305,4 +305,4 @@ network defaults for a local or custom environment.
 **Cross-references to other skills:**
 - Chain definitions, RPC, wallet conventions, general Radius dev: **radius-dev** skill
 - Get testnet/mainnet SBC tokens: **dripping-faucet** skill
-- Production gotchas (EIP-2612 domain, v-value, nonce collisions): radius-dev [gotchas.md](../radius-dev/references/gotchas.md)
+- Production gotchas (EIP-2612 domain, v-value, nonce management): radius-dev [gotchas.md](../radius-dev/references/gotchas.md)