diff --git a/README.md b/README.md index 7395627..e20e3f8 100644 --- a/README.md +++ b/README.md @@ -42,11 +42,11 @@ fRPC substrate allows existing dApps to be upgraded to decentralized RPC while n Upcoming Fluence hackathons with fRPC bounties: -* [ETHDenver 2023](https://www.ethdenver.com/). See Fluence [events](https://www.notion.so/fluencenetwork/ETHDenver-Fluence-Team-66edb7a1a2624475844bfc11ff8c5756) and [bounty](https://github.com/fluencelabs/ethdenver-2023) repo for more info. +- [ETHDenver 2023](https://www.ethdenver.com/). See Fluence [events](https://www.notion.so/fluencenetwork/ETHDenver-Fluence-Team-66edb7a1a2624475844bfc11ff8c5756) and [bounty](https://github.com/fluencelabs/ethdenver-2023) repo for more info. ## Quickstart -Clone the repo, if you haven't done so already, and in the *gateway* directory, install the dependencies: +Clone the repo, if you haven't done so already, and in the _gateway_ directory, install the dependencies: ```bash npm i @@ -58,14 +58,14 @@ If you don't have Fluence CLI installed, do: npm -g i @fluencelabs/cli@unstable ``` -Before you proceed, you should have, say, three RPC endpoint urls, e.g., Infura, Alchemy and QuickNode, for the same EVM-based chain you are using in your dAPP. Update the `configs/quickstart_config.json` by providing your endpoint urls and ignore the rest of the parameters for now: +Before you proceed, you should have, say, three RPC endpoint urls, e.g., Infura, Alchemy and QuickNode, for the same EVM-based chain you are using in your dAPP. Update the `configs/quickstart_config.json` by providing your endpoint urls and ignore the rest of the parameters for now: ```json { "providers": [ - "", // <- replace - "", // <- replace - "" // <- replace and maybe add more + "", // <- replace + "", // <- replace + "" // <- replace and maybe add more ], "mode": "round-robin", "relay": "/dns4/stage.fluence.dev/tcp/19002/wss/p2p/12D3KooWMigkP4jkVyufq5JnDJL6nXvyjeaDNpRfEZqQhsG3sYCU", @@ -81,8 +81,15 @@ Before you proceed, you should have, say, three RPC endpoint urls, e.g., Infura Now start the gateway: -```bash +**Command**: + +``` npm -C gateway run run configs/quickstart_config.json +``` + +**Output**: + +```bash > @fluencelabs/aqua-eth-gateway@0.0.11 run > fluence aqua -i aqua/ -o aqua-compiled/ --js && node src/index.js configs/my_quickstart_config.json @@ -99,13 +106,19 @@ Server was started on port 3000 With the gateway ready for action, all you have to do is change your dApps HTTP transport url to `http://127.0.0.1:3000` and keep using your dApp as usual. In the absence of a dAPP, we can interact with the gateway from the command line: +**Command**: + ```bash curl http://127.0.0.1:3000 \ -X POST \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params": [],"id":100}' +``` -{"jsonrpc":"2.0","id":100,"result":"0x82b950" +**Output**: + +```bash +{"jsonrpc":"2.0","id":100,"result":"0x82b950"} # with the corresponding gateway log output Receiving request 'eth_blockNumber' @@ -115,14 +128,20 @@ Worker used: "12D3KooWKPcNwR6EMq3sqm4sKtUKmZbMhPQ2dk1zr8YNgjdu9Xqn" Call will be to : https://eth-goerli.g.alchemy.com/v2/ ``` -Since we have specified *round-robin* in our config file and have more than one endpoint url in play, re-running the json-rpc call should result in a different endpoint selection: +Since we have specified _round-robin_ in our config file and have more than one endpoint url in play, re-running the json-rpc call should result in a different endpoint selection: + +**Command**: ```bash curl http://127.0.0.1:3000 \ -X POST \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params": [],"id":100}' +``` + +**Output**: +```bash {"jsonrpc":"2.0","id":100,"result":"0x82b956"} # with the corresponding gateway log output @@ -132,7 +151,6 @@ peerId: 12D3KooWKDnWpCLPJrycSevracdEgGznfDPwG1g5CWbt8uccdL79 Counter: 2 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. @@ -143,9 +161,9 @@ Congrats, you just took a major step toward keeping your dAPP decentralized, ava Fluence's decentralized serverless protocol and solution stack allows developers to quickly create decentralized applications and protocols by distributing services for subsequent execution to peers of the open and permissionless Fluence peer-to-peer compute network. Specifically, developers: -* express their business logic in Rust code compiled to wasm32-wasi -* create a [Deal](https://fluence.dev/docs/build/glossary#deal), i.e., a construct that links on-chain contract economics and off-chain resources necessary for peers to run a service, which entails escrowing stablecoin, currently limited to (testnet) USDC, to the Deal contract -* deploy their Wasm modules plus linking instructions as a uniquely addressable *service* to p2p network storage, i.e., IPFS +- express their business logic in Rust code compiled to wasm32-wasi +- create a [Deal](https://fluence.dev/docs/build/glossary#deal), i.e., a construct that links on-chain contract economics and off-chain resources necessary for peers to run a service, which entails escrowing stablecoin, currently limited to (testnet) USDC, to the Deal contract +- deploy their Wasm modules plus linking instructions as a uniquely addressable _service_ to p2p network storage, i.e., IPFS With a Deal in place, resource owners, i.e., owner/operators of one or more peers, make a decision whether to host the service and if so, participate in the Deal by providing a stake to the Deal contract and pulling the corresponding service assets required for hosting from IPFS. As a matter of fact, peers utilize [Workers](https://fluence.dev/docs/build/glossary#worker), omitted from Figure 2 for simplicity reasons, to implement their side of a Deal. See Figure 2. @@ -186,7 +204,7 @@ sequenceDiagram ``` -While this sounds, and is, elaborate, *Fluence CLI*, see below, takes care of most of the scaffolding and workflow management for you. +While this sounds, and is, elaborate, _Fluence CLI_, see below, takes care of most of the scaffolding and workflow management for you. > At this point, the marketplace for Fluence's decentralized serverless isn't quite finished. The supply side has not been enabled and on the demand side, parameters are fixed for the testnet. That is, developers are not able to provide custom Deal parameters, such as willingness to pay for service execution. Instead, these parameters, i.e. price of execution per epoch and epoch duration, are hard-coded and used by Fluence CLI to create the corresponding Deal contract and transaction for you to sign. Moreover, economics are limited to the testnet using testnet tokens and throughout the EthDenver hackathon, resource owners may not claim their periodic share of revenue from the Deal's escrow. @@ -194,33 +212,33 @@ While this sounds, and is, elaborate, *Fluence CLI*, see below, takes care of mo To get going, you need to install and setup a few dependencies. -> Fluence tooling works on most *nix systems including OSX and Windows Linux Subsystem. At this time, Windows is not supported. +> Fluence tooling works on most \*nix systems including OSX and Windows Linux Subsystem. At this time, Windows is not supported. ### Off-chain Dependencies -* [node](https://nodejs.org/en/) 18 LTS -* [Fluence CLI](https://github.com/fluencelabs/fluence-cli) -* [Rust](https://www.rust-lang.org/tools/install) (optional; Fluence CLI will install if not already in your environment) -* For VSCode, there is a helpful [Aqua language support](https://marketplace.visualstudio.com/items?itemName=FluenceLabs.aqua) package available +- [node](https://nodejs.org/en/) 18 LTS +- [Fluence CLI](https://github.com/fluencelabs/fluence-cli) +- [Rust](https://www.rust-lang.org/tools/install) (optional; Fluence CLI will install if not already in your environment) +- For VSCode, there is a helpful [Aqua language support](https://marketplace.visualstudio.com/items?itemName=FluenceLabs.aqua) package available > This Fluence CLI install missing dependencies as needed ("lazy install"). If you want all your dependencies installed at once, use the `fluence dependencies i` command. ### On-chain Dependencies -* Wallectconnect compatible wallet, e.g., MetaMask, setup for and funded with: - * [Mumbai testnet](https://chainlist.org/chain/80001) parameters - * [Mumbai faucet](https://mumbaifaucet.com/) - * [Fluence USDC testnet faucet](https://faucet.fluence.dev/) +- Wallectconnect compatible wallet, e.g., MetaMask, setup for and funded with: + - [Mumbai testnet](https://chainlist.org/chain/80001) parameters + - [Mumbai faucet](https://mumbaifaucet.com/) + - [Fluence USDC testnet faucet](https://faucet.fluence.dev/) You will need Mumbai MATIC and Fluence (testnet) USDC. This is as good a time as any to head over to those faucets and get your allocations. As an experienced Web3 dev, you know it's good hygiene to set up a new account, say, fRPC-dev, for the Mumbai testnet and testnet tokens. ### RPC Endpoints -Since fRPC works with existing centralized or self-hosted RPC providers, you want at least three provider urls with appended API keys to *the* chain of your choice. Multi-chain support is currently not supported by fRPC Substrate (hint, hint to all you hackathoners). For Ethereum's Goerli testnet, for example: +Since fRPC works with existing centralized or self-hosted RPC providers, you want at least three provider urls with appended API keys to _the_ chain of your choice. Multi-chain support is currently not supported by fRPC Substrate (hint, hint to all you hackathoners). For Ethereum's Goerli testnet, for example: -* Infura: https://goerli.infura.io/v3/\/ -* Alchemy: https://eth-goerli.g.alchemy.com/v2/\/ -* QuickNode: https://frequent-sleek-river.ethereum-goerli.discover.quiknode.pro/\/ +- Infura: https://goerli.infura.io/v3/\/ +- Alchemy: https://eth-goerli.g.alchemy.com/v2/\/ +- QuickNode: https://frequent-sleek-river.ethereum-goerli.discover.quiknode.pro/\/ Each of the listed providers has a free account option and supports the API key in the url style, rather than the header, which is the current gateway implementation choice; a choice you should feel free to override and customize to your needs. @@ -246,42 +264,42 @@ Figure 3: Stylized Project Creation And Deployment Workflow With Fluence CLI DeployedService --> RunService: fluence run ``` -Fluence CLI uses multiple *yaml* config files. Below find references to the most important ones populated with parameters from our fRPC-Substrate project. You can find the schemas in the [schemas](./.fluence/schemas) directory. Note that Fluence CLI creates config files lazily, i.e., as needed. +Fluence CLI uses multiple _yaml_ config files. Below find references to the most important ones populated with parameters from our fRPC-Substrate project. You can find the schemas in the [schemas](./.fluence/schemas) directory. Note that Fluence CLI creates config files lazily, i.e., as needed. #### fluence.yaml -- the root project config file that manages version, dependencies, and more: ```yaml version: 2 -aquaInputPath: src/aqua/main.aqua # path where to look for default aqua files, you can change that -workers: # worker settings for deploy +aquaInputPath: src/aqua/main.aqua # path where to look for default aqua files, you can change that +workers: # worker settings for deploy defaultWorker: - services: [ eth_rpc ] -deals: # deal settings for deploy + services: [eth_rpc] +deals: # deal settings for deploy defaultWorker: - minWorkers: 1 # default min worker settings -- you want your service deployed ot at least 1 worker - targetWorkers: 3 # default max worker settings -- you want your service deployed ot at least 3 workers + minWorkers: 1 # default min worker settings -- you want your service deployed ot at least 1 worker + targetWorkers: 3 # default max worker settings -- you want your service deployed ot at least 3 workers hosts: defaultWorker: peerIds: - 12D3KooWJ4bTHirdTFNZpCS72TAzwtdmavTBkkEXtzo6wHL25CtE -relays: stage # Name of Fluence network used +relays: stage # Name of Fluence network used services: - eth_rpc: # service name - get: wasm-modules/ # and where to get the service config + eth_rpc: # service name + get: wasm-modules/ # and where to get the service config ``` #### service.yaml -- the service config file that manages module dependencies -You find this in the service directory root, i.e., *wasm-modules* in our case. +You find this in the service directory root, i.e., _wasm-modules_ in our case. ```yaml version: 0 -name: eth_rpc # name of the service which is referenced in fluence.yaml -modules: # modules included - facade: # service API module, see https://fluence.dev/docs/marine-book/marine-runtime/module-types/ for more info +name: eth_rpc # name of the service which is referenced in fluence.yaml +modules: # modules included + facade: # service API module, see https://fluence.dev/docs/marine-book/marine-runtime/module-types/ for more info get: eth-rpc - curl-adapter: # other modules + curl-adapter: # other modules get: curl-adapter ``` @@ -292,18 +310,17 @@ Each module includes a module.yaml file in its root, e.g., [eth_rpc](./wasm-modu ```yaml # curl-adapter/module.yaml version: 0 -type: rust # language used to code the module +type: rust # language used to code the module name: curl_adapter -mountedBinaries: # effector module specific: what mechanism is used to access host resources - curl: /usr/bin/curl # host path to binary mapped to the alias used in the module's FFI link section +mountedBinaries: # effector module specific: what mechanism is used to access host resources + curl: /usr/bin/curl # host path to binary mapped to the alias used in the module's FFI link section ``` The minimum key for a module file are: version, type and name. Effector modules, however, may need additional information such as [MountedBinaries](https://fluence.dev/docs/marine-book/marine-runtime/mounted-binaries). Such information needs to be manually added. - #### project-secrets.yaml, user-secrets.yaml -- the cryptographic key file -Fluence uses cryptographic keys in a variety of contexts including end-to-end encryption, client peer id determination and securing services. By default, Fluence CLI creates a keypair in *user-secrets.yaml*, which is placed in the global *.fluence* directory in your home directory. +Fluence uses cryptographic keys in a variety of contexts including end-to-end encryption, client peer id determination and securing services. By default, Fluence CLI creates a keypair in _user-secrets.yaml_, which is placed in the global _.fluence_ directory in your home directory. ```yaml # user-secrets.yaml @@ -316,7 +333,7 @@ keyPairs: defaultKeyPairName: auto-generated ``` -The default keys are available and used by all your projects unless you create a project-specific key pair with the `fluence key` command and saved in the *project-secrets.yaml* file in the project-local *.fluence* directory. Since we are in default mode for our current setup, *projects-secrets.yaml* is not populated. +The default keys are available and used by all your projects unless you create a project-specific key pair with the `fluence key` command and saved in the _project-secrets.yaml_ file in the project-local _.fluence_ directory. Since we are in default mode for our current setup, _projects-secrets.yaml_ is not populated. ```yaml # projects-secrets.yaml @@ -326,7 +343,7 @@ keyPairs: [] #### workers.yaml -This file, also located in the project *.fluence* directory, holds all the deployment information necessary to track your distributed resources both on- and off-chain. +This file, also located in the project _.fluence_ directory, holds all the deployment information necessary to track your distributed resources both on- and off-chain. ```yaml version: 0 @@ -344,11 +361,11 @@ See [FLuence CLI](https://github.com/fluencelabs/fluence-cli) for more details. ## Hacking On fRPC Substrate -Fluence's *fRPC Substrate* is a starter kit that includes all the components you need to quickly enable your dAPP with decentralized RPC using existing centralized RPC providers, e.g., Infura, Alchemy, QuickNode, etc., without touching your existing frontend Web3 code. fRPC substrate consists of the following code components, see Figure 4: +Fluence's _fRPC Substrate_ is a starter kit that includes all the components you need to quickly enable your dAPP with decentralized RPC using existing centralized RPC providers, e.g., Infura, Alchemy, QuickNode, etc., without touching your existing frontend Web3 code. fRPC substrate consists of the following code components, see Figure 4: -* RPC API "adapter" code written in Rust and compiled to wasm32-wasi modules that are deployable to any peer in the Fluence p2p network -* Aqua code for distributed algorithms, such as Random and Round Robin selection, using the distributed Wasm connectors for request-response handling over libp2p -* A gateway app server that bridges libp2p transport to the HTTP transport expected by your dAPPs' Web3 SDK, such as web3js, ethers, etc. Note that the expectation at this point is for you to *self-host* the gateway at a location of your choosing. +- RPC API "adapter" code written in Rust and compiled to wasm32-wasi modules that are deployable to any peer in the Fluence p2p network +- Aqua code for distributed algorithms, such as Random and Round Robin selection, using the distributed Wasm connectors for request-response handling over libp2p +- A gateway app server that bridges libp2p transport to the HTTP transport expected by your dAPPs' Web3 SDK, such as web3js, ethers, etc. Note that the expectation at this point is for you to _self-host_ the gateway at a location of your choosing. Figure 4: Stylized fRPC Use With dAPPs @@ -373,34 +390,48 @@ Figure 4: Stylized fRPC Use With dAPPs In order to use the fRPC substrate out-of-the-box or after customization, you need to: -* have three or more centralized RPC endpoints ready, where each provider url needs to contain the API key, e.g., -* deploy a deal -* deploy the service -* update the gateway configuration -* run the gateway -* use the gateway url in your web3 sdk's HTTP transport config +- have three or more centralized RPC endpoints ready, where each provider url needs to contain the API key, e.g., +- deploy a deal +- deploy the service +- update the gateway configuration +- run the gateway +- use the gateway url in your web3 sdk's HTTP transport config ### fRPC Wasm Components -fRPC Substrate comes with one *service* comprised of two Wasm modules, which you can find in the [wasm-modules]("./wasm-modules/") directory. The service is called 'eth_rpc' and the included modules are a [curl_adapater]("./../wasm-modules/curl-adapter") and [eth_rpc]("./../wasm-modules/eth-rpc"). The *curl_adapter* module is a generic, re-usable module allowing access a peer's curl binary, if permissioned by the peer, and exposes the *curl_request* function. Any modules requiring curl access may use the curl_adapter modules via [FFI linking](https://doc.rust-lang.org/nomicon/ffi.html) with the *curl_request* function. +fRPC Substrate comes with one _service_ comprised of two Wasm modules, which you can find in the [wasm-modules]("./wasm-modules/") directory. The service is called 'eth*rpc' and the included modules are a [curl_adapater]("./../wasm-modules/curl-adapter") and [eth_rpc]("./../wasm-modules/eth-rpc"). The \_curl_adapter* module is a generic, re-usable module allowing access a peer's curl binary, if permissioned by the peer, and exposes the _curl_request_ function. Any modules requiring curl access may use the curl*adapter modules via [FFI linking](https://doc.rust-lang.org/nomicon/ffi.html) with the \_curl_request* function. -The *eth_rpc* module manages the json-rpc requests and responses initiated and consumed by Aqua scripts as he result of some frontend event, e.g. our dAPP or curl request. Once available on peers of the Fluence p2p network, the *eth-rpc* services, aka RPC endpoint adapter, allows us to call one or more RPC endpoints using Aqua for choreography and composition of services. +The _eth_rpc_ module manages the json-rpc requests and responses initiated and consumed by Aqua scripts as he result of some frontend event, e.g. our dAPP or curl request. Once available on peers of the Fluence p2p network, the _eth-rpc_ services, aka RPC endpoint adapter, allows us to call one or more RPC endpoints using Aqua for choreography and composition of services. Before you can deploy your service, use `fluence build` in the root dir to compile each module's Rust code to wasm32-wasi output: +**Command**: + ```bash fluence build +``` + +**Output**: + +```bash # Making sure all services are downloaded... # Making sure all services are built... Finished release [optimized] target(s) in 0.61s ``` -See [target dir]("./target/wasm32-wasi/release") for *curl_adapter.wasm* and *eth_erpc.wasm*, respectively. With the wasm modules available, you can locally interact with them using [Marine REPL](https://crates.io/crates/mrepl): +See [target dir]("./target/wasm32-wasi/release") for _curl_adapter.wasm_ and _eth_erpc.wasm_, respectively. With the wasm modules available, you can locally interact with them using [Marine REPL](https://crates.io/crates/mrepl): `fluence service repl` +**Command**: + ```bash fluence service repl +``` + +**Output**: + +```bash ? Enter service name from fluence.yaml, path to a service or url to .tar.gz archive wasm-modules # Making sure service and modules are downloaded and built... Finished release [optimized] target(s) in 0.18s @@ -465,38 +496,59 @@ result: { 3> ``` -The *i* command lists all the exported interfaces from the wasm modules in Aqua instead of Rust notation. In *exported* functions you see the module namespace, e.g., *curl_adapter*, and exported functions, e.g., *curl_request*. To execute a function, use `call []`. +The _i_ command lists all the exported interfaces from the wasm modules in Aqua instead of Rust notation. In _exported_ functions you see the module namespace, e.g., _curl_adapter_, and exported functions, e.g., _curl_request_. To execute a function, use `call []`. ### Adding Modules To A Service -Regardless of your customization requirements, you probably will have no reason to modify the *curl_adapter* and *eth_rpc* modules. However, you may want to add new modules, or even services, to handle your additional business logic requirements. For example, you may want to capture RPC endpoint performance data, such as response times and availability, to some Web3 storage, e.g., IPFS or Ceramic, for further analysis to, say, derive a weighting scheme for endpoint selection. +Regardless of your customization requirements, you probably will have no reason to modify the _curl_adapter_ and _eth_rpc_ modules. However, you may want to add new modules, or even services, to handle your additional business logic requirements. For example, you may want to capture RPC endpoint performance data, such as response times and availability, to some Web3 storage, e.g., IPFS or Ceramic, for further analysis to, say, derive a weighting scheme for endpoint selection. Fluence CLI allows you to quickly create a new, or add an existing, module to your project. For example, +**Command**: + ```bash fluence module new --path ./wasm-modules demo-module +``` + +**Output**: + +```bash Successfully generated template for new module at demo-module ``` -Which created a Rust project in the *wasm-module/demo-module* directory ready for you to customize. When you're done, you add the new module to your service config, service.yaml: +Which created a Rust project in the _wasm-module/demo-module_ directory ready for you to customize. When you're done, you add the new module to your service config, service.yaml: + +**Command**: ```bash fluence module add +``` + +**Output**: + +```bash ? Enter path to a module or url to .tar.gz archive wasm-modules/demo ? Enter service name from fluence.yaml or path to the service directory wasm-modules Added demo to ~/localdev/fRPC-Substrate/wasm-modules/service.yaml ``` -The demo module is now part of the service and `fluence build`, for example, now compiles the *demo* module as part of the project build. You can create a new service with the `fluence service new` command. Note that the implication of creating a new service, possibly in a new project directory, is that you intend to deploy that service separately from the *eth-rpc* service. Of course, you will need to write Aqua code to be able to interact with your new module. +The demo module is now part of the service and `fluence build`, for example, now compiles the _demo_ module as part of the project build. You can create a new service with the `fluence service new` command. Note that the implication of creating a new service, possibly in a new project directory, is that you intend to deploy that service separately from the _eth-rpc_ service. Of course, you will need to write Aqua code to be able to interact with your new module. -To get rid of the demo project for now, use `fluence module remove` to unlink the module from the *fluence.yaml* and *service.yaml* files; the old *rm -r * gets rid of the code template. +To get rid of the demo project for now, use `fluence module remove` to unlink the module from the _fluence.yaml_ and _service.yaml_ files; the old _rm -r _ gets rid of the code template. ### Deploying A Service -With a service, in this case the *eth-rpc* service, ready for deployment, we simply use the `fluence deal deploy` command: +With a service, in this case the _eth-rpc_ service, ready for deployment, we simply use the `fluence deal deploy` command: + +**Command**: ```bash fluence deal deploy +``` + +**Output**: + +```bash Connecting to: /dns4/stage.fluence.dev/tcp/19004/wss/p2p/12D3KooWJ4bTHirdTFNZpCS72TAzwtdmavTBkkEXtzo6wHL25CtE # 1 if Deal is already in place update or create new Deal? @@ -538,18 +590,18 @@ created deals: One little command is doing quite a bit so you don't have to. Let's work through the process: -* once we launch `fluence deal deploy` we create a (new) Deal with both on-chain and off-chain activities -* for an up-to-date look, all service assets, i.e., modules, are (re-) compiled (1) -* the wasm modules and config are uploaded to IPFS node where deal-participating peer's workers can fetch the package by CID (2) -* get back CID and update local file(s) (3) -* if a deal is already in place, which was so you could run the Quickstart demo *quickly*, either update the existing deal or create a new one: **create a new one!** (4) -* now you have to get involved! you are presented with the uri to get metamask to ask you to sign your escrow payment to the contract (5). Copy and paste the uri to your browser and eventually, Metamask should pop-up with a signing request. The transaction displays only in hex, so double check the other request params to make sure you're signing the Mumbai transaction. This is what you should see: -![Sign TX](./images/sign_tx_metamask.png) -* once you signed the transaction and the contract was successfully updated, we are done! (6) +- once we launch `fluence deal deploy` we create a (new) Deal with both on-chain and off-chain activities +- for an up-to-date look, all service assets, i.e., modules, are (re-) compiled (1) +- the wasm modules and config are uploaded to IPFS node where deal-participating peer's workers can fetch the package by CID (2) +- get back CID and update local file(s) (3) +- if a deal is already in place, which was so you could run the Quickstart demo _quickly_, either update the existing deal or create a new one: **create a new one!** (4) +- now you have to get involved! you are presented with the uri to get metamask to ask you to sign your escrow payment to the contract (5). Copy and paste the uri to your browser and eventually, Metamask should pop-up with a signing request. The transaction displays only in hex, so double check the other request params to make sure you're signing the Mumbai transaction. This is what you should see: + ![Sign TX](./images/sign_tx_metamask.png) +- once you signed the transaction and the contract was successfully updated, we are done! (6) 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. The parametric details necessary to write Aqua scripts are save in [deals.aqua](./.fluence/aqua/deals.aqua) and serves as an important dependency in your Aqua scripts, as we'll see in the next section. -Note that the deal's section in [fluence.yaml](./fluence.yaml) specifies the number of workers that should be deployed specified by *targetWorkers*. The default is three (3) and can be customized. It is important to note that this is a desire not a guarantee as the actual deployment depends on the number of peers willing to participate in the deal. Currently, *all* the testnet peers operated by Fluence will participate in your deal. +Note that the deal's section in [fluence.yaml](./fluence.yaml) specifies the number of workers that should be deployed specified by _targetWorkers_. The default is three (3) and can be customized. It is important to note that this is a desire not a guarantee as the actual deployment depends on the number of peers willing to participate in the deal. Currently, _all_ the testnet peers operated by Fluence will participate in your deal. ### fRPC Algorithms @@ -567,8 +619,7 @@ import Registry, Record from "@fluencelabs/registry/registry-service.aqua" 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). - +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). #### Random @@ -597,7 +648,7 @@ func randomLoadBalancing(uris: []string, method: string, jsonArgs: []string, cal <- result ``` -We want to execute our Aqua program on the peer the client, i.e. the gateway's client peer, connected to (1). To setup for our randomized worker and endpoint selection, we need to get the workers running our eth-rpc service (2). We then calculate the index *workerNumber* as a random integer (3) and do the same for the endpoint provider (5). Finally, we call the chosen worker with the chosen endpoint url (6) and print our randomly chosen integers to the screen (7) before returning the result. +We want to execute our Aqua program on the peer the client, i.e. the gateway's client peer, connected to (1). To setup for our randomized worker and endpoint selection, we need to get the workers running our eth-rpc service (2). We then calculate the index _workerNumber_ as a random integer (3) and do the same for the endpoint provider (5). Finally, we call the chosen worker with the chosen endpoint url (6) and print our randomly chosen integers to the screen (7) before returning the result. #### Round robin @@ -620,7 +671,7 @@ 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. In order to keep 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. In order to keep 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. #### Quorum