diff --git a/quic-forward-proxy/README.md b/quic-forward-proxy/README.md index 8d6f0494..21263d3e 100644 --- a/quic-forward-proxy/README.md +++ b/quic-forward-proxy/README.md @@ -1,12 +1,22 @@ +# Welcome to the Lite RPC QUIC Forward Proxy Sub-Project! + + +Project Info +---------------- +* Status: __experimental__ - Feedback welcome (Solana-Discord: _grooviegermanikus_) +* [Lite RPC QUIC Forward Proxy](https://github.com/blockworks-foundation/lite-rpc/tree/main/quic-forward-proxy) +* [Lite RPC](https://github.com/blockworks-foundation/lite-rpc/) + + + Purpose ------- -This component (__quic-forward-proxy__) can be optionally used along with one or multiple Lite RPC micro-service instances. -The Lite RPC services need to be reconfigured to send transactions via __quic-forward-proxy__ instead of sending them directly to the solana tpu nodes. +This component (__quic-forward-proxy__) can be optionally used along with one or multiple Lite RPC micro-service instances to optimized and simplify sending transactions to Solana TPUs. Benefits: -* the __quic-forward-proxy__ can batch transactions from multiple source and send them efficiently to the solana validator -* the __quic-forward-proxy__ can be configured with a validator identity keypair +* the __quic-forward-proxy__ can batch transactions from multiple source and send them _efficiently_ to the Solana validator +* the __quic-forward-proxy__ can be optionally configured with a validator identity keypair: * connections to TPU will be privileged (__staked connections__) * keypair can be kept in one place while the Lite RPC instances can benefit from the staked connection @@ -19,7 +29,7 @@ Prepare: choose a proxy port (e.g. 11111) and bind address of appropriate (minim # unstaked solana-lite-rpc-quic-forward-proxy --proxy-listen-addr 127.0.0.1:11111 # staked - solana-lite-rpc-quic-forward-proxy --proxy-listen-addr 127.0.0.1:11111 --identity-keypair /pathto-test-ledger/validator-keypair.json + solana-lite-rpc-quic-forward-proxy --proxy-listen-addr 127.0.0.1:11111 --identity-keypair /pathto/validator-keypair.json ``` 2. run lite-rpc ```bash @@ -50,7 +60,7 @@ Local Development / Testing --------------------------- ### Rust Integration Test -Use integrated testing in __quic_proxy_tpu_integrationtest.rs__. +Use integrated testing in __quic_proxy_tpu_integrationtest.rs__ for fast feedback. ### Local Setup With Solana Test Validator 1. run test-validator (tested with 1.16.1) @@ -75,17 +85,22 @@ Use integrated testing in __quic_proxy_tpu_integrationtest.rs__. Implementation Details ---------------------- -* the __proxy__ is designed to be light-weight and stateless (no persistence) -* note: only one instance of the __proxy__ should talk to the TPU nodes at a time to be able to correctly comply with the validator quic policy +* _proxy_ expects clients to send transactions via QUIC using the __proxy request format__: + * array of transactions (signature and raw bytes) + * array of tpu target nodes (address:port and identity public key) +* the _proxy_ is designed to be light-weight and stateless (no persistence) +* note: only one instance of the _proxy_ should talk to the TPU nodes at a time to be able to correctly comply with the validator quic policy * outbound connections (to TPU): - * __proxy__ tries to maintain active quic connections to recent TPU nodes - * __proxy__ will maintain multiple quic connection per TPU according to the solána validator quic policy -* __proxy__ will use lightweight quic streams to send the transactions - * inbound traffic (from Lite RPC) - * __proxy__ supports only quic ATM but that could be extended to support other protocols - * __proxy__ will perform client authentication by TLS (see [issue](https://github.com/blockworks-foundation/lite-rpc/issues/167)) + * _proxy_ tries to maintain active quic connections to recent TPU nodes using transparent reconnect + * _proxy_ will maintain multiple quic connection per TPU according to the Solana validator quic policy + * _proxy_ will use lightweight quic streams to send the transactions +* inbound traffic (from Lite RPC) + * client-proxy-communcation is done via QUIC using a custom wire format + * _proxy_ supports only quic ATM but that could be extended to support other protocols + * _proxy_ should perform client authentication by TLS (see [issue](https://github.com/blockworks-foundation/lite-rpc/issues/167)) +* _proxy_ uses a single queue (channel) for buffering the transactions from any inbound connection * TPU selection / Leader Schedule - * the __proxy__ will not perform any TPU selection; the TPU target nodes __MUST__ be selected by the __client__ (Lite RPC) and not by the __proxy__ + * the _proxy_ will not perform any TPU selection; the TPU target nodes __MUST__ be selected by the __client__ (Lite RPC) and not by the _proxy_ * pitfall: the TPU target node list might become stale if the transactions are not sent out fast enough ### Example Output from _Solana Validator_: @@ -98,10 +113,18 @@ Implementation Details [2023-06-26T15:16:18.430854000Z DEBUG solana_streamer::nonblocking::quic] stream error: ApplicationClosed(ApplicationClose { error_code: 0, reason: b"done" }) ``` -solana validator quic policy +Solana Validator QUIC Policy ---------------------------- -TPU has complex logic to assign connection capacity to TPU clients; this considers stake vs unstaked connections, per peer/per node limits, QUIC stream limits (see solana quic.rs) +TPU has complex logic to assign connection capacity to TPU clients (see Solana quic.rs) +* it purges connections +* it limits number of parallel quic streams +* it considers stake vs unstaked connections (validator identity signature in QUIC TLS certificate, see Solana get_remote_pubkey+get_pubkey_from_tls_certificate) +* it keeps connections on a per peer address / peer identity basis +* ... + +## License & Copyright + +Copyright (c) 2022 Blockworks Foundation + +Licensed under the **[AGPL-3.0 license](/LICENSE)** -Project Info ----------------- -* [Lite RPC](https://github.com/blockworks-foundation/lite-rpc/) \ No newline at end of file