├── .gitignore
├── .nojekyll
├── LICENSE
├── README.md
├── _coverpage.md
├── _media
    ├── favicon.ico
    ├── loading.gif
    ├── logo-transparent.jpeg
    ├── logo-transparent.png
    ├── overview.png
    ├── random.png
    ├── remix.png
    ├── staking.png
    └── streams_ui.png
├── _sidebar.md
├── contents
    ├── .nojekyll
    ├── architecture.md
    ├── blockchains
    │   ├── .nojekyll
    │   ├── bsc.md
    │   ├── ethereum.md
    │   ├── heco.md
    │   ├── ok.md
    │   └── polkadot.md
    ├── concepts.md
    ├── deploy.md
    ├── dev_tools.md
    ├── faq.md
    ├── feedback.md
    ├── sdk
    │   ├── examples.md
    │   └── introduction.md
    └── streams
    │   ├── addresses.md
    │   ├── api.md
    │   └── start.md
├── homepage.md
├── index.html
└── package-lock.json


/.gitignore:
--------------------------------------------------------------------------------
1 | *.*.swp
2 | 


--------------------------------------------------------------------------------
/.nojekyll:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/DOSNetwork/docs/fde4ef3ad71a1365f082c0181731a93b25496d9b/.nojekyll


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) 2018 DOS NETWORK
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | ## Docs
 2 | 
 3 | #### Documentation for developers to use oracle service and node runners to operate node software.
 4 | 
 5 | - Readable at https://dosnetwork.github.io/docs.
 6 | - Built with [Docsify](https://docsify.js.org/#/quickstart).
 7 | - Hostable on Github Pages or our own VPS.
 8 | 
 9 | 
10 | #### Contribution guide:
11 | - Install docsify: ```npm i docsify-cli -g```
12 | - Edit markdown files under contents/ directory.
13 | - Test locally by ```docsify serve .```
14 | 


--------------------------------------------------------------------------------
/_coverpage.md:
--------------------------------------------------------------------------------
 1 | <p align="center">
 2 |   <img width="300" height="300" src="https://raw.githubusercontent.com/DOSNetwork/docs/master/_media/logo-transparent.jpeg">
 3 | </p>
 4 | 
 5 | > Decentralized Oracle Service provides blockchains with real world data and computation power.
 6 | 
 7 | * :heavy_check_mark: Decentralized network without single point of failure
 8 | * :heavy_check_mark: VRF driven near real-time and verifiable result
 9 | * :heavy_check_mark: Fault tolerant open-membership protocol
10 | * :heavy_check_mark: Scalable and provably with low cost
11 | 
12 | [Getting Started](homepage)
13 | 


--------------------------------------------------------------------------------
/_media/favicon.ico:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/DOSNetwork/docs/fde4ef3ad71a1365f082c0181731a93b25496d9b/_media/favicon.ico


--------------------------------------------------------------------------------
/_media/loading.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/DOSNetwork/docs/fde4ef3ad71a1365f082c0181731a93b25496d9b/_media/loading.gif


--------------------------------------------------------------------------------
/_media/logo-transparent.jpeg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/DOSNetwork/docs/fde4ef3ad71a1365f082c0181731a93b25496d9b/_media/logo-transparent.jpeg


--------------------------------------------------------------------------------
/_media/logo-transparent.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/DOSNetwork/docs/fde4ef3ad71a1365f082c0181731a93b25496d9b/_media/logo-transparent.png


--------------------------------------------------------------------------------
/_media/overview.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/DOSNetwork/docs/fde4ef3ad71a1365f082c0181731a93b25496d9b/_media/overview.png


--------------------------------------------------------------------------------
/_media/random.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/DOSNetwork/docs/fde4ef3ad71a1365f082c0181731a93b25496d9b/_media/random.png


--------------------------------------------------------------------------------
/_media/remix.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/DOSNetwork/docs/fde4ef3ad71a1365f082c0181731a93b25496d9b/_media/remix.png


--------------------------------------------------------------------------------
/_media/staking.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/DOSNetwork/docs/fde4ef3ad71a1365f082c0181731a93b25496d9b/_media/staking.png


--------------------------------------------------------------------------------
/_media/streams_ui.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/DOSNetwork/docs/fde4ef3ad71a1365f082c0181731a93b25496d9b/_media/streams_ui.png


--------------------------------------------------------------------------------
/_sidebar.md:
--------------------------------------------------------------------------------
 1 | * [Home](homepage.md)
 2 | * Developers
 3 |   * Using Data Streams
 4 |     * [Quick Start](contents/streams/start.md)
 5 |     * [APIs](contents/streams/api.md)
 6 |     * [Contract Addresses](contents/streams/addresses.md)
 7 |   * Using Oracle SDK contract
 8 |     * [Introduction](contents/sdk/introduction.md)
 9 |     * [Examples](contents/sdk/examples.md)
10 |   * Supported Chains
11 |     * [Ethereum](contents/blockchains/ethereum.md)
12 |     * [Huobi Heco Chain](contents/blockchains/heco.md)
13 |     * [Binance Smart Chain](contents/blockchains/bsc.md)
14 |     * [OkChain](contents/blockchains/ok.md)
15 |     * [Polkadot](contents/blockchains/polkadot.md)
16 |   * [Tools](contents/dev_tools.md)
17 | * Node Runners
18 |   * [Tutorials](contents/deploy.md)
19 | * Misc
20 |   * [FAQ](contents/faq.md)
21 |   * [Feedback](contents/feedback.md)
22 | 


--------------------------------------------------------------------------------
/contents/.nojekyll:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/DOSNetwork/docs/fde4ef3ad71a1365f082c0181731a93b25496d9b/contents/.nojekyll


--------------------------------------------------------------------------------
/contents/architecture.md:
--------------------------------------------------------------------------------
 1 | DOS NETWORK is chain-agnostic, meaning that it could serve all existing smart contract platforms; it is decentralized, meaning that it has no single point of failure, no central trust in a single company or special hardware, the trust lives in math and code; it is horizontally scalable, meaning that with more nodes running DOS client software the whole network offers more capability and computation power to supported blockchains; it is designed with cryptoeconomic models, meaning that the protocol is resistant to sybil attacks and the network effect is expanded with provable credibility.
 2 | 
 3 | ![](../_media/architecture.png)
 4 | 
 5 | DOS NETWORK is consist of two part: on-chain contracts part and off-chain p2p network part:
 6 | * **on-chain contracts part:** A set of DOS system contracts deployed on supported blockchains, mainly including functionalities such as request handling and response/computation result verification, node registration and staking, stats monitoring, payment processing, etc. On-chain system contracts also provide a universal interface to all user contracts across supported chains.
 7 | 
 8 | 
 9 | * **off-chain p2p network part:** A client software implementing the core protocol run by third party users aiming for economic rewards, constituting a distributed network. Client software includes several important modules: event monitoring and chain adaptor module, distributed randomness engine module, off-chain group consensus module, and request processing/computation task processing module depending on the type of oracle service the user node provides.
10 | 


--------------------------------------------------------------------------------
/contents/blockchains/.nojekyll:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/DOSNetwork/docs/fde4ef3ad71a1365f082c0181731a93b25496d9b/contents/blockchains/.nojekyll


--------------------------------------------------------------------------------
/contents/blockchains/bsc.md:
--------------------------------------------------------------------------------
1 | ### Deployed address
2 | 
3 | 


--------------------------------------------------------------------------------
/contents/blockchains/ethereum.md:
--------------------------------------------------------------------------------
  1 | ## Deployed Contracts on Mainnet
  2 | We're using [proxy-upgrade pattern](https://blog.openzeppelin.com/proxy-patterns/) for contracts that touching users' money (i.e. `DOSPayment` and `Staking` contract), so that in case of emergency situation we'll be able to upgrade to a patched version without interrupting user behavior.
  3 | * [DOSAddressBridge](https://etherscan.io/address/0x98a0e7026778840aacd28b9c03137d32e06f5ff1) - Connector that contains all system contratcs' addresses.
  4 | * [CommitReveal](https://etherscan.io/address/0x144ed0555269628049f76da2adbdcdf3aa488e0e) - Conceals details of [commit-reveal scheme](https://en.wikipedia.org/wiki/Commitment_scheme), which is used to generate a secure and unpredictable genesis random number by multiparties in every bootstrap phase.
  5 | * [DOSProxy](https://etherscan.io/address/0x1402c061e2aec7b41ae4911b40f7b340489dd1da) - Conceals details such as request handling, random group selection, threshold signature verification, user-defined callback function invocation, response parsing, etc.
  6 | * `DOSPayment` - Conseals details of oracle request payment schemes and other node runners' validity judgement.
  7 |   - Payment gateway (proxy): https://etherscan.io/address/0x7b8d5a37008382b2c7e8e15ecf3c2727e38a6ac6
  8 |   - Payment implementation: https://etherscan.io/address/0x24286C5a340bF99EDB2d7e7D114477987d34816F
  9 | * `Staking` - Both eligible node runners and normal token holders (delegators) are able to earn staking rewards:
 10 |   - Staking gateway (proxy): https://etherscan.io/address/0x5dbef8e9e83a17d4d1d4c65a1e26133edae851dc
 11 |   - Staking implementation: https://etherscan.io/address/0x6a829E0EB032FA39D0444D29DFd80Bd3AE91C5B9
 12 |   - Node runners earn staking rewards by staking at least 800K tokens (or lessen a bit by owning [DropBurn](https://medium.com/dos-network/introducing-dropburn-a-new-model-to-bootstrap-staking-network-3b2c605dd276) token) themselves and join the network to provide oracle services.
 13 |   - Normal token holders earn staking rewards by delegating to eligible nodes, they may need to pay a percentage of earned rewards to delegated nodes.
 14 |   - A user-friendly [frontend](https://dashboard.dos.network) is provided to help node runners and token holders to stake, delegate, withdraw rewards, register a node, etc.
 15 |   - (Note that running a node requires both on-chain stake bonding and off-chain setup of node software, which is detailed in [node runner tutorials](https://medium.com/dos-network/instructions-of-launching-a-node-in-dos-network-932e73a91a75))
 16 | 
 17 | <p align="center">
 18 |   <img src="https://raw.githubusercontent.com/DOSNetwork/docs/master/_media/staking.png">
 19 | </p>
 20 | 
 21 | 
 22 | ## Deployed Contracts on Rinkeby Testnet
 23 | * [DOSAddressBridge](https://rinkeby.etherscan.io/address/0xeE2e9f35c9F91571535173902E7e7B4E67deE32b)
 24 | * [CommitReveal](https://rinkeby.etherscan.io/address/0x044D8D7028eC8Fc98247d072603F5316656EcfDe)
 25 | * [DOSProxy](https://rinkeby.etherscan.io/address/0xAb09D3A9998c918Ffa796F6449D8515e5C7DB8a2)
 26 | * `DOSPayment`:
 27 |   - Payment gateway (proxy): https://rinkeby.etherscan.io/address/0x306d78A9Cf1116513220C908C5D950914D797682
 28 |   - Payment implementation: https://rinkeby.etherscan.io/address/0x6b89f9C6bD11B14ae17DAfba4C578DdA527E7EF3
 29 | * `Staking`:
 30 |   - Staking gateway (proxy): https://rinkeby.etherscan.io/address/0x064fa6a739580a9bA8cfeFDc271fa5585BC274e3
 31 |   - Staking implementation: https://rinkeby.etherscan.io/address/0x9faaebe59eaf3132c3cf42a947bab11408d12296
 32 | 
 33 | 
 34 | 
 35 | ## Acquire Testnet DOS Tokens
 36 | * [Testnet DOS Token](https://rinkeby.etherscan.io/address/0x214e79c85744cd2ebbc64ddc0047131496871bee)
 37 | * Please fill in this [form](https://docs.google.com/forms/d/e/1FAIpQLSe7Kf1RvGa2p5SjP4eGAp-fw2frauOl6CDORnHK0-TNbjho9w/viewform) to request testnet tokens.
 38 | * Testnet DOS token Faucet:
 39 |  - [x]
 40 | 
 41 | 
 42 | ## Appendix
 43 | ### Selector
 44 | The selector expression is following [JSONPath](https://www.npmjs.com/package/jsonpath) and [XPath](https://en.wikipedia.org/wiki/XPath) rules to filter components from responses.
 45 | ##### Json example and selector expression:
 46 | ```solidity
 47 | {
 48 |     "store": {
 49 |         "book": [
 50 |             {
 51 |                 "category": "reference",
 52 |                 "author": "Nigel Rees",
 53 |                 "title": "Sayings of the Century",
 54 |                 "price": 8.95
 55 |             },
 56 |             {
 57 |                 "category": "fiction",
 58 |                 "author": "Evelyn Waugh",
 59 |                 "title": "Sword of Honour",
 60 |                 "price": 12.99
 61 |             },
 62 |             {
 63 |                 "category": "fiction",
 64 |                 "author": "Herman Melville",
 65 |                 "title": "Moby Dick",
 66 |                 "isbn": "0-553-21311-3",
 67 |                 "price": 8.99
 68 |             },
 69 |             {
 70 |                 "category": "fiction",
 71 |                 "author": "J. R. R. Tolkien",
 72 |                 "title": "The Lord of the Rings",
 73 |                 "isbn": "0-395-19395-8",
 74 |                 "price": 22.99
 75 |             }
 76 |         ],
 77 |         "bicycle": {
 78 |             "color": "red",
 79 |             "price": 19.95
 80 |         }
 81 |     },
 82 |     "expensive": 10
 83 | }
 84 | ```
 85 | Example selector expressions for the above json object:
 86 | 
 87 | 
 88 | Selector expression           | Description
 89 | ----------------------------- | --------------
 90 | $.expensive 			                               | 10
 91 | $.store.book[0].price                            | 8.95
 92 | $.store.book[-1].isbn                            | "0-395-19395-8"
 93 | $.store.book[0,1].price                          | [8.95, 12.99]
 94 | $.store.book[0:2].price                          | [8.95, 12.99, 8.99]
 95 | $.store.book[?(@.isbn)].price                    |  [8.99, 22.99]
 96 | $.store.book[?(@.price > 10)].title              | ["Sword of Honour", "The Lord of the Rings"]
 97 | $.store.book[?(@.price < $.expensive)].price     | [8.95, 8.99]
 98 | $.store.book[:].price                            | [8.9.5, 12.99, 8.9.9, 22.99]
 99 | 
100 | * Use this [online tool](https://codebeautify.org/jsonpath-tester) to get familar with JSONPath selector.
101 | 
102 | ##### XML example and selector expression:
103 | ```xml
104 | <library>
105 |   <!-- Great book. -->
106 |   <book id="b0836217462" available="true">
107 |     <isbn>0836217462</isbn>
108 |     <title lang="en">Being a Dog Is a Full-Time Job</title>
109 |     <quote>I'd dog paddle the deepest ocean.</quote>
110 |     <author id="CMS">
111 |       <?echo "go rocks"?>
112 |       <name>Charles M Schulz</name>
113 |       <born>1922-11-26</born>
114 |       <dead>2000-02-12</dead>
115 |     </author>
116 |     <character id="PP">
117 |       <name>Peppermint Patty</name>
118 |       <born>1966-08-22</born>
119 |       <qualification>bold, brash and tomboyish</qualification>
120 |     </character>
121 |     <character id="Snoopy">
122 |       <name>Snoopy</name>
123 |       <born>1950-10-04</born>
124 |       <qualification>extroverted beagle</qualification>
125 |     </character>
126 |   </book>
127 | </library>
128 | ```
129 | Example selector expressions for the above xml document:
130 | 
131 | Selector expression           | Description
132 | ------------------------------|------------
133 | /library/book/isbn                               |  "0836217462"
134 | /library/*/isbn                                  |  "0836217462"
135 | /library/book/../book/./isbn                     |  "0836217462"
136 | /library/book/character[2]/name                  |  "Snoopy"
137 | /library/book/character[born='1950-10-04']/name  |  "Snoopy"
138 | /library/book//node()[@id='PP']/name             |  "Peppermint Patty"
139 | //book[author/@id='CMS']/title                   |  "Being a Dog Is a Full-Time Job",
140 | /library/book/preceding::comment()               |  " Great book. "
141 | //*[contains(born,'1922')]/name                  |  "Charles M Schulz"
142 | //*[@id='PP' or @id='Snoopy']/born               |  {"1966-08-22", "1950-10-04"}
143 | 
144 | * Use this [online tool](http://www.utilities-online.info/xpath) to get familar with XPath selector.
145 | 


--------------------------------------------------------------------------------
/contents/blockchains/heco.md:
--------------------------------------------------------------------------------
1 | ### Deployed address
2 | 


--------------------------------------------------------------------------------
/contents/blockchains/ok.md:
--------------------------------------------------------------------------------
1 | ### Deployed address
2 | 


--------------------------------------------------------------------------------
/contents/blockchains/polkadot.md:
--------------------------------------------------------------------------------
1 | ### Under Construction...
2 | 


--------------------------------------------------------------------------------
/contents/concepts.md:
--------------------------------------------------------------------------------
1 | - Alpha fillin
2 | 


--------------------------------------------------------------------------------
/contents/deploy.md:
--------------------------------------------------------------------------------
 1 | ### Ethereum mainnet nodes:
 2 | * Please follow the node runner [tutorial](https://medium.com/dos-network/instructions-of-launching-a-node-in-dos-network-932e73a91a75) here for software version, hardware requirements, and detailed instructions.
 3 | * For developers to contribute and compile binary locally, check [readme](https://github.com/DOSNetwork/core/blob/master/README.md) file and open github issues if necessary.
 4 | * Nodes should use this [config file](https://github.com/DOSNetwork/core/blob/master/config.json).
 5 | 
 6 | ### HecoChain mainnet nodes:
 7 | * Nodes should use this [config file](https://github.com/DOSNetwork/core/blob/master/config-heco.json).
 8 | 
 9 | 
10 | ### Binance smart chain mainnet nodes:
11 | * Nodes should use this [config file](https://github.com/DOSNetwork/core/blob/master/config-bsc.json).
12 | 
13 | 
14 | ### Rinkeby Testnet tokens & nodes:
15 | * [Testnet DOS Token](https://rinkeby.etherscan.io/address/0x214e79c85744cd2ebbc64ddc0047131496871bee)
16 | * [Testnet DropBurn Token](https://rinkeby.etherscan.io/address/0x9bfe8f5749d90eb4049ad94cc4de9b6c4c31f822)
17 | * Please fill in this [form](https://docs.google.com/forms/d/e/1FAIpQLSe7Kf1RvGa2p5SjP4eGAp-fw2frauOl6CDORnHK0-TNbjho9w/viewform) to request testnet tokens.
18 | * Testnet token faucet: [...]
19 | * Nodes should use this [config file](https://github.com/DOSNetwork/core/blob/master/config-rinkeby.json).
20 |  
21 | 
22 | 
23 | 


--------------------------------------------------------------------------------
/contents/dev_tools.md:
--------------------------------------------------------------------------------
 1 | - [Ethfiddle by Loom](https://ethfiddle.com/)
 2 | 
 3 | - [Browser Solidity](http://remix.ethereum.org)
 4 | 
 5 | - [JSONPath Online Evaluator](https://codebeautify.org/jsonpath-tester)
 6 | 
 7 | - [XPath Online Evaluator](http://www.utilities-online.info/xpath)
 8 | 
 9 | - [DEX Liquidity Provider Incentives](https://medium.com/dos-network/dos-network-tokenomics-update-liquidity-rewards-and-token-burning-events-f8aa4c429d5b)
10 | 
11 | - [Network Explorer and Staking Dashboard](https://dashboard.dos.network)
12 | 
13 | - [Data Streams UI](#)
14 | 


--------------------------------------------------------------------------------
/contents/faq.md:
--------------------------------------------------------------------------------
 1 | #### What is DOS Network?
 2 | - DOS Network is a chain-agnostic layer 2 decentralized oracle network that offers realtime data feeds and verifiable computation power to mainstream blockchains. It connects on-chain smart contracts and Ðapps with off-chain data sources and unlimited computation power, enabling smart contracts with more real world use cases.
 3 | 
 4 | #### What is the architecture of DOS Network?
 5 | - **On-chain part**: A set of system and governance contracts are to be deployed on supported blockchains, mainly including functionalities such as request handling and response/computation result verification, node registration and staking, stats monitoring, payment processing, etc. On-chain system contracts also provide a universal interface to developers and user contracts on all supported chains.
 6 | - **Off-chain part**: A client software implementing the core protocol running by third party users (a.k.a node operators), constituting a layer 2 distributed network serving oracle requests. Client software includes several important modules: event monitoring and chain adaptor module, distributed randomness engine module, cryptography and off-chain group consensus module, request and/or computation task processing module depending on the type of oracle service the node operator provides.
 7 | 
 8 | #### How does DOS Network provide real world data to smart contracts?
 9 | - It basically follows the request-response pattern. Through the on-chain SDK we develop, smart contract (developer) specifies the origin and format of the required data by making a message call (oracle request) into system contracts. The request is randomly dispatched to an off-chain worker group, inside which member nodes fetch from the specified data source and cryptographically reach off-chain consensus within the selected group. The proof along with the response data are sent back to the system contracts just in 1 transaction, triggering on-chain verification.
10 | - Besides the asynchronous request-response pattern, we're also building on-chain aggregation contracts for frequently used data (e.g. Coingecko price data, e.g.) for other DeFi projects to use / integrate directly. Please [contact](mailto:info@dos.network) with team for alpha usage request. (Whitelist mode for alpha stage.)
11 | - Unlike prediction market, DOS Network is able to connect any data/endpoint reachable in the Internet, the whole process happens automatically near real time and there is no human involvement at all.
12 | 
13 | #### How to ensure the returned data is untampered?
14 | - DOS Network applies Verifiable Random Function (VRF) and Threshold Cryptography to drive the secure, unpredictable and verifiable random group selection. Different oracle requests will be handled by randomly selected worker groups.
15 | - Threshold cryptography will then be applied in the worker group to collectively generate a proof to demonstrate data integrity. Finally, the proof along with the data will be sent back together to the system contracts within one transaction for on-chain verification - any malicious submitter will be detected and punished accordingly.
16 | - You can check our [whitepaper](https://s3.amazonaws.com/whitepaper.dos/DOS+Network+Technical+Whitepaper.pdf) for more technical details and mathematical proofs.
17 | 
18 | #### How fast is DOS Network?
19 | - The off-chain process is blazing fast and usually completes within less than 1 second, including event monitoring, request processing, data fetching and parsing, collective proof generation within group members, etc. That is to say, the performance bottleneck is often in the layer 1 blockchain side.
20 | - For Ethereum, the response is delivered in the next block (average block time ~14s) - the fastest one could achieve in theory. For other blockchains such as EOS (average block time ~0.5s) the delay will be much smaller.
21 | 
22 | #### Why is the node-selection mechanism based on randomness instead of reputation?
23 | - We see some oracles are based on reputation to choose service nodes - node with higher reputation often leads to a bigger probability of being selected. However, reputation based solution is susceptible to centralization, collusions and targeted attacks against high-score nodes. Moreover, it easily leads to the [Matthew Effect](https://en.wikipedia.org/wiki/Matthew_effect), disincentivizing new node operators with same abilities to join the network, leading to the centralization spiral.
24 | - Thus we're replying on randomness to select oracle nodes. Randomness is specifically important in blockchains. For example, Proof-of-Work system achieves random block producer selection through the mining process. Verifiable Random Function (VRF) and Threshold Cryptography generate secure, unpredictable and verifiable randomness, keeping the DOS Network resistant to targeted attacks and node collusions, safe and fair for all node operators.
25 | 


--------------------------------------------------------------------------------
/contents/feedback.md:
--------------------------------------------------------------------------------
1 | ?> Do you have any comment for  API usage or suggestion on this doc? [Create issues here](https://github.com/DOSNetwork/docs/issues/new)
2 | 


--------------------------------------------------------------------------------
/contents/sdk/examples.md:
--------------------------------------------------------------------------------
  1 | - **Example 1**: `DOSQuery()` to get latest ETH-USD price from Coinbase.
  2 | ```solidity
  3 |   pragma solidity ^0.5.0;
  4 | 
  5 |   import "./utils.sol";
  6 |   import "./DOSOnChainSDK.sol";
  7 | 
  8 |   // An example get latest ETH-USD price from Coinbase
  9 |   contract CoinbaseEthPriceFeed is DOSOnChainSDK {
 10 |     using utils for *;
 11 | 
 12 |     // Struct to hold parsed floating string "123.45"
 13 |     struct ethusd {
 14 |         uint integral;
 15 |         uint fractional;
 16 |     }
 17 |     uint queryId;
 18 |     string public price_str;
 19 |     ethusd public price;
 20 | 
 21 |     event GetPrice(uint integral, uint fractional);
 22 | 
 23 |     constructor() public {
 24 |         // @dev: setup and then transfer DOS tokens into deployed contract
 25 |         // as oracle fees.
 26 |         // Unused fees can be reclaimed by calling DOSRefund() in the SDK.
 27 |         super.DOSSetup();
 28 |     }
 29 | 
 30 |     function getEthUsdPrice() public {
 31 |         queryId = DOSQuery(30, "https://api.coinbase.com/v2/prices/ETH-USD/spot", "$.data.amount");
 32 |     }
 33 | 
 34 |     function __callback__(uint id, bytes calldata result) external auth {
 35 |         require(queryId == id, "Unmatched response");
 36 | 
 37 |         price_str = string(result);
 38 |         price.integral = price_str.subStr(1).str2Uint();
 39 |         int delimit_idx = price_str.indexOf('.');
 40 |         if (delimit_idx != -1) {
 41 |             price.fractional = price_str.subStr(uint(delimit_idx + 1)).str2Uint();
 42 |         }
 43 |         emit GetPrice(price.integral, price.fractional);
 44 |     }
 45 |   }
 46 | ```
 47 |  - Try this gist on [remix](http://remix.ethereum.org/#gist=f39845c47564c9ff98085749bd542d44&optimize=true&version=soljson-v0.5.17+commit.d19bba13.js).
 48 |  - The example is also [deployed](https://etherscan.io/address/0x284e8386e94624d7a681b883d0a718ec22481536#code) on ethereum mainnet and seeded with 450 DOS tokens for anyone to try with.
 49 |  - (On Etherscan, click `Write Contract`, click `Connect to Web3`. Then select `getEthUSdPrice()` and you'll be paying a little gas. After 1 block, click `Read Contract` and see `price_str` and `price` fields. Click `Events` and `Internal Txns` to see more details.).
 50 | 
 51 | <p align="center">
 52 |   <img width="600" height="400" src="https://raw.githubusercontent.com/DOSNetwork/docs/master/_media/remix.png">
 53 | </p>
 54 | 
 55 | 
 56 | - **Example 2**: A `SimpleDice` game with no insider trading or house edge, based on smart contract plus secure and unpredictable random number generated through `DOSRandom()`.
 57 | ```solidity
 58 |   pragma solidity ^0.5.0;
 59 | 
 60 |   import "./DOSOnChainSDK.sol";
 61 | 
 62 |   contract SimpleDice is DOSOnChainSDK {
 63 |     address payable public devAddress;
 64 |     uint public devContributed = 0;
 65 |     // 1% winning payout goes to developer account
 66 |     uint public developCut = 1;
 67 |     // precise to 4 digits after decimal point.
 68 |     uint public decimal = 4;
 69 |     // gameId => gameInfo
 70 |     mapping(uint => DiceInfo) public games;
 71 | 
 72 |     struct DiceInfo {
 73 |         uint rollUnder;  // betted number, player wins if random < rollUnder
 74 |         uint amountBet;  // amount in wei
 75 |         address payable player;  // better address
 76 |     }
 77 | 
 78 |     event ReceivedBet(
 79 |         uint gameId,
 80 |         uint rollUnder,
 81 |         uint weiBetted,
 82 |         address better
 83 |     );
 84 |     event PlayerWin(uint gameId, uint generated, uint betted, uint amountWin);
 85 |     event PlayerLose(uint gameId, uint generated, uint betted);
 86 | 
 87 |     modifier onlyDev {
 88 |         require(msg.sender == devAddress);
 89 |         _;
 90 |     }
 91 | 
 92 |     constructor() public {
 93 |         // @dev: setup and then transfer DOS tokens into deployed contract
 94 |         // as oracle fees.
 95 |         // Unused fees can be reclaimed by calling DOSRefund() in the SDK.
 96 |         super.DOSSetup();
 97 |         
 98 |         // Convert address to payable address.
 99 |         devAddress = address(uint160(owner()));
100 |     }
101 | 
102 |     function min(uint a, uint b) internal pure returns(uint) {
103 |         return a < b ? a : b;
104 |     }
105 |     // Only receive bankroll funding from developer.
106 |     function() external payable onlyDev {
107 |         devContributed += msg.value;
108 |     }
109 |     // Only developer can withdraw the amount up to what he has contributed.
110 |     function devWithdrawal() public onlyDev {
111 |         uint withdrawalAmount = min(address(this).balance, devContributed);
112 |         devContributed = 0;
113 |         devAddress.transfer(withdrawalAmount);
114 |     }
115 | 
116 |     // 100 / (rollUnder - 1) * (1 - 0.01) => 99 / (rollUnder - 1)
117 |     // Not using SafeMath as this function cannot overflow anyway.
118 |     function computeWinPayout(uint rollUnder) public view returns(uint) {
119 |         return 99 * (10 ** decimal) / (rollUnder - 1);
120 |     }
121 | 
122 |     // 100 / (rollUnder - 1) * 0.01
123 |     function computeDeveloperCut(uint rollUnder) public view returns(uint) {
124 |         return 10 ** decimal / (rollUnder - 1);
125 |     }
126 | 
127 |     function play(uint rollUnder) public payable {
128 |         // winChance within [1%, 95%]
129 |         require(rollUnder >= 2 && rollUnder <= 96, "rollUnder should be in 2~96");
130 |         // Make sure contract has enough balance to cover payouts before game.
131 |         // Not using SafeMath as I'm not expecting this demo contract's
132 |         // balance to be very large.
133 |         require(address(this).balance * (10 ** decimal) >= msg.value * computeWinPayout(rollUnder),
134 |                 "Game contract doesn't have enough balance, decrease rollUnder");
135 | 
136 |         // Request a safe, unmanipulatable random number from DOS Network with
137 |         // optional seed.
138 |         uint gameId = DOSRandom(now);
139 | 
140 |         games[gameId] = DiceInfo(rollUnder, msg.value, msg.sender);
141 |         // Emit event to notify Dapp frontend
142 |         emit ReceivedBet(gameId, rollUnder, msg.value, msg.sender);
143 |     }
144 | 
145 |     function __callback__(uint requestId, uint generatedRandom) external auth {
146 |         address payable player = games[requestId].player;
147 |         require(player != address(0x0));
148 | 
149 |         uint gen_rnd = generatedRandom % 100 + 1;
150 |         uint rollUnder = games[requestId].rollUnder;
151 |         uint betted = games[requestId].amountBet;
152 |         delete games[requestId];
153 | 
154 |         if (gen_rnd < rollUnder) {
155 |             // Player wins
156 |             uint payout = betted * computeWinPayout(rollUnder) / (10 ** decimal);
157 |             uint devPayout = betted * computeDeveloperCut(rollUnder) / (10 ** decimal);
158 | 
159 |             emit PlayerWin(requestId, gen_rnd, rollUnder, payout);
160 |             player.transfer(payout);
161 |             devAddress.transfer(devPayout);
162 |         } else {
163 |             // Lose
164 |             emit PlayerLose(requestId, gen_rnd, rollUnder);
165 |         }
166 |     }
167 |   }
168 | ```
169 |  - Try this gist out on [remix](http://remix.ethereum.org/#gist=3b2ca0410af407497bdc70ffe79ee123&optimize=true&evmVersion=null&version=soljson-v0.5.17+commit.d19bba13.js).
170 |  - This example is also [deployed](https://rinkeby.etherscan.io/address/0xb156032041f83eb6d96916aada5c7dbdd338dccb) on rinkeby testnet.
171 |  - (On Etherscan, click `Write Contract`, click `Connect to Web3`. Then select `play()` and you need to fill in 2 arguments: the amount of `testnet ether` you'd like to bet, and a `rollUnder` number. If the off-chain collectively generated random number is less than the `rollUnder` you provide then you win, otherwise you lose the amount you bet. After 1 block, click `Internal Txns` and `ReceivedBet & PlayerWin / PlayerLose` Events to see more details.
172 | 
173 | 
174 | 
175 | - **Example 3**: See [Stream](https://github.com/DOSNetwork/smart-contracts/blob/master/contracts/Stream.sol) contract to learn more.
176 | 


--------------------------------------------------------------------------------
/contents/sdk/introduction.md:
--------------------------------------------------------------------------------
  1 | ## Setup
  2 | - Besides consuming data streams, DOS Network can connect smart contracts with any external API / data by utilizing [DOSOnChainSDK](https://github.com/DOSNetwork/eth-contracts/blob/master/contracts/DOSOnChainSDK.sol) contract for each supported chain. For each data request or VRF randomness request, **20 DOS token** is needed (the number may change depending on usage cost).
  3 | 
  4 | - In the calling contract's constructor, simply setup by calling `super.DOSSetup()`.
  5 | 
  6 | - Sending several DOS tokens as fees into the calling contract. The fees can be reclaimed by contract owner by calling `DOSRefund()`.
  7 | 
  8 | <!-- tabs:start -->
  9 | 
 10 | #### **Example Setup**
 11 | ```solidity
 12 | contract Example is DOSOnChainSDK {
 13 |   // ...
 14 |   constructor() public {
 15 |     // @dev: setup and then transfer DOS tokens into deployed contract as oracle fees.
 16 |     // Unused fees can be reclaimed by calling DOSRefund() in the SDK.
 17 |     super.DOSSetup();
 18 |   }
 19 |   // ...
 20 | }
 21 | ```
 22 | 
 23 | <!-- tabs:end -->
 24 | 
 25 | 
 26 | ## Request Any Data
 27 | - Smart contract requests for external data by calling `DOSQuery()` function. The whole process is an asynchronous one - i.e. it merely returns a unique `queryId` that caller caches for bookkeeping and future identification, with the real response coming back through the `__callback__()` function.
 28 | 
 29 | - The response data will be backfilled through the `__callback__` function along with corresponding `queryId`. Instead of backfilling the whole raw response we're using [selector expression](#selector) to filter `json` and `xml/html` formated response, developers are able to specify interesting data fields in `DOSQuery()` function.
 30 | 
 31 | - Example usage:
 32 | 
 33 | <!-- tabs:start -->
 34 | 
 35 | #### **DOSQuery() API**
 36 | `function DOSQuery(uint timeout, string memory dataSource, string memory selector)`:
 37 | - `timeout`: An estimated timeout in seconds specified by the caller, e.g. `30`. Response is not guaranteed if client side processing time exceeds this value.
 38 | - `dataSource`: Path to the data source specified by caller.
 39 | - `selector`: A `selector expression` provided by caller to filter out specific data fields out of the raw response, with the response data format (json, xml, or more) to be identified from the selector expression. Check the [selector expression](#selector) part for details.
 40 | - Example usage:
 41 | ```solidity
 42 | contract Example is DOSOnChainSDK {
 43 |     mapping(uint => bool) private _valid_queries;
 44 |     ...
 45 |     function CoinbaseEthPriceFeed() public {
 46 |         // Returns a unique queryId that caller caches for future verification
 47 |         uint queryId = DOSQuery(30, "https://api.coinbase.com/v2/prices/ETH-USD/spot", "$.data.amount");
 48 |         _valid_queries[queryId] = true;
 49 |         ...
 50 |     }
 51 |     ...
 52 | }
 53 | ```
 54 | 
 55 | #### **__callback__() API**
 56 | 
 57 | <p>* Note that the caller must override `__callback__` function to receive and process the response. A user-defined event may be added to notify the Dapp frontend that the response is ready.</p>
 58 | 
 59 | `function __callback__(uint queryId, bytes calldata result)`:
 60 | - `queryId`: A unique `queryId` returned by `DOSQuery()` to differenciate parallel responses.
 61 | - `result`: Corresponding response in `bytes`.
 62 | - Example usage:
 63 | ```solidity
 64 | function __callback__(uint queryId, bytes calldata result) external auth {
 65 |     // Check whether @queryId corresponds to a previous cached one
 66 |     require(_valid_queries[queryId], "Err-resp-with-invalid-queryId");
 67 | 
 68 |     // Deal with result
 69 |     ...
 70 |     delete _valid_queries[queryId];
 71 | }
 72 | ```
 73 | <!-- tabs:end -->
 74 | 
 75 | - We also provide utility functions for developers to easily process `string / bytes`: 
 76 | ```solidity
 77 |   library StringUtils {
 78 |       function subStr(string memory a, uint start, uint len) internal pure returns(string memory);
 79 |       function subStr(string memory a, uint start) internal pure returns(string memory);
 80 |       function subStr(bytes memory a, uint start, uint len) internal pure returns(bytes memory);
 81 |       function subStr(bytes memory a, uint start) internal pure returns(bytes memory);
 82 |       function indexOf(string memory haystack, string memory needle) internal pure returns(uint);
 83 |       function indexOf(bytes memory haystack, bytes memory needle) internal pure returns(uint);
 84 |       function count(string memory str, string memory delimiter) internal pure returns(uint);
 85 |       function split(string memory str, string memory delimiter) internal pure returns(string[] memory);
 86 |       function split(bytes memory str, bytes memory delimiter) internal pure returns(bytes[] memory);
 87 |       function strConcat(string memory a, string memory b) internal pure returns(string memory);
 88 |       function bytesConcat(bytes memory a, bytes memory b) internal pure returns(bytes memory);
 89 |       function strCompare(string memory a, string memory b) internal pure returns(int);
 90 |       function bytesCompare(bytes memory a, bytes memory b) internal pure returns(int);
 91 |       function strEqual(string memory a, string memory b) internal pure returns(bool);
 92 |       function bytesEqual(bytes memory a, bytes memory b) internal pure returns(bool);
 93 | 
 94 |       function uint2Str(uint x) internal pure returns(string memory);
 95 |       function uint2HexStr(uint x) internal pure returns(string memory);
 96 |       function addr2Str(address x) internal pure returns(string memory);
 97 |       function str2Addr(string memory a) internal pure returns(address);
 98 |       function str2Uint(string memory a) internal pure returns(uint);
 99 |       function hexStr2Uint(string memory a) internal pure returns(uint);
100 |       function byte2Uint(byte b) internal pure returns(uint);
101 |       function hexByte2Uint(byte b) internal pure returns(uint);
102 |   }
103 | ```
104 | 
105 | 
106 | ## Request VRF Randomness
107 | - Randomness is particularly important for many Dapps and games, however, it's impossible to generate a secure and unpredictable random number in pure deterministic environment:
108 | 
109 | <p align="center">
110 |   <img width="500" height="250" src="https://raw.githubusercontent.com/DOSNetwork/docs/master/_media/random.png">
111 | </p>
112 | 
113 | - DOS Network is providing a provably secure, unstoppable and unpredictable random source for on-chain smart contracts to use. For technical details and cryptographic proofs please check our [whitepaper](#).
114 | 
115 | <!-- tabs:start -->
116 | 
117 | #### **DOSRadom() API**
118 | `function DOSRandom(uint seed) returns (uint)`:
119 | - `seed`: An *optional* random seed provided by caller to get more entropy. The generated random number is secure and unpredictable in safe mode even without providing this `seed`.
120 | - Example usage:
121 | ```solidity
122 | function requestSafeRandom() public {
123 |     uint requestId = DOSRandom(now);
124 |     _valid[requestId] = true;
125 |     emit RandomRequested(requestId);
126 | }
127 | ```
128 | 
129 | #### **__callback__() API**
130 | `function __callback__(uint requestId, uint generatedRandom) external`:
131 | - `requestId`: A unique `requestId` returned by `DOSRandom()` to process parallelly generated random numbers.
132 | - `generatedRandom`: Generated secure random number for the specific `requestId`.
133 | - Example usage:
134 | 
135 | ```solidity
136 | modifier auth(uint id) {
137 |     // Exclude malicious callback responses.
138 |     require(msg.sender == fromDOSProxyContract(),
139 |             "Unauthenticated response from non-DOS.");
140 |     // Check whether id mapps to a previously requested one.
141 |     require(_valid[id], "Response with invalid request id!");
142 |     _;
143 | }
144 | 
145 | function __callback__(uint requestId, uint generatedRandom)
146 |     external
147 |     auth(requestId)
148 | {
149 |     emit RandomGenerated(generatedRandom);
150 |     delete _valid[requestId];
151 | 
152 |     // Deal with generated random number
153 |     random = generatedRandom;
154 |     ...
155 | }
156 | ```
157 | 
158 | <!-- tabs:end -->
159 | 
160 | 
161 | 


--------------------------------------------------------------------------------
/contents/streams/addresses.md:
--------------------------------------------------------------------------------
  1 | ## Heco Chain Data Streams
  2 | 
  3 | ### UI
  4 | * https://stream.dos.network
  5 | 
  6 | ### Mainnet
  7 | * **Crypto Streams**:
  8 |   - StreamsManager: [0xc02DDAeb7644b9D2d92b96371f79A92FB6d306fe](https://hecoinfo.com/address/0xc02DDAeb7644b9D2d92b96371f79A92FB6d306fe)
  9 |   - MegaStream: [0xF0236DfB582B43fF2db7f390A6829cF22ABf9bB9](https://hecoinfo.com/address/0xF0236DfB582B43fF2db7f390A6829cF22ABf9bB9)
 10 | 
 11 | 
 12 | | Stream | Contract |
 13 | | ------ | ------ |
 14 | | BTC / USD | [0xEE12758Ea54F0Afa4268cc1Fc5BB70b53E24E8A5](https://hecoinfo.com/address/0xEE12758Ea54F0Afa4268cc1Fc5BB70b53E24E8A5) |
 15 | | ETH / USD | [0x7ceDd198017b030F9009D800fa8e3DfEB48e098f](https://hecoinfo.com/address/0x7ceDd198017b030F9009D800fa8e3DfEB48e098f) |
 16 | | DOT / USD | [0xB01c89Effe80c29782d50CBE09160F20BA9Bc4F7](https://hecoinfo.com/address/0xB01c89Effe80c29782d50CBE09160F20BA9Bc4F7) |
 17 | | HT / USD  | [0xB6D103f142A3f493f1d00478F64159591d82c92a](https://hecoinfo.com/address/0xB6D103f142A3f493f1d00478F64159591d82c92a) |
 18 | | DOS / USD | [0xdB2831118407367d9116E509bC7AeED325c21B59](https://hecoinfo.com/address/0xdB2831118407367d9116E509bC7AeED325c21B59) |
 19 | | FIL / USD | [0x0bC3E19138F8B0CaB31F369565e4fd5A90bD79f8](https://hecoinfo.com/address/0x0bC3E19138F8B0CaB31F369565e4fd5A90bD79f8) |
 20 | | HPT / USD | [0x27CF3f3C05188Fb61696d0a6Aad1a1013126cA89](https://hecoinfo.com/address/0x27CF3f3C05188Fb61696d0a6Aad1a1013126cA89) |
 21 | 
 22 | 
 23 | * **Stock Streams**:
 24 | 
 25 | 
 26 | 
 27 | ### Testnet
 28 | * **Crypto Streams**:
 29 |   - StreamsManager: [0x51D657f6000190Ba785e30344E9987028c1CF025](https://testnet.hecoinfo.com/address/0x51D657f6000190Ba785e30344E9987028c1CF025)
 30 |   - MegaStream: [0x8d2cf53d3c9635DC0f73B4Ca4cbf3191DBeC29b8](https://testnet.hecoinfo.com/address/0x8d2cf53d3c9635dc0f73b4ca4cbf3191dbec29b8)
 31 | 
 32 | | Stream | Contract |
 33 | | ----------- | -------- |
 34 | | BTC / USD | [0x2022737ddC95b15d55E452C9E8418899063fc196](https://testnet.hecoinfo.com/address/0x2022737ddC95b15d55E452C9E8418899063fc196) |
 35 | | ETH / USD | [0x9E39eF90EfE2eF833a9bB1F149be17477cdFA4d0](https://testnet.hecoinfo.com/address/0x9E39eF90EfE2eF833a9bB1F149be17477cdFA4d0) |
 36 | | DOT / USD | [0x4bBe16963C98553416114846e77696680F7cB812](https://testnet.hecoinfo.com/address/0x4bBe16963C98553416114846e77696680F7cB812) |
 37 | | HT / USD  | [0x438A5CC6A2b5E14A81e196fa32356a3705db10Fa](https://testnet.hecoinfo.com/address/0x438A5CC6A2b5E14A81e196fa32356a3705db10Fa) |
 38 | | DOS / USD | [0xfBc42FA54b3dc107f76978436b46542E3876229F](https://testnet.hecoinfo.com/address/0xfBc42FA54b3dc107f76978436b46542E3876229F) |
 39 | 
 40 | 
 41 | * **Stock Streams**:
 42 | 
 43 | 
 44 | 
 45 | 
 46 | ## Binance Smart Chain Data Streams
 47 | 
 48 | ### UI
 49 | * https://...
 50 | 
 51 | ### Mainnet
 52 | * **Crypto Streams**:
 53 | 
 54 | | Stream | Contract |
 55 | | ------ | ------ |
 56 | | BTC / USD | []() |
 57 | | ETH / USD | []() |
 58 | | DOT / USD | []() |
 59 | | BNB / USD | []() |
 60 | | DOS / USD | []() |
 61 | 
 62 | * **Stock Streams**:
 63 | 
 64 | 
 65 | ### Testnet
 66 | * **Crypto Streams**:
 67 | 
 68 | | Stream | Contract |
 69 | | ------ | ------ |
 70 | | BTC / USD | []() |
 71 | | ETH / USD | []() |
 72 | | DOT / USD | []() |
 73 | | BNB / USD | []() |
 74 | | DOS / USD | []() |
 75 | 
 76 | * **Stock Streams**:
 77 | 
 78 | 
 79 | ## OkChain Data Streams
 80 | 
 81 | ### UI
 82 | * https://...
 83 | 
 84 | ### Mainnet
 85 | * **Crypto Streams**:
 86 | 
 87 | | Stream | Contract |
 88 | | ------ | ------ |
 89 | | BTC / USD | []() |
 90 | | ETH / USD | []() |
 91 | | DOT / USD | []() |
 92 | | OKB / USD | []() |
 93 | | OKT / USD | []() |
 94 | | DOS / USD | []() |
 95 | 
 96 | * **Stock Streams**:
 97 | 
 98 | 
 99 | ### Testnet
100 | * **Crypto Streams**:
101 | 
102 | | Stream | Contract |
103 | | ------ | ------ |
104 | | BTC / USD | []() |
105 | | ETH / USD | []() |
106 | | DOT / USD | []() |
107 | | OKB / USD | []() |
108 | | OKT / USD | []() |
109 | | DOS / USD | []() |
110 | 
111 | * **Stock Streams**:
112 | 
113 | 


--------------------------------------------------------------------------------
/contents/streams/api.md:
--------------------------------------------------------------------------------
 1 | #### Time Window & Data Granularity
 2 | * `function windowSize() public view returns (uint)`:
 3 |   - Length of sliding window in seconds. Stream data is guaranteed to be updated at least once in each sliding window. E.g.: 1200 represents 20 minutes (1200 seconds).
 4 | 
 5 | * `function deviation() public view returns (uint)`:
 6 |   - Threshold value in multiples of 1/1000.
 7 |   - Stream data is guaranteed to be updated if the data from data source is beyond `(1 ± deviation / 1000) * lastUpdatedValue`. E.g.: 5 represents 0.005 deviation threshold.
 8 | 
 9 | * `function decimal() public view returns (uint)`:
10 |   - Number of decimals used in the price data. E.g.: With decimal value 8, 153765000000 represents 1537.65.
11 | 
12 | 
13 | 
14 | #### Number of Data Points
15 | * `function numPoints() public view returns (uint)`:
16 |   - Number of data points this data stream has ever been updated with since birth.
17 | 
18 | * `function num24hPoints() public view returns (uint)`:
19 |   - Number of data points this data stream has been updated with within the last 24 hours.
20 | 
21 | 
22 | 
23 | #### Data Freshness
24 | * `function stale(uint age) public view returns (bool)`:
25 |   - Returns true if the last updated result is outdated: i.e. last updated timestamp is more than `age` seconds from `now`.
26 | 
27 | 
28 | 
29 | #### Latest and Historical Data
30 | * `function latestResult() public view accessible returns (uint _lastPrice, uint _lastUpdatedTime)`:
31 |   - Returns the latest reported data point consensused from the data source, as well as the latest update time.
32 | 
33 | * `function result(uint idx) public view accessible returns (uint _price, uint _timestamp)`:
34 |   - Returns a specific historical data point and its timestamp given appropriate index into data point arrray.
35 |   - Parameter idx can be computed using helper functions like `binarySearch(uint timeDelta)`, `numPoints()`, etc. Read [Stream.sol](https://github.com/DOSNetwork/smart-contracts/blob/master/contracts/Stream.sol) source code to learn more.
36 | 
37 | 
38 | #### Time-Weighted-Average-Price (TWAP) Data
39 | A series of prebuilt functions to compute TWAP price data for time window from 1 hour to 1 week:
40 | ```solidity
41 | function TWAP1Hour() public view accessible returns (uint)
42 | function TWAP2Hour() public view accessible returns (uint)
43 | function TWAP4Hour() public view accessible returns (uint)
44 | function TWAP6Hour() public view accessible returns (uint)
45 | function TWAP8Hour() public view accessible returns (uint)
46 | function TWAP12Hour() public view accessible returns (uint)
47 | function TWAP1Day() public view accessible returns (uint)
48 | function TWAP1Week() public view accessible returns (uint)
49 | ```
50 | 
51 | * `function twapResult(uint startIdx) public view accessible returns (uint)`:
52 |   - Compute TWAP price data (observations[startIdx] : observations[lastIdx]).
53 | 
54 | 
55 | 
56 | #### Misc
57 | * `function whitelistEnabled() public view returns (bool)`:
58 |   - Returns true if whitelist access mode enabled. Once enabled, only whitelisted smart contracts, or EOA address can consume stream data.
59 | 
60 | * `function parser() public view returns (address)`:
61 |   - Returns parser contract used to parse reported data from data source, as consensused reported data is encoded into `bytes` format for general purpose.
62 | 
63 | * `function hasAccess(address reader) public view returns (bool)`:
64 |   - Returns whether `reader` address / contract has access to stream data. Can be skipped if `whitelistEnabled` is not turned on.
65 | 
66 | * `function shouldUpdate(uint price) public view returns (bool)`:
67 |   - Returns whether `price` data should be updated. True if either last updated timestamp is outdated, or `data` is beyond `deviation` threshold of last result.
68 |   - Note that this is only a reference function, `price` is not used to update the stream data. Stream data can only be updated in the `__callback__` function, invoked by off-chain nodes, with off-chain collectively generated group signature must also be verified on-chain before an update is invoked.
69 | 
70 | * `function binarySearch(uint timedelta) public view returns (uint)`:
71 |   - All reported data is sorted by timestamp in ascending order. Given time range, return the maximum index {i} satisfying that: `data[i].timestamp <= data[end].timestamp - timedelta`. This helper function is mostly used to construct other useful features like TWAP.
72 | 


--------------------------------------------------------------------------------
/contents/streams/start.md:
--------------------------------------------------------------------------------
  1 | ## Introducing Data Streams
  2 | <p align="center">
  3 |   <img width="880" height="660" src="https://raw.githubusercontent.com/DOSNetwork/docs/heco/_media/streams_ui.png">
  4 | </p>
  5 | 
  6 | * Data Streams provide real-time market prices of popular assests from high-quality data sources, secured by off-chain decentralized oracle network and validated by on-chain smart contracts before making available to dependent smart contracts.
  7 | 
  8 | * Stream data is guaranteed to be updated either every time window (e.g. 20 minutes) or when the latest data from data source is beyond the predetermined threshold (e.g. ±0.5%) of the last updated data, whichever happens first.
  9 | 
 10 | 
 11 | * Data streams' results can be read by External Own Accounts (`EOA`) or consumed (through `EVM call`) by downstream smart contracts, **freely** for now.
 12 | 
 13 | * Please [contact](mailto:info@dos.network) DOS Team if you're developers and want to access Data Streams in your smart contracts freely. We're glad to onboard more projects / developers and we have development grants to boost the usage and ecosystem.
 14 | 
 15 | * Please note that each data stream has a switch called `whitelistEnabled`, which is currently disabled. Once turned on, only whitelisted smart contracts can consume price data. Data streams are made for the public good and open to everyone for now to bootstrap both DeFi & DOS ecosystems on supported chains, but there're both technical & operational efforts to keep data streams secure and accurate, thus we highly encourage projects / developers to contact the team to get your smart contracts whitelisted beforehead, as well as receive news of latest supported streams.
 16 | 
 17 | 
 18 | ## Get Latest Price Data
 19 | * For your smart contracts to read latest price data, simply plugin [StreamInterface](https://github.com/DOSNetwork/smart-contracts/blob/master/contracts/interfaces/StreamInterface.sol) and call `latestResult()` like below.
 20 | 
 21 | <!-- tabs:start -->
 22 | 
 23 | #### **Example Code**
 24 | ```solidity
 25 | pragma solidity 0.5.17;
 26 | 
 27 | import "github.com/DOSNetwork/smart-contracts/contracts/interfaces/StreamInterface.sol";
 28 | 
 29 | contract BTCLatestPriceExample {
 30 |     IStream public stream;
 31 |     uint public decimal;
 32 | 
 33 |     /**
 34 |      * Network: Heco Testnet
 35 |      * Description: BTC/USD
 36 |      * Decimal: stream.decimal()
 37 |      * Address: 0x2022737ddC95b15d55E452C9E8418899063fc196
 38 |      */
 39 |     constructor() public {
 40 |         stream = IStream(0x2022737ddC95b15d55E452C9E8418899063fc196);
 41 |         decimal = stream.decimal();
 42 |     }
 43 | 
 44 |     /**
 45 |      * Returns the latest price
 46 |      */
 47 |     function getLatestBTCPrice() public view returns (uint) {
 48 |         (uint price, uint timestamp) = stream.latestResult();
 49 |         return price;
 50 |     }
 51 | }
 52 | ```
 53 | 
 54 | <!-- tabs:end -->
 55 | 
 56 | 
 57 | 
 58 | ## Get TWAP Price Data
 59 | * `Time-Weighted-Average-Price (TWAP)` data is widely used to smooth out abnormal spikes. A set of TWAP functions, ranging from 1 hour TWAP to 24 hours TWAP, are builtin for the ease of developers, simply calling `TWAP*Hour` (* = 1, 2, 4, 6, 8, 12) like below:
 60 | 
 61 | <!-- tabs:start -->
 62 | 
 63 | #### **Example Code**
 64 | ```solidity
 65 | pragma solidity 0.5.17;
 66 | 
 67 | import "github.com/DOSNetwork/smart-contracts/contracts/interfaces/StreamInterface.sol";
 68 | 
 69 | contract BTCTwapPriceExample {
 70 |     IStream public stream;
 71 |     uint public decimal;
 72 | 
 73 |     /**
 74 |      * Network: Heco Testnet
 75 |      * Description: BTC/USD
 76 |      * Data Decimal: stream.decimal()
 77 |      * Address: 0x2022737ddC95b15d55E452C9E8418899063fc196
 78 |      */
 79 |     constructor() public {
 80 |         stream = IStream(0x2022737ddC95b15d55E452C9E8418899063fc196);
 81 |         decimal = stream.decimal();
 82 |     }
 83 | 
 84 |     // Returns Time-Weighted-Average-Price for 1 hour.
 85 |     function getBTC1HourTwapPrice() public view returns (uint) {
 86 |         return stream.TWAP1Hour();
 87 |     }
 88 |     function getBTC2HourTwapPrice() public view returns (uint) {
 89 |         return stream.TWAP2Hour();
 90 |     }
 91 | 
 92 |     // ... 
 93 |     // ...
 94 | 
 95 |     // Returns Time-Weighted-Average-Price for 1 day.
 96 |     function getBTC1DayTwapPrice() public view returns (uint) {
 97 |         return stream.TWAP1Day();
 98 |     }
 99 | }
100 | ```
101 | 
102 | <!-- tabs:end -->
103 | 
104 | 
105 | 
106 | ## Get Historical Price Data
107 | * Each Data Stream is either updated every windowSize (e.g. 20 minutes) or when the latest data from data source is beyond the pre-determined threashold (e.g. ±0.5%) of last updated result, whichever happenes first.
108 | * Any specific historical data point can be obtained by calling `result(uint idx)`, along with other helper functions like `numPoints()`, `num24hPoints()`, `binarySearch(uint timedelta)` to get optimal parameter `idx`. Check [Stream.sol](https://github.com/DOSNetwork/smart-contracts/blob/master/contracts/Stream.sol) source code to meet advanced requirements.
109 | 
110 | 
111 | 
112 | ## Supported Assets & Data Sources
113 | * **Crypto**:
114 |   - Data Source 1: [Coingecko](https://www.coingecko.com/en/api)
115 |   - Supported Assets: `BTC/USD`, `ETH/USD`, `DOT/USD`, `HT/USD`, `DOS/USD`, `FIL/USD`, `HPT/USD`
116 | 
117 | * **Stocks**:
118 |   - Data Source 1: [IEXCloud](#)
119 |   - Data Source 2: [AlphaVantage](#)
120 |   - Supported Assets: [...]
121 | 
122 | * **Forex**: [...]
123 | 
124 | * **Commodities**: [...]
125 | 


--------------------------------------------------------------------------------
/homepage.md:
--------------------------------------------------------------------------------
 1 | ## Introduction
 2 | > DOS Network is a layer 2 chain-agnostic **D**ecentralized **O**racle **S**ervice network, providing real-time data feed oracle and computation oracle solution to mainstream blockchains.
 3 | 
 4 | <p align="center">
 5 |   <img width="460" height="300" src="https://raw.githubusercontent.com/DOSNetwork/docs/master/_media/overview.png">
 6 | </p>
 7 | 
 8 | Compared with other centralized or decentralized oracle solutions, DOS Network has many unique features making it the best choice for smart contract and Dapp developers:
 9 | - Fault tolerant and decentralized protocol - there's no single point of failure or downtime to break your Dapps. It's also an open membership network with crypto economy that tolerates malicious nodes and sybil attacks.
10 | - Not reputation based, but driven by secure, unmanipulatable and verifiable randomness - Reputation based system is prone to Matthew Effect, collusion, and targeted attacks that leads to many security issues.
11 | - Near real-time and verifiable response at a low cost - Built upon Verifiable Random Function and threshold cryptographic signatures, the response along with the proof of the response are delivered back on-chain together within only one transaction.
12 | 
13 | 
14 | ## Overview
15 | The vision is to offer standard and complete set of oracle services to mainstream blockchains. Right now it has been launched on Ethereum and Huobi HecoChain, however, we're actively exploring and integrating with other blockchains like Binance Smart Chain, OKExChain, Polkadot, etc.
16 | 
17 | In the high level DOS Network consist of two parts: on-chain smart contract part and off-chain P2P network (client) part:
18 | * **On-chain smart contract**: A set of DOS system contracts are deployed on supported blockchains, including functionalities such as request handling and response/computation result verification, node registration and staking, group public key registration, stats monitoring, payment processing, etc. On-chain system contracts expose a universal interface to all user contracts across supported chains.
19 | * **Off-chain P2P network**: A P2P network consists of client software implementing the core protocol running by node operators. Client includes several important modules: event monitoring and chain adaptor module, VRF module, off-chain group consensus module, response parsing module, verifiable computation module, etc.
20 | 
21 | 
22 | ## Recent update
23 | The **V1.0.3** has recently been released on March 2021 to support multi-chain data streams feacure. Currently a group consists of three nodes, with functionalities including threshold BLS group signing, on-chain aggregated BLS signature verification, verifiable random number generation, off-chain data query and secure random number request and so on.
24 | 
25 | Please check [developers guide](contents/blockchains/ethereum) and examples to start using our on-chain SDK to fetch external data and request secure random numbers within your smart contracts, and stay tuned for more updates and future releases.
26 | 
27 | Also join our [discord server]() to communicate with the devs and community members directly.
28 | 


--------------------------------------------------------------------------------
/index.html:
--------------------------------------------------------------------------------
 1 | <!DOCTYPE html>
 2 | <html lang="en">
 3 | <head>
 4 |   <meta charset="UTF-8">
 5 |   <title>Documentation for DOS Network - Decentralized Oracle Service Network</title>
 6 |   <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
 7 |   <meta name="description" content="Description">
 8 |   <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
 9 |   <!-- link rel="stylesheet" href="https://unpkg.com/docsify-themeable/dist/css/theme-simple-dark.css" -->
10 |   <link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
11 |   <!--style>
12 |     .markdown-section a {
13 |       color: #f38f02;
14 |     }
15 |   </style-->
16 |   <link rel="shortcut icon" href="_media/favicon.ico">
17 | </head>
18 | <body>
19 |   <div id="app"></div>
20 |   <script>
21 |     window.$docsify = {
22 |       name: 'DOS NETWORK',
23 | //      themeColor: '#dabf99',
24 |       repo: 'https://github.com/DOSNetwork/docs',
25 |       homepage: '/homepage.md',
26 |       logo: '/_media/logo-transparent.png',
27 |       search: 'auto',
28 |       loadSidebar: true,
29 |       alias: {
30 |         '/.*/_sidebar.md': '/_sidebar.md'
31 |       },
32 |       auto2top: true,
33 |       subMaxLevel: 2,
34 |       coverpage: true,
35 |       formatUpdated: '{MM}/{DD}/{YYYY}',
36 |       tabs: {
37 |         persist: true,
38 |         sync: true,
39 |         tabHeadings: true
40 |       },
41 |       plugins: [
42 |         function (hook, vm) {
43 |           hook.beforeEach(function (html) {
44 |             var url
45 |             if (/githubusercontent\.com/.test(vm.route.file)) {
46 |               url = vm.route.file
47 |                 .replace('raw.githubusercontent.com', 'github.com')
48 |                 .replace(/\/master/, '/blob/master')
49 |             } else {
50 |               url = 'https://github.com/DOSNetwork/docs/blob/master/' + vm.route.file
51 |             }
52 |             var editHtml = '[:memo: Edit Document](' + url + ')\n'
53 |             return html
54 |               + '\n\n----\n\n'
55 |               + 'Last modified {docsify-updated} '
56 |               + editHtml
57 |           })
58 |         }
59 |       ]
60 |     }
61 |   </script>
62 |   <script src="https://unpkg.com/docsify@4.11.3/lib/docsify.min.js"></script>
63 |   <!-- script src="https://unpkg.com/docsify/lib/docsify.min.js"></script -->
64 |   <script src="https://unpkg.com/docsify/lib/plugins/search.min.js"></script>
65 |   <script src="https://unpkg.com/docsify/lib/plugins/emoji.min.js"></script>
66 |   <script src="https://unpkg.com/docsify-copy-code@2"></script>
67 |   <script src="https://unpkg.com/docsify-tabs@1"></script>
68 |   <script src="https://unpkg.com/docsify/lib/plugins/zoom-image.min.js"></script>
69 |   <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-solidity.min.js"></script>
70 | </body>
71 | </html>
72 | 


--------------------------------------------------------------------------------
/package-lock.json:
--------------------------------------------------------------------------------
1 | {
2 |   "lockfileVersion": 1
3 | }
4 | 


--------------------------------------------------------------------------------