diff --git a/README.md b/README.md index 57d0ad0..9fed882 100644 --- a/README.md +++ b/README.md @@ -149,7 +149,7 @@ Worker used: "12D3KooWKPcNwR6EMq3sqm4sKtUKmZbMhPQ2dk1zr8YNgjdu9Xqn" Call will be to : https://frequent-sleek-river.ethereum-goerli.discover.quiknode.pro// ``` -Success! Go ahead and replace the `round-robin` mode with the `random` mode in your config file, stop and start the gateway and have a look at the different endpoint management. +Success! Go ahead and replace the `round-robin` mode with the `random` mode in your config file, stop and start the gateway and have a look at the different endpoint management. All available algorithms and their parameters are described in the [fRPC](#fRPC-Algorithms) section below. Congrats, you just took a major step toward keeping your dApp decentralized, available and performant! Now it's time to dive into the Fluence protocol and technology stack to learn how to improve upon the basic substrate. @@ -505,13 +505,13 @@ One little command is doing quite a bit so you don't have to. Let's work through Fluence CLI did a bunch of work for us behind the scenes and signing the transaction is a lot quicker than entering (virtual) credit card information. Fluence CLI organized a set of parameters needed by our Aqua scripts in [deals.aqua](./.fluence/aqua/deals.aqua) for easy importing. -Note that the deal's section in [fluence.yaml](./fluence.yaml) specifies the minimum and maximum workers that should be deployed under the *defaultWorker* namespace. Fluence CLI currently provides default values for min and max workers of one (1) and three (3), respectively. In the near future, you will be able to provide your spot price for service execution, hosting targets in the form of named capacity providers and more. Stay tuned! +Note that the deal's section in [fluence.yaml](./fluence.yaml) specifies the minimum and maximum workers that should be deployed under the *defaultWorker* namespace. Fluence CLI currently provides default values for min and max workers of one (1) and three (3), respectively. In the near future, you will be able to provide your spot price for service execution, hosting targets in the form of named capacity providers and more. -### fRPC Algorithms +### fRPC Aqua Code -Now that we have our services deployed and ready for action, it's time to look at Aqua, which is utilized by the Gateway to bridge HTTP to/from libp2p. The fRPC substrate comes with basic implementations of several algorithms useful in mitigating failure as the result of availability and lack of trustlessness with respect to RPC endpoints and possibly peers. Before we dive into the algorithms, let's have a look at the Aqua code and structure. +Now that we have our services deployed and ready for action, it's time to look at Aqua, which is utilized by the Gateway to bridge HTTP to/from libp2p. Let's have a look at the Aqua code and structure. -[rpc.aqua]("./../gateway/aqua/rpc.aqua") contains the necessary dependencies and algorithms. +[rpc.aqua]("./gateway/aqua/rpc.aqua") contains the necessary dependencies and algorithms. ```aqua -- rpc.aqua @@ -525,6 +525,19 @@ import "@fluencelabs/spell/spell_service.aqua" Two of the dependencies (should) stand out: *deals.aqua* and *services.aqua* as they are local files located in the project *.fluence* directory: *services.aqua* contains the interface exports from the *eth-rpc* wasm module and *deals.aqua* maps the values from *deployed.yaml* to data structures usable by your aqua code. Since these files are dynamically generated by Fluence CLI, you need to (re-) compile your Aqua after every change to your Wasm code or deal deploy updates. For all things Aqua refer to the [Aqua book](https://fluence.dev/docs/aqua-book/introduction), the [aqua playground](https://github.com/fluencelabs/aqua-playground) and the respective repos: [aqua-lib](https://github.com/fluencelabs/aqua-lib), [registry](https://github.com/fluencelabs/registry), [spell](https://github.com/fluencelabs/spell). +### fRPC Gateway Configuration + +The gateway config file, e.g., [quickstart_config.json](./configs/quickstart_config.json), contains the parameters necessary for the gateway to connect to the Fluence p2p network and to configure the gateway's behavior. The gateway config file is a json file with the following parameters: + +* *providers*: an array of RPC endpoint urls, e.g., Infura, Alchemy, Ankr, etc. +* *mode*: one of "random", "round-robin" or "quorum" to specify the endpoint selection algorithm +* *relay*: the Fluence p2p network relay address for [js-client](https://github.com/fluencelabs/js-client) to use +* *port*: the port the gateway listens on +* other parameters related to the fRPC Algorithms, see below + +### fRPC Algorithms + +The fRPC substrate comes with basic implementations of several algorithms useful in mitigating failure as the result of availability and lack of trustlessness with respect to RPC endpoints and possibly peers. #### Random @@ -559,6 +572,10 @@ We want to execute our Aqua program on the peer of the client, i.e. the gateway' **Use: Set `mode` to "round-robin" in your gateway config file** +[Config Parameters](#fRPC-Gateway-Configuration): +* *counterServiceId*: the service id of the counter service +* *counterPeerId*: the peer id of the counter service + ```aqua func roundRobin(uris: []string, method: string, jsonArgs: []string, counterServiceId: string, counterPeerId: string, callFunc: string, string, []string -> JsonString) -> JsonString: on counterPeerId: --< 1 @@ -576,12 +593,17 @@ func roundRobin(uris: []string, method: string, jsonArgs: []string, counterServi <- result ``` -A round robin algorithm cycles through the different options usually in a predictable manner. This substrate implementation is no different. To keep the state of the *cycle index*, we use a counter based on a local, [js-client](https://github.com/fluencelabs/js-client) based service [implementation]("./gateway/src/index.js) (1). Here, the peer executing the *Counter* service is the (local) client-per implemented by the gateway. Note that the state of the counter is limited to the life of the gateway. With the incremented counter in place, we had to our relay (2), determine our worker (3) and provider (4) indexes, call for the service execution (5), log and return the result. +A round robin algorithm cycles through the different options usually in a predictable manner. This substrate implementation is no different. To keep the state of the *cycle index*, we use a counter based on a local, [js-client](https://github.com/fluencelabs/js-client) based service [implementation]("./gateway/src/index.js) (1). Here, the peer executing the *Counter* service is the (local) client-peer implemented by the gateway. Note that the state of the counter is limited to the life of the gateway. With the incremented counter in place, we had to our relay (2), determine our worker (3) and provider (4) indexes, call for the service execution (5), log and return the result. #### Quorum **Use: Set `mode` to "quorum" in your gateway config file** +[Config Parameters](#fRPC-Gateway-Configuration): +* *quorumServiceId*: the service id of the quorum service +* *quorumPeerId*: the peer id of the quorum service +* *quorumNumber*: the number of results that must be equal to determine a quorum result + ```aqua func quorum( uris: []string, quorumNumber: u32, timeout: u32, method: string, jsonArgs: []string, quorumServiceId: string, quorumPeerId: string,