# BlockFerret direct reads with automatic proxy fallback

The standard wallet RPC URL remains `https://rpc.blockferret.win`. Unmodified
wallets use the server proxy. Automatic fallback after an HTTP redirect requires
client support: once a wallet contacts the public provider, the BlockFerret
server cannot see or repair that connection's failure.

For a compatible custom client, browser app or wallet integration, use the
dependency-free [private-rpc-client.mjs](https://blockferret.win/assets/examples/private-rpc-client.mjs).
It runs in Node.js 20+ or a browser with Fetch. It handles already signed
transactions; it does not collect keys, sign for MetaMask, override another
wallet's internal RPC routing, or change any wallet network configuration.

```js
import { createPrivateRPCClient } from './private-rpc-client.mjs';

const rpc = createPrivateRPCClient();
const balance = await rpc.request({
  method: 'eth_getBalance',
  params: ['0xYOUR_ADDRESS', 'latest'],
});
// For an already signed transaction:
// const hash = await rpc.request({method: 'eth_sendRawTransaction', params: [raw]});
```

For ordinary public reads, the helper calls `/?read_redirect=1`. The edge can
return HTTP 307 to an approved, currently healthy public provider. The client's
device then contacts that RPC directly, using the device's outbound IP rather
than the BlockFerret VPS IP. The upstream's own policies still apply.

If redirects are unsupported, a CORS/network error occurs, the direct request
times out, or the provider throttles or returns an invalid reply, the helper
retries that read once through the original proxy URL. Execution reverts and
invalid user parameters are returned without shopping for another result.

Private writes, nonce reads and mixed read/write batches use the original URL
with redirects disabled. An ambiguous private write timeout is never retried
automatically or sent to a public RPC; check the receipt/status and nonce before
resubmitting. The helper also provides `sendBatch([...])`, returning individual
JSON-RPC responses for at most 16 members.

Do not add `?read_redirect=1` to a normal wallet URL expecting universal automatic
fallback. This flag alone cannot provide it. Use the helper or equivalent client
behavior, and test the particular wallet/client before enabling direct reads.

## Shared-node last resort

The proxy normally uses the public pool. If every currently eligible public
candidate fails or is unavailable, it can use a separately verified Switch
PulseChain read RPC. This applies to ordinary proxy users as well as helper
fallback requests. It never routes transaction submissions to that RPC.

The shared node has deliberately strict limits: 6 fallback reads/minute/IP,
60 globally including health checks, one request in flight and a 750 ms timeout.
Simulations are capped at 500,000 gas with no state overrides; fee history is
limited to 32 blocks and 20 percentiles. Stale or lagging fallback state is not
used. Requests can still fail when these limits or the overall deadline apply.

No broader caching layer was added. The existing small 500 ms fee/head cache is
unchanged. The shared-node address is never returned to clients in a redirect.