From c650f934379702cbea614fa6762f0abaeefb7520 Mon Sep 17 00:00:00 2001 From: tomsanch Date: Wed, 6 May 2020 12:58:58 +0100 Subject: [PATCH 01/21] Update overview Updated various links, changed the name of the repo, fixed typos --- docs/{index.md => overview.md} | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) rename docs/{index.md => overview.md} (74%) diff --git a/docs/index.md b/docs/overview.md similarity index 74% rename from docs/index.md rename to docs/overview.md index e0bad797..0465a13d 100644 --- a/docs/index.md +++ b/docs/overview.md @@ -4,17 +4,17 @@ The Witnet protocol enables a network of computers to act as a **decentralized oracle** that retrieves, attests and delivers -information in behalf of **smart contracts** in a **tamper-resistant** +information on behalf of **smart contracts** in a **tamper-resistant** way. > This _Decentralized Oracle Network (DON)_ maintains and distributes a -> _block chain_ data structure that serves as a common ledger for the +> _blockchain_ data structure that serves as a common ledger for the > operation of the protocol as well as for the _wit_ token, which is -> central for incentivizing the network players to abide by the protocol +> crucial for incentivizing the network players to abide by the protocol > and make them liable for any misbehavior. — > [Witnet Whitepaper][whitepaper] -Active network participants **earn wit tokens** for fulfilling the data +Active network participants **earn WIT tokens** for fulfilling the data retrieval, attestation and delivery tasks coming from different smart contract platforms such as [Ethereum][ethereum]. @@ -31,8 +31,8 @@ contracts. ## Developers -The Witnet ecosystem welcomes developers of all kind of backgrounds: -from people who contribute to [Witnet-Rust] or [Sheikah] to those who +The Witnet ecosystem welcomes developers with all types of background: +from people who contribute to [Witnet-Rust], [Sheikah] or any of the community [Operator Tools] to those who want to [connect their Ethereum smart contracts to external APIs][ethereum]. Developers can: @@ -48,16 +48,17 @@ Developers can: charge of funding the development of Witnet-Rust and Sheikah, as well as fostering the thriving ecosystem around the Witnet protocol. -## Other stakeholders +## Other contributions The Witnet community is open to everyone. Even if you are not a developer or node operator, there are -[many things you can do][contributing] to spread the word! +[many things you can do][contributing] to contribute to the ecosystem! [apis-illustration]: assets/images/APIs.svg [ethereum]: try/use-from-ethereum [foundation]: https://witnet.foundation -[whitepaper]: https://witnet.io/static/witnet-whitepaper.pdf +[whitepaper]: https://witnet.io/witnet-whitepaper.pdf [run-a-node]: /try/run-a-node [contributing]: /developer/contributing [Witnet-Rust]: https://github.com/witnet/witnet-rust [Sheikah]: https://github.com/witnet/sheikah +[Operator Tools]: https://github.com/witnet/witnet-operator-tools From e16f6e1e6f092b7870aad551a960845308881bc7 Mon Sep 17 00:00:00 2001 From: tomsanch Date: Wed, 6 May 2020 13:46:24 +0100 Subject: [PATCH 02/21] Update and rename overview.md to Ecosystem.md --- docs/{overview.md => Ecosystem.md} | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) rename docs/{overview.md => Ecosystem.md} (90%) diff --git a/docs/overview.md b/docs/Ecosystem.md similarity index 90% rename from docs/overview.md rename to docs/Ecosystem.md index 0465a13d..cf605442 100644 --- a/docs/overview.md +++ b/docs/Ecosystem.md @@ -44,9 +44,7 @@ Developers can: ## Witnet Foundation -[Witnet Foundation][foundation] is the independent entity currently in -charge of funding the development of Witnet-Rust and Sheikah, as well -as fostering the thriving ecosystem around the Witnet protocol. +The Witnet Foundation is an independent entity, designated to fund the development of Witnet-Rust and Sheikah and foster a thriving and engaged ecosystem around the Witnet protocol. ## Other contributions The Witnet community is open to everyone. Even if you are not a @@ -55,7 +53,6 @@ developer or node operator, there are [apis-illustration]: assets/images/APIs.svg [ethereum]: try/use-from-ethereum -[foundation]: https://witnet.foundation [whitepaper]: https://witnet.io/witnet-whitepaper.pdf [run-a-node]: /try/run-a-node [contributing]: /developer/contributing From 4b8e7b37f7a956b97de6def08ee00cd3ddd125a3 Mon Sep 17 00:00:00 2001 From: tomsanch Date: Wed, 6 May 2020 14:54:00 +0100 Subject: [PATCH 03/21] Update introduction to Tutorial typos, grammar, link fixes --- docs/tutorials/bitcoin-price-feed/introduction.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/tutorials/bitcoin-price-feed/introduction.md b/docs/tutorials/bitcoin-price-feed/introduction.md index 7e6f5198..be4dab48 100644 --- a/docs/tutorials/bitcoin-price-feed/introduction.md +++ b/docs/tutorials/bitcoin-price-feed/introduction.md @@ -16,9 +16,9 @@ In this tutorial you will: - Compile and deploy the entire flow into a local Ethereum network. !!! tip "" - Remember: using Witnet from Ethereum is specially convenient because - you do not need to own or pay any Wit tokens: you pay the bridge - nodes using ETH and then they spend their own Wit tokens when + Remember: using Witnet from Ethereum is particularly convenient, as + you do not need to own or pay any WIT tokens: you pay the bridge + nodes using ETH and then they spend their own WIT tokens when posting your requests into Witnet in your behalf. ## How decentralized will this price feed be @@ -34,7 +34,7 @@ the data points it provides: - The price is averaged from two different public APIs, thus mitigating their influence in the final price. - The data is relayed by 4 different Witnet nodes, whose reported data - points get aggregated and averaged, filtering out any outliers so as + points are aggregated and averaged, filtering out any outliers so as to cancel any malicious reporter who may try to leverage a slight drift of the data point. From 31a8ac7ccd3b6a41b8f653eac54d291bb479f956 Mon Sep 17 00:00:00 2001 From: tomsanch Date: Wed, 6 May 2020 15:26:55 +0100 Subject: [PATCH 04/21] Update and rename aggregations.md to 3-aggregations.md --- .../{aggregations.md => 3-aggregations.md} | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) rename docs/tutorials/bitcoin-price-feed/{aggregations.md => 3-aggregations.md} (92%) diff --git a/docs/tutorials/bitcoin-price-feed/aggregations.md b/docs/tutorials/bitcoin-price-feed/3-aggregations.md similarity index 92% rename from docs/tutorials/bitcoin-price-feed/aggregations.md rename to docs/tutorials/bitcoin-price-feed/3-aggregations.md index ac8f6573..aa99c5af 100644 --- a/docs/tutorials/bitcoin-price-feed/aggregations.md +++ b/docs/tutorials/bitcoin-price-feed/3-aggregations.md @@ -8,7 +8,7 @@ ## What is an aggregator? Aggregators define how to reduce or merge the result of multiple sources -into a single data point. They are similar to Javascript's `.reduce()` +into a single data point. They are similar to JavaScript's `.reduce()` method or the [`fold` higher-order function][fold] from many programming languages. @@ -22,7 +22,7 @@ outliers by using one or more statistical primitives. - When a Witnet node gets a request assigned for resolution, it retrieves every source, applies the source companion scripts on the retrieved data, collects the results into an `Array`, and then apply - the aggregator on it, first running the filters and eventually the + the aggregator on it, first running the filters and later the reducer. @@ -57,8 +57,8 @@ function. ## Tally by average -For this tutorial, you will be using a tally function that is quite -equivalent to the aggregation function: +For this tutorial, we will be using a tally function that is quite +similar to the aggregation function: ```javascript // Filters out any value that is more than 1.5 times the standard @@ -72,8 +72,8 @@ const tally = new Witnet.Tally({ }) ``` -Note however that in this case the deviation filter is using a narrower -threshold (`1.0` instead of `1.5`). This is to make sure that malicious +Note, however, that in this case the deviation filter is using a narrower +threshold (`1.0` instead of `1.5`). This is to ensure that malicious data points will not affect the final result, and that the witnesses that produced such outliers will be punished for their misbehavior. From 08773f9167a136849bdd0e15f09400d6247b9e47 Mon Sep 17 00:00:00 2001 From: tomsanch Date: Wed, 6 May 2020 15:27:35 +0100 Subject: [PATCH 05/21] Rename fine-tuning.md to 4-fine-tuning.md --- .../bitcoin-price-feed/{fine-tuning.md => 4-fine-tuning.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/tutorials/bitcoin-price-feed/{fine-tuning.md => 4-fine-tuning.md} (100%) diff --git a/docs/tutorials/bitcoin-price-feed/fine-tuning.md b/docs/tutorials/bitcoin-price-feed/4-fine-tuning.md similarity index 100% rename from docs/tutorials/bitcoin-price-feed/fine-tuning.md rename to docs/tutorials/bitcoin-price-feed/4-fine-tuning.md From 0445976ca6f834eec5e62f7463576d5e144a2392 Mon Sep 17 00:00:00 2001 From: tomsanch Date: Wed, 6 May 2020 15:28:08 +0100 Subject: [PATCH 06/21] Rename introduction.md to 0-introduction.md --- .../bitcoin-price-feed/{introduction.md => 0-introduction.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/tutorials/bitcoin-price-feed/{introduction.md => 0-introduction.md} (100%) diff --git a/docs/tutorials/bitcoin-price-feed/introduction.md b/docs/tutorials/bitcoin-price-feed/0-introduction.md similarity index 100% rename from docs/tutorials/bitcoin-price-feed/introduction.md rename to docs/tutorials/bitcoin-price-feed/0-introduction.md From 3944b4c44e1b1bd3c8459c5c92a213d0127f2481 Mon Sep 17 00:00:00 2001 From: tomsanch Date: Wed, 6 May 2020 15:29:16 +0100 Subject: [PATCH 07/21] Update 3-aggregations.md --- docs/tutorials/bitcoin-price-feed/3-aggregations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/bitcoin-price-feed/3-aggregations.md b/docs/tutorials/bitcoin-price-feed/3-aggregations.md index aa99c5af..8456421e 100644 --- a/docs/tutorials/bitcoin-price-feed/3-aggregations.md +++ b/docs/tutorials/bitcoin-price-feed/3-aggregations.md @@ -130,4 +130,4 @@ Now it is time to put everything together and [discord]: https://discord.gg/X4uurfP [intro]: /tutorials/bitcoin-price-feed/introduction [fold]: https://en.wikipedia.org/wiki/Fold_(higher-order_function) -[next]: /tutorials/bitcoin-price-feed/fine-tuning +[next]: /tutorials/bitcoin-price-feed/4-fine-tuning From 894097692a4188f2a54e7109a09925207a73206a Mon Sep 17 00:00:00 2001 From: tomsanch Date: Wed, 6 May 2020 15:29:39 +0100 Subject: [PATCH 08/21] Rename 0-introduction.md to introduction.md --- .../bitcoin-price-feed/{0-introduction.md => introduction.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/tutorials/bitcoin-price-feed/{0-introduction.md => introduction.md} (100%) diff --git a/docs/tutorials/bitcoin-price-feed/0-introduction.md b/docs/tutorials/bitcoin-price-feed/introduction.md similarity index 100% rename from docs/tutorials/bitcoin-price-feed/0-introduction.md rename to docs/tutorials/bitcoin-price-feed/introduction.md From bdb13e7d39910b0cf3821a6792bd9eb6dabb9ac0 Mon Sep 17 00:00:00 2001 From: tomsanch Date: Wed, 6 May 2020 15:50:08 +0100 Subject: [PATCH 09/21] Update-4-fine-tuning Typos and grammatical errors --- .../bitcoin-price-feed/4-fine-tuning.md | 44 +++++++++---------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/tutorials/bitcoin-price-feed/4-fine-tuning.md b/docs/tutorials/bitcoin-price-feed/4-fine-tuning.md index 8b8a4542..1c89083b 100644 --- a/docs/tutorials/bitcoin-price-feed/4-fine-tuning.md +++ b/docs/tutorials/bitcoin-price-feed/4-fine-tuning.md @@ -50,10 +50,10 @@ The `witnesses` is the minimum number of Witnet nodes that will be resolving each specific request. In general, the higher the number of witnesses, the safer the request. -However, fees should be proportional to this number. +However, a higher number of witnesses generally means higher fees. The actual number of nodes that will resolve each request is guaranteed -to be equal than the specified number. If for some reason the +to be equal to the specified number. If for some reason the network fails to assign the request to enough nodes, it will be reassigned in every subsequent epoch to a different randomly-selected set of nodes until the required number is reached. @@ -62,11 +62,11 @@ The `backup_witnesses` is the number of Witnet nodes that will be used as a backup in case some of the originally assigned nodes fail to fulfill their commitments. -A higher `backup_witnesses` number implies more fees but also guarantees -that the request will be timely resolved. In the other hand, if you use -small `backup_witnesses` values, the risk is that your request will need +A higher `backup_witnesses` value corresponds with higher fees but also guarantees +that the request will be resolved in a timely fashion. On the other hand, +a small `backup_witnesses` value comes with the risk that your request will need to be retried many times and therefore the result may be potentially -inaccurate (in case the queried data point changes very fast). +inaccurate (especially if the queried data point changes rapidly). #### Optional arguments for `.setQuorum` @@ -82,32 +82,32 @@ The `.setQuorum` method accepts three more optional arguments: ) ``` -The `extra_commit_rounds` number is how many extra epochs will Witnet -nodes be given for commiting their partial results. A number of rounds +The `extra_commit_rounds` number specifies how many extra epochs Witnet +nodes will be given for committing their partial results. A number greater than `0` strengthens the chances of a Witnet request being resolved to a value instead of timing out. This parameter is actually an -upper threshold, i.e. the request will progress into reveal stage as +upper threshold, i.e. the request will progress into a reveal stage as soon as the number of commitments equals the number of required witnesses. If not set, this parameter defaults to `1`. This parameter has no impact on the price of the request. -The `extra_reveal_rounds` number is how many extra epochs will Witnet -nodes be given for revealing their partial results. A number of rounds +The `extra_reveal_rounds` number specifies how many extra epochs Witnet +nodes will be given to reveal their partial results. A number greater than `0` strengthens the security of a Witnet request by preventing miners from withholding reveal transactions—as the subsequent miners can include any reveal transactions withheld by a former miner. -This parameter is actually an upper threshold, i.e. the request will get +This parameter is actually an upper threshold, i.e. the request will be tallied and finalized as soon as the number of reveals equals the number of commitments. If not set, this parameter defaults to `1`. This parameter has no impact on the price of the request. -The `minimum_consensus` percentage allows to define a threshold for +The `minimum_consensus` percentage allows users to define a threshold for aborting resolution of a request if the witnessing nodes did not arrive -to broad consensus. That is, aggregator and tally functions will not be +at broad consensus. That is, aggregator and tally functions will not be applied if the ratio of valid values vs. errors is below this threshold. -*E.g. a `minimum_consensus` threshold of `70` requires a `70%` of the -witnesses to report a valid value, otherwise the result of the request -will be an error stating "insufficient consensus"*. If not set, this +*E.g. a `minimum_consensus` threshold of `70` requires `70%` of the +witnesses to report a valid value, otherwise the request +will result in an error, stating "insufficient consensus"*. If not set, this parameter defaults to `51`. ### Set the fees @@ -116,7 +116,7 @@ parameter defaults to `51`. ``` Witnet allows parametrization of many of the economic incentives that -affect the life cycle of your requests. Namely, those incentives are: +affect the life cycle of your requests. These incentives include: - `request_fee`: the amount of wit tokens that will be earned by the Witnet miner that publishes your request in a block. @@ -129,8 +129,8 @@ affect the life cycle of your requests. Namely, those incentives are: - `reveal_fee`: the amount of wit tokens that will be earned by Witnet miners for each valid reveal transaction they include in a block. - `tally_fee`: the amount of wit tokens that will be earned by the - Witnet miner that publishes in a block the tally of all the reveal - transactions related to your request. + Witnet miner that publishes the tally of all the reveal + transactions related to your request in a block. !!! question "How can I compute the total cost of a request?" The total cost of a Witnet request equals: @@ -152,7 +152,7 @@ affect the life cycle of your requests. Namely, those incentives are: .schedule(timestamp) ``` -Witnet requests can be scheduled for resolution in a particular date and +Witnet requests can be scheduled for resolution on a particular date and time in the future. Timestamps need to be provided as [POSIX timestamps][POSIX], i.e. @@ -224,4 +224,4 @@ Time to go ahead and [compile the request][next]. [discord]: https://discord.gg/X4uurfP [intro]: /tutorials/bitcoin-price-feed/introduction [POSIX]: https://en.wikipedia.org/wiki/Unix_time -[next]: /tutorials/bitcoin-price-feed/compiling +[next]: /tutorials/bitcoin-price-feed/5-compiling From 9847ee9345cfcabf31852e3889db95f4755e3aa7 Mon Sep 17 00:00:00 2001 From: tomsanch Date: Wed, 6 May 2020 15:55:12 +0100 Subject: [PATCH 10/21] Update and rename compiling.md to 5-compiling.md --- .../{compiling.md => 5-compiling.md} | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) rename docs/tutorials/bitcoin-price-feed/{compiling.md => 5-compiling.md} (86%) diff --git a/docs/tutorials/bitcoin-price-feed/compiling.md b/docs/tutorials/bitcoin-price-feed/5-compiling.md similarity index 86% rename from docs/tutorials/bitcoin-price-feed/compiling.md rename to docs/tutorials/bitcoin-price-feed/5-compiling.md index e9947b8e..f30d1a02 100644 --- a/docs/tutorials/bitcoin-price-feed/compiling.md +++ b/docs/tutorials/bitcoin-price-feed/5-compiling.md @@ -22,10 +22,10 @@ The `compile-requests` npm task will: 3. Try to compile the requests into Witnet bytecode. 4. Put the bytecode into auxiliary Solidity contracts that you can import into your own contracts. -5. Write [migration files][migrations] with default constructor +5. Write [migration files][deploy] with default constructor arguments that you can later customize. -If you go and look at the `contracts/requests` folder, you will notice a +If you now take a look in the `contracts/requests` folder, you will notice a new file called `BitcoinPrice.sol`. It will contain something like this: ```solidity @@ -40,7 +40,7 @@ contract BitcoinPriceRequest is Request { ``` As you can see, the contract contains the byte code for the request you -just wrote, exported as a Solidity contract that you can in turn import +just wrote, exported as a Solidity contract that you can then import and instantiate from your own contracts. Now the next step is pretty straightforward: @@ -53,6 +53,6 @@ Now the next step is pretty straightforward: tutorial. [discord]: https://discord.gg/X4uurfP -[migrations]: /tutorials/bitcoin-price-feed/migrations +[deploy]: /tutorials/bitcoin-price-feed/7-deploy [intro]: /tutorials/bitcoin-price-feed/introduction -[next]: /tutorials/bitcoin-price-feed/contract +[next]: /tutorials/bitcoin-price-feed/6-contract From 4ada441b66ae3e21feb4776a8bacc7fda1052441 Mon Sep 17 00:00:00 2001 From: tomsanch Date: Wed, 6 May 2020 16:35:16 +0100 Subject: [PATCH 11/21] Update 5-compiling.md --- docs/tutorials/bitcoin-price-feed/5-compiling.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/tutorials/bitcoin-price-feed/5-compiling.md b/docs/tutorials/bitcoin-price-feed/5-compiling.md index f30d1a02..a8c45fea 100644 --- a/docs/tutorials/bitcoin-price-feed/5-compiling.md +++ b/docs/tutorials/bitcoin-price-feed/5-compiling.md @@ -43,8 +43,7 @@ As you can see, the contract contains the byte code for the request you just wrote, exported as a Solidity contract that you can then import and instantiate from your own contracts. -Now the next step is pretty straightforward: -[write your main consumer contract][next]. +The next step is to [write your main consumer contract][next]. !!! question "Remember: You are not alone!" You are invited to join the [Witnet Community Discord][discord]. From adbca5864c0f1e29e1afe1abf5162321eec94d82 Mon Sep 17 00:00:00 2001 From: tomsanch Date: Wed, 6 May 2020 16:55:14 +0100 Subject: [PATCH 12/21] Update and rename 6-contract typos, grammar and link fixes --- .../{contract.md => 6-contract.md} | 29 +++++++++---------- 1 file changed, 14 insertions(+), 15 deletions(-) rename docs/tutorials/bitcoin-price-feed/{contract.md => 6-contract.md} (88%) diff --git a/docs/tutorials/bitcoin-price-feed/contract.md b/docs/tutorials/bitcoin-price-feed/6-contract.md similarity index 88% rename from docs/tutorials/bitcoin-price-feed/contract.md rename to docs/tutorials/bitcoin-price-feed/6-contract.md index 7f6d9d1b..d13f3b4a 100644 --- a/docs/tutorials/bitcoin-price-feed/contract.md +++ b/docs/tutorials/bitcoin-price-feed/6-contract.md @@ -14,18 +14,14 @@ point can be requested on demand by any interested party: - Anyone will be able to call a `requestUpdate` method in the contract that creates a new instance of the `BitcoinPrice.sol` contract and send it to Witnet. -- Once the request gets resolved, anyone will be able to call the -`completeUpdate` to actually write the result into the contract state. +- Once the request is resolved, anyone will be able to call the +`completeUpdate` and write the result into the contract state. -It is an assumption that the mere existence of a multiparty contract -that consumes the price feed will be enough incentive for the interested -parties to request and complete the update always that the price point -inside the contract differs from the actual market price more than the -cost of performing the Witnet request. +The assumption is that the mere existence of a multiparty contract that consumes the price feed will be enough incentive for the interested parties to request and complete the update so long as the price point inside the contract differs from the actual market price more than the cost of performing the Witnet request. ## Initialize a basic contract -Let's start by creating a really bare-bones contract and saving it as +Let's start by creating a bare-bones contract and saving it as `contracts/PriceFeed.sol`: ```js @@ -56,11 +52,11 @@ contract PriceFeed is UsingWitnet { } ``` -What you are doing here is quite straightforward: +Executing the above will: - Import `UsingWitnet.sol` so your contract is Witnet-enabled. - Import `BitcoinPrice.sol` so that you can instantiate the Witnet - request when needed. + request when necessary. - Make your contract inherit `UsingWitnet`. - Make the constructor receive the address of the Witnet Bridge Interface (`_wbi`) and pass it down to the `UsingWitnet` constructor @@ -86,7 +82,7 @@ function requestUpdate() public payable { ## Write the `resolveUpdate` method that reads the result of the Witnet request ```js -// The `witnetRequestAccepted` modifier comes with `UsingWitnet` and allows to +// The `witnetRequestAccepted` modifier comes with `UsingWitnet` and allows you to // protect your methods from being called before the request has been successfully // relayed into Witnet. function completeUpdate() public payable witnetRequestAccepted(lastRequestId) { @@ -105,7 +101,7 @@ function completeUpdate() public payable witnetRequestAccepted(lastRequestId) { emit Error(uint64(errorCode), errorMessage); } - // In any case, set `pending` to false so a new update can be requested + // In either case, set `pending` to false so a new update can be requested pending = false; } ``` @@ -130,10 +126,10 @@ contract PriceFeed is UsingWitnet { bool pending; // Tells if an update has been requested but not yet completed Request request; // The Witnet request object, is set in the constructor - // Allows logging errors + // Allow logging errors event Error(uint64, string); - // This constructor does a nifty trick to tell the `UsingWitnet` library where + // This constructor carries out a clever trick to tell the `UsingWitnet` library where // to find the Witnet contracts on whatever Ethereum network you use. constructor (address _wbi) UsingWitnet(_wbi) public { // Instantiate the Witnet request @@ -153,7 +149,7 @@ contract PriceFeed is UsingWitnet { lastRequestId = witnetPostRequest(request, _witnetRequestReward, _witnetResultReward); } - // The `witnetRequestAccepted` modifier comes with `UsingWitnet` and allows to + // The `witnetRequestAccepted` modifier comes with `UsingWitnet` and allows you to // protect your methods from being called before the request has been successfully // relayed into Witnet. function completeUpdate() public payable witnetRequestAccepted(lastRequestId) { @@ -179,6 +175,8 @@ contract PriceFeed is UsingWitnet { ``` +We can now [prepare to deploy!][next]. + !!! question "Remember: You are not alone!" You are invited to join the [Witnet Community Discord][discord]. Members of the Witnet community will be happy to answer your @@ -187,3 +185,4 @@ contract PriceFeed is UsingWitnet { [discord]: https://discord.gg/X4uurfP [intro]: /tutorials/bitcoin-price-feed/introduction +[next]: /tutorials/bitcoin-price-feed/7-deploy From 90325e08ed75412cbba43d1d88bfc70c5a8cc00e Mon Sep 17 00:00:00 2001 From: tomsanch Date: Wed, 6 May 2020 16:57:30 +0100 Subject: [PATCH 13/21] Delete Assumption Statement --- docs/tutorials/bitcoin-price-feed/6-contract.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/tutorials/bitcoin-price-feed/6-contract.md b/docs/tutorials/bitcoin-price-feed/6-contract.md index d13f3b4a..7d6ff593 100644 --- a/docs/tutorials/bitcoin-price-feed/6-contract.md +++ b/docs/tutorials/bitcoin-price-feed/6-contract.md @@ -17,8 +17,6 @@ point can be requested on demand by any interested party: - Once the request is resolved, anyone will be able to call the `completeUpdate` and write the result into the contract state. -The assumption is that the mere existence of a multiparty contract that consumes the price feed will be enough incentive for the interested parties to request and complete the update so long as the price point inside the contract differs from the actual market price more than the cost of performing the Witnet request. - ## Initialize a basic contract Let's start by creating a bare-bones contract and saving it as From 2be7c9513f7d5accb047098b12e3d6dfc7ea036b Mon Sep 17 00:00:00 2001 From: tomsanch Date: Wed, 6 May 2020 16:58:18 +0100 Subject: [PATCH 14/21] Update 6-contract.md --- docs/tutorials/bitcoin-price-feed/6-contract.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/bitcoin-price-feed/6-contract.md b/docs/tutorials/bitcoin-price-feed/6-contract.md index 7d6ff593..b3b2464a 100644 --- a/docs/tutorials/bitcoin-price-feed/6-contract.md +++ b/docs/tutorials/bitcoin-price-feed/6-contract.md @@ -173,7 +173,7 @@ contract PriceFeed is UsingWitnet { ``` -We can now [prepare to deploy!][next]. +We can now [prepare to deploy][next]! !!! question "Remember: You are not alone!" You are invited to join the [Witnet Community Discord][discord]. From 2411f6fb8a2fa71188d8217be40f18da7d16adf4 Mon Sep 17 00:00:00 2001 From: tomsanch Date: Wed, 6 May 2020 17:10:16 +0100 Subject: [PATCH 15/21] Update and rename "migrations" Typos and grammar fixes. --- .../{migrations.md => 7-deploy.md} | 32 +++++++++---------- 1 file changed, 15 insertions(+), 17 deletions(-) rename docs/tutorials/bitcoin-price-feed/{migrations.md => 7-deploy.md} (80%) diff --git a/docs/tutorials/bitcoin-price-feed/migrations.md b/docs/tutorials/bitcoin-price-feed/7-deploy.md similarity index 80% rename from docs/tutorials/bitcoin-price-feed/migrations.md rename to docs/tutorials/bitcoin-price-feed/7-deploy.md index e6f05aee..3fbbf861 100644 --- a/docs/tutorials/bitcoin-price-feed/migrations.md +++ b/docs/tutorials/bitcoin-price-feed/7-deploy.md @@ -1,4 +1,4 @@ -# 7. Migrate the contracts into an Ethereum network +# 7. Migrate and deploy the contracts into an Ethereum network !!! note "" *This article is part of the [beginner tutorial on creating a totally @@ -8,7 +8,7 @@ ## Compile your Solidity contract First off, run the `compile` command, which compiles your Solidity -contracts and recompiles the Witnet requests too: +contracts and then recompiles the Witnet requests: ```console tab="npm" npm run compile @@ -18,22 +18,21 @@ npm run compile yarn compile ``` -## You got migration scripts, for free! +## You have migration scripts by default! -Migration scripts are one of the nicest features of Truffle. They allow +Migration scripts are very useful in Truffle. They allow you to configure how your contracts will be deployed on different Ethereum networks, set your contract's constructor arguments and link dynamic dependencies. -The Witnet requests compiler that lives inside the Truffle box quietly -did something else than compiling your requests into Solidity -contracts—**it also wrote autogenerated migration scripts for your own +In addition to compiling your requests into Solidity, the Witnet request compiler that lives inside the Truffle box also +**wrote autogenerated migration scripts for your contracts**. If you look at the `migrations` folder, you should find these three files: - `1_initial_migration.js`: basic Truffle infrastructure migrations. -- `2_witnet_core.js`: deploys all the Witnet-related contracts in case - you are deploying on a local or private network; or dynamically link +- `2_witnet_core.js`: deploys all the Witnet-related contracts if + you are deploying on a local or private network; or dynamically links them if you are on a public network (Ethereum Mainnet, Rinkeby or Görli). - `3_user_contracts.js`: contains autogenerated migration scripts for @@ -42,8 +41,8 @@ these three files: Let's take a look at `migrations/3_user_contracts.js`: ```js -// This file was auto-generated by the Witnet compiler, any manual changes will be overwritten except -// each contracts' constructor arguments (you can freely edit those and the compiler will respect them). +// This file was auto-generated by the Witnet compiler; any manual changes will be overwritten except +// for the contracts' constructor arguments (you can freely edit those and the compiler will respect them). const Witnet = artifacts.require("Witnet") const WitnetRequestsBoardProxy = artifacts.require("WitnetRequestsBoardProxy") const PriceFeed = artifacts.require("PriceFeed") @@ -70,7 +69,7 @@ constructor argument called `_wbi`, just like `PriceFeed` has. If your consumer contract has additional constructor arguments, the compiler will create default values for them. -Before running any migration, please make sure to double-check the +Before running any migration, please make sure you double-check the default arguments that the compiler inserts for you, as they may not make any sense for your specific use case. @@ -82,8 +81,7 @@ compiler once again. ## Run the deployment -Deploying your contract into Truffle's own local Ethereum network is as -easy as it gets: +Deploying your contract into Truffle's own local Ethereum network is as simple as executing: ```console truffle migrate @@ -91,7 +89,7 @@ truffle migrate Please take into account that Truffle's own local network lacks any -bridging capability with Witnet. This means that it is a good option for +bridging capability with Witnet. This means that it is good for testing the migrations, but not for testing the entire workflow of your contracts. However, the Witnet community is working hard to overcome this limitation so that you can test your Witnet-connected contracts @@ -105,8 +103,8 @@ can deploy them into a public network using the `--network` flag: - `truffle migrate --network=goerli` deploys on the Ethereum Görli testnet. -Deploying on mainnet is not supported yet. Take a look at the [community -roadmap][roadmap] for more information on mainnet support. +Deploying on Mainnet is not supported yet. Take a look at the [community +roadmap][roadmap] for more information on Mainnet support. ## Interact with your contract From 6c8f6d2c6cc46e7ab4a05a11c08e8e600c611713 Mon Sep 17 00:00:00 2001 From: tomsanch Date: Wed, 6 May 2020 17:20:55 +0100 Subject: [PATCH 16/21] Update and rename "create-project" Typos and grammar changes --- .../{create-project.md => 2-create-project.md} | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) rename docs/tutorials/bitcoin-price-feed/{create-project.md => 2-create-project.md} (91%) diff --git a/docs/tutorials/bitcoin-price-feed/create-project.md b/docs/tutorials/bitcoin-price-feed/2-create-project.md similarity index 91% rename from docs/tutorials/bitcoin-price-feed/create-project.md rename to docs/tutorials/bitcoin-price-feed/2-create-project.md index 8d3a8532..15020031 100644 --- a/docs/tutorials/bitcoin-price-feed/create-project.md +++ b/docs/tutorials/bitcoin-price-feed/2-create-project.md @@ -18,8 +18,7 @@ truffle unbox witnet/truffle-box ``` You can keep reading this page to learn more about the Truffle box -boilerplate, but if you are feeling impatient you can [jump into the -next step][next]. +boilerplate, but if you are feeling impatient you can [jump straight to defining data sources][next]. ### Project folder structure @@ -49,4 +48,4 @@ You are now ready to move forward into [discord]: https://discord.gg/X4uurfP [truffle]: https://www.trufflesuite.com/ [intro]: /tutorials/bitcoin-price-feed/introduction -[next]: /tutorials/bitcoin-price-feed/sources +[next]: /tutorials/bitcoin-price-feed/3-sources From b653432b0032eb0cfa6ea7ded3abdad2da1eb431 Mon Sep 17 00:00:00 2001 From: tomsanch Date: Wed, 6 May 2020 17:21:43 +0100 Subject: [PATCH 17/21] Rename --- .../{2-create-project.md => 1-create-project.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename docs/tutorials/bitcoin-price-feed/{2-create-project.md => 1-create-project.md} (97%) diff --git a/docs/tutorials/bitcoin-price-feed/2-create-project.md b/docs/tutorials/bitcoin-price-feed/1-create-project.md similarity index 97% rename from docs/tutorials/bitcoin-price-feed/2-create-project.md rename to docs/tutorials/bitcoin-price-feed/1-create-project.md index 15020031..d0eebd44 100644 --- a/docs/tutorials/bitcoin-price-feed/2-create-project.md +++ b/docs/tutorials/bitcoin-price-feed/1-create-project.md @@ -48,4 +48,4 @@ You are now ready to move forward into [discord]: https://discord.gg/X4uurfP [truffle]: https://www.trufflesuite.com/ [intro]: /tutorials/bitcoin-price-feed/introduction -[next]: /tutorials/bitcoin-price-feed/3-sources +[next]: /tutorials/bitcoin-price-feed/2-sources From 6bd0a0ba1ae76d5fac384c0a549055465ca9d87e Mon Sep 17 00:00:00 2001 From: tomsanch Date: Wed, 6 May 2020 17:44:43 +0100 Subject: [PATCH 18/21] Update and rename sources Fix typos and grammar errors --- .../{sources.md => 2-sources.md} | 51 +++++++++---------- 1 file changed, 25 insertions(+), 26 deletions(-) rename docs/tutorials/bitcoin-price-feed/{sources.md => 2-sources.md} (76%) diff --git a/docs/tutorials/bitcoin-price-feed/sources.md b/docs/tutorials/bitcoin-price-feed/2-sources.md similarity index 76% rename from docs/tutorials/bitcoin-price-feed/sources.md rename to docs/tutorials/bitcoin-price-feed/2-sources.md index 7b98958f..f88607af 100644 --- a/docs/tutorials/bitcoin-price-feed/sources.md +++ b/docs/tutorials/bitcoin-price-feed/2-sources.md @@ -8,12 +8,12 @@ ## A quick intro on Witnet data sources **Data sources are each of the endpoints from which you want Witnet to -retrieve the data**. Most times, these will be the URLs of public APIs. +retrieve the data**. Most of the time, these will be the URLs of public APIs. There is no limit to the number of sources in a single Witnet -request—although the more sources, the higher the fees will be. +request - although the more sources, the higher the fees will be. -**Each source can have a companion script** that lists operations that +**Each source can have a companion script** that lists the operations we want the witnesses to apply on the retrieved data. This enables you to get the information of your interest extracted out of larger data structures like JSON objects. @@ -21,27 +21,27 @@ structures like JSON objects. ## Choose your sources carefully Just like your friends—and your enemies—your **data sources need to be -chosen wisely**. The *[Garbage In, Garbage Out][GIGO]* principle really +chosen wisely**. The *[Garbage In, Garbage Out][GIGO]* principle applies here. Regardless of the many *checks-and-balances*, well-designed incentives and security measures that the Witnet protocol implements, if the data sources in your Witnet requests are not -reliable, either will your contracts be. +reliable, your contracts won't be either. -The more data sources and the more reliable they are, the more -trust-mitigated your Witnet requests will become. That is, your +The more **reliable** data sources you list, the more +trust-mitigated your Witnet requests will become. In other words, your contracts will be more resilient to downtime, failure or corruption of each separate source. ## Introducing smart data sources -The scripting language used in Witnet requests is quite rich indeed: in +The scripting language used in Witnet requests is very flexible: in addition to selecting specific pieces of data, you can also transform -those so they are uniform and can be compared or aggregated together. -E.g. imagine a request that queries weather data. One source may use -Celsius and the other may use Fahrenheit, but you will tell Witnet to -transform one into another so they can be averaged. +them so they are uniform and can be compared or aggregated together. +For example, imagine a request that queries weather data. One source may use +Celsius and the other may use Fahrenheit. You can tell Witnet to +transform them both to Celcius so they can be averaged. -In this tutorial, you will be defining two data sources—one for querying +In this tutorial, you will be defining two data sources — one querying [Bitstamp] and the other for [CoinDesk]: ```javascript tab="Source 1: Bitstamp" @@ -53,7 +53,7 @@ const bitstamp = new Witnet.Source("https://www.bitstamp.net/api/ticker/") ```javascript tab="Source 2: CoinDesk" // Retrieves USD price of a bitcoin from CoinDesk's "bitcoin price index" API -// The JSON here is a bit more complex, thus more operators are needed +// The JSON here is a bit more complex, so more operators are needed const coindesk = new Witnet.Source("https://api.coindesk.com/v1/bpi/currentprice.json") .parseMapJSON() // Parse a `Map` from the retrieved `String` .getMap("bpi") // Get the `Map` value associated to the `bpi` key @@ -61,8 +61,7 @@ const coindesk = new Witnet.Source("https://api.coindesk.com/v1/bpi/currentprice .getFloat("rate_float") // Get the `Float` value associated to the `rate_float` key ``` -These scripts are quite self-explanatory, but there are a few details -that are worth noticing: +A few things worth noticing: - The operators and data types that can be used are defined by the [RADON domain-specific language][radon]. @@ -70,10 +69,10 @@ that are worth noticing: as you would expect from Javascript method chaining or [the builder pattern][builder]. - Source scripts always start with a `String`[^1]. -- Key-value data structures (roughly alike to Javascript *objects*, +- Key-value data structures (roughly similar to Javascript *objects*, Python *dictionaries* or Solidity *mappings*) are called *maps*. - Values in maps cannot be accessed directly by name as `.keyName` but - rather accessed through a call to one of the `.getArray("keyName")`, + instead through a call to one of the `.getArray("keyName")`, `.getBoolean("keyName")`, `.getInteger("keyName")`, `.getFloat("keyName")`, `.getInteger("keyName")`, `.getMap("keyName")` or `.getString("keyName")` operators. - The final return type of a script is that of its last operator. @@ -104,7 +103,7 @@ const coindesk = new Witnet.Source("https://api.coindesk.com/v1/bpi/currentprice .getFloat("rate_float") // Get the `Float` value associated to the `rate_float` key ``` -Notice the `import` instruction on top, which makes possible using all +Notice the `import` instruction at the top, which makes it possible to use all the tools that the Witnet Javascript library provides: ```javascript @@ -126,7 +125,7 @@ You are done with the sources for now. Let's move forward into [discord]: https://discord.gg/X4uurfP [intro]: /tutorials/bitcoin-price-feed/introduction -[next]: /tutorials/bitcoin-price-feed/aggregations +[next]: /tutorials/bitcoin-price-feed/3-aggregations [radon]: /protocol/data-requests/overview/#rad-object-notation-radon [builder]: https://en.wikipedia.org/wiki/Builder_pattern [GIGO]: https://en.wikipedia.org/wiki/Garbage_in,_garbage_out @@ -135,12 +134,12 @@ You are done with the sources for now. Let's move forward into [^1]: In future versions, the Witnet protocol will make no assumptions on what the data type of the server response will be for different data -sources. This will allow dealing with formats other than plain text, -such as multimedia files and any other kind of binaries. Therefore, -source scripts will start with `Bytes` as the input type and it will be +sources. This will allow for formats other than plain text, +such as multimedia files and any kind of binaries. Therefore, +source scripts will start with `Bytes` as the input type; it will be totally up to the requester to specify whether those bytes should be -interpreted as a `String`, `Integer` or whatnot. +interpreted as a `String`, `Integer` etc. -[^2]: One of the key features in the future RADON 2.0 version will be -implicit type casting, which will dramatically cut off the size of +[^2]: One of the key features in RADON 2.0 will be +implicit type casting, which will dramatically reduce the size of scripts. From a9798d20353baf60e9799c1d452dc81ce10f5c28 Mon Sep 17 00:00:00 2001 From: tomsanch Date: Wed, 6 May 2020 18:08:21 +0100 Subject: [PATCH 19/21] Update and rename recap.md to summary.md --- docs/tutorials/bitcoin-price-feed/recap.md | 12 ------------ docs/tutorials/bitcoin-price-feed/summary.md | 11 +++++++++++ 2 files changed, 11 insertions(+), 12 deletions(-) delete mode 100644 docs/tutorials/bitcoin-price-feed/recap.md create mode 100644 docs/tutorials/bitcoin-price-feed/summary.md diff --git a/docs/tutorials/bitcoin-price-feed/recap.md b/docs/tutorials/bitcoin-price-feed/recap.md deleted file mode 100644 index 04707cb4..00000000 --- a/docs/tutorials/bitcoin-price-feed/recap.md +++ /dev/null @@ -1,12 +0,0 @@ -# Quick recap on what you built - -**Congratulations!** - -You already built your first Solidity contract using -Witnet to trustlessly consume external APIs. - -What will you build next? Feel free to drop by the -[Witnet Community Discord][discord] and let us know any ideas, doubts or -suggestions. - -[discord]: https://discord.gg/X4uurfP diff --git a/docs/tutorials/bitcoin-price-feed/summary.md b/docs/tutorials/bitcoin-price-feed/summary.md new file mode 100644 index 00000000..77dd5ea8 --- /dev/null +++ b/docs/tutorials/bitcoin-price-feed/summary.md @@ -0,0 +1,11 @@ +# **Congratulations!** + +You've now built your first Solidity contract using +Witnet to trustlessly consume external APIs. + +What will you build next? Join the +[Witnet Community Discord][discord] or the [Witnet Community Telegram][telegram] and let us know any ideas or +suggestions you have. + +[discord]: https://discord.gg/X4uurfP +[telegram]: https://t.me/witnetio From d9535f68a0d43355cee796cc1a51e9bd2205da42 Mon Sep 17 00:00:00 2001 From: tomsanch Date: Wed, 6 May 2020 18:11:14 +0100 Subject: [PATCH 20/21] Updates to tutorial links --- mkdocs.yml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/mkdocs.yml b/mkdocs.yml index d2a26600..77c538fd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,14 +13,14 @@ nav: - Connect your Ethereum contracts to external APIs: try/use-from-ethereum.md - Tutorial: - Introduction: tutorials/bitcoin-price-feed/introduction.md - - 1. Create a new project: tutorials/bitcoin-price-feed/create-project.md - - 2. Adding data sources: tutorials/bitcoin-price-feed/sources.md - - 3. Define aggregator / tally: tutorials/bitcoin-price-feed/aggregations.md - - 4. Fine-tune the request: tutorials/bitcoin-price-feed/fine-tuning.md - - 5. Compile the request: tutorials/bitcoin-price-feed/compiling.md - - 6. Write the Solidity contract: tutorials/bitcoin-price-feed/contract.md - - 7. Deploy: tutorials/bitcoin-price-feed/migrations.md - - Recap: tutorials/bitcoin-price-feed/recap.md + - 1. Create a new project: tutorials/bitcoin-price-feed/1-create-project.md + - 2. Adding data sources: tutorials/bitcoin-price-feed/2-sources.md + - 3. Define aggregator / tally: tutorials/bitcoin-price-feed/3-aggregations.md + - 4. Fine-tune the request: tutorials/bitcoin-price-feed/4-fine-tuning.md + - 5. Compile the request: tutorials/bitcoin-price-feed/5-compiling.md + - 6. Write the Solidity contract: tutorials/bitcoin-price-feed/6-contract.md + - 7. Deploy: tutorials/bitcoin-price-feed/7-deploy.md + - Summary: tutorials/bitcoin-price-feed/summary.md - Community: - Roadmap: community/roadmap.md - Developer Docs: From 0d477e407bff6d941b5c521d312685e1d3fee015 Mon Sep 17 00:00:00 2001 From: tomsanch Date: Wed, 6 May 2020 18:12:20 +0100 Subject: [PATCH 21/21] Update link to create-project --- docs/tutorials/bitcoin-price-feed/introduction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/bitcoin-price-feed/introduction.md b/docs/tutorials/bitcoin-price-feed/introduction.md index be4dab48..6413872f 100644 --- a/docs/tutorials/bitcoin-price-feed/introduction.md +++ b/docs/tutorials/bitcoin-price-feed/introduction.md @@ -63,4 +63,4 @@ project][create-project]. [discord]: https://discord.gg/X4uurfP [pricefeed]: https://github.com/stampery-labs/witnet-pricefeed-example -[create-project]: /tutorials/bitcoin-price-feed/create-project +[create-project]: /tutorials/bitcoin-price-feed/1-create-project