docs: add DEP docs

.gitbook/about-panacea/roadmap.md → .gitbook/0-about-panacea/1-roadmap.md

@@ -8,13 +8,13 @@ Now, MediBloc would like to shift its focus to boosting the potential of Panacea
 
 Nowadays, many businesses and technologies are data-driven. Many companies are already familiar with handling large dataset and deriving new values by analyzing sets of data. But, secure data exchange is still the one of the hardest area for data-driven industries. Data requesters want well-refined data or fine-grained raw data for successful data analysis. But, data owners (individuals) don’t want their privacy exposed and abused. Additionally, Web3 users are already aware that proper rewards should be guaranteed for their data and actions transparently on Web3. Traditional systems in Web2 have solved this issue in various ways, but MediBloc believes that we all can build more transparent and reliable systems for secure data exchange in Web3 ecosystem. 
 
-Our data exchange protocol has the concept of data Pool, so that anyone can specify the type and the quantity of the data they want. Also, they can specify how much cryptocurrency they are willing to pay for the data. All of these data pools are recorded in Panacea and everyone who wants to sell their data can see all data pools. Data sellers can choose data pools by checking how many parts of their data to be shared to data buyers. Then, they sign the consents for data exchange. Verified off-chain data validators validate whether data provided by data sellers conforms to criteria that data pool creator has specified. If all the requirements are met, the data is provided to data buyers via secure connections and the promised amount of cryptocurrency is transferred to data sellers. In this entire protocol, data is not recorded on any blockchain such as Panacea. All data transmissions are performed off-chain and Panacea guarantees all agreements for data exchanges and transparent payments.
+Our data exchange protocol has the concept of data Pool, so that anyone can specify the type and the quantity of the data they want. Also, they can specify how much cryptocurrency they are willing to pay for the data. All of these data pools are recorded in Panacea and everyone who wants to sell their data can see all data pools. Data providers can choose data pools by checking how many parts of their data to be shared to data consumers. Then, they sign the consents for data exchange. Verified off-chain data validators validate whether data provided by data providers conforms to criteria that data pool creator has specified. If all the requirements are met, the data is provided to data consumers via secure connections and the promised amount of cryptocurrency is transferred to data providers. In this entire protocol, data is not recorded on any blockchain such as Panacea. All data transmissions are performed off-chain and Panacea guarantees all agreements for data exchanges and transparent payments.
 
 This data exchange protocol is being developed to be as general as possible, so that not only the healthcare data but also all the other types of data can be handled by the protocol. Since Panacea and data exchange protocol is publicly opened, any service providers can build their own services on the top of the data exchange protocol, so that their users can exchange their data securely and get proper rewards. As the first use case, MediBloc is going to build a healthcare data marketplace service based on this protocol.
-Well, it sounds like the protocol should work well, right? However, there are so many issues that we have to resolve. For privacy and security, data sellers should be able to expose only a small part of their data that is really desired by data buyers. Data transmission must be secure, so that anyone cannot steal data. In order to guarantee the right of data buyers, all criteria that data buyers specified has to be validated clearly before the payment is finalized. In addition, the ecosystem should be attractive enough for many data sellers and buyers to join. 
+Well, it sounds like the protocol should work well, right? However, there are many issues that we have to resolve. For privacy and security, data providers should be able to expose only a small part of their data that is really desired by data consumers. Also, data transmission must be secure, so that no one can steal or intercept the data. In order to guarantee the right of data consumers, all criteria that data consumers specified has to be validated clearly before the payment is finalized. Last but not least, the ecosystem should be attractive enough for many data providers and consumers to join. 
 
 In order to resolve these challenges, the team is developing this data exchange protocol with several latest technologies.
-The detailed tech stack of the data exchange protocol is described in the [Panacea Ecosystem](./panacea-ecosystem.md) document.
+The detailed tech stack of the data exchange protocol is described in the [Panacea Ecosystem](./0-panacea-ecosystem.md) document.
 
-There will be more details that we have to solve, and we know that all of them cannot be achieved in one step. Hence, we will complete this big task step by step. In 2022, MediBloc will release the v0 of data exchange protocol as a proof of concept that includes only essential features. Also, a data marketplace web service will be introduced as a simple example service based on the protocol. Based on this proof of concepts, the data exchange protocol will be improved as v1 from 2023 with enhanced security and interoperability. MediBloc has already opened all source codes and progresses publicly on GitHub. We encourage anyone to join the project and share your insights. 
+There will be more detailed issues that we would have to solve, and we know that all of them cannot be solved in one step. Hence, we will complete this big task step by step. In 2022, MediBloc have released the v0 of data exchange protocol as a proof of concept that includes only essential features on testnet. Based on this proof of concepts, the data exchange protocol will be improved as v1 in 2023 with enhanced security and interoperability. Also, MediBloc will be introducing dApps for data providers using data exchange protocol and keep designing the services that go on top of data exchange protocol. MediBloc has already opened all source codes and progresses publicly on GitHub. We encourage anyone to join the project and share your insights. 
 We are so excited and thrilled to share our vision to achieve our goal to become the world’s best patient centric health data platform. Thank you for your continued support! 

.gitbook/1-users/3-data-exchange/0-about-dep.md

@@ -0,0 +1,43 @@
+# About Data Exchange Protocol
+
+Data Exchange Protocol (hereafter 'DEP') is a communication layer for sharing and exchanging various types of data
+between two parties in decentralized environments.
+
+
+## What can you do with DEP?
+
+Data consumers can open data deals by specifying the type, the quantity, and the pricing of the data that they are willing to consume. 
+
+Data providers can choose and participate in the deals that match the data that they have when they are willing to provide.
+
+To guarantee data consumers only consume data in the form they want,
+decentralized oracles verify and issue certificates for all data being provided by the data provider.
+
+Panacea public blockchain manages the status of all data deals and data sharing consents,
+ensuring data providers and ecosystem operators are rewarded appropriately.
+
+
+## Motivation and Goals
+
+### Data Ownership and Sovereignty
+
+The ultimate goal of owning our own data is having a control about how our data is used.
+
+### Decentralized off-chain data validation
+
+To ensure data consumers can only consume data that they want, all data being shared must be validated by
+decentralized players who are not malicious.
+
+### Privacy
+
+Throughout the entire process of data verification and transmission,
+the data content must not be exposed to anyone other than the consumer intended by the data provider.
+
+### Generalized data exchange
+
+Not only healthcare data, but various types of data should be covered through this protocol.
+
+### Open-sourced protocol
+
+All protocol specifications and implementations must be open-sourced, so any participants can understand
+how data is exchanged and how privacy is guaranteed.

.gitbook/1-users/3-data-exchange/1-consume-data.md

@@ -0,0 +1,108 @@
+# Consume data
+
+Data consumers can open data deals by specifying the type, the quantity, and the pricing of the data that they are willing to consume. 
+
+Data deals are registered in the Panacea public blockchain, so all data providers can find data deals, which match their data.
+
+
+## Create a data deal
+
+Broadcast the following `create-deal` transaction with specifying data schema, a data count, and a budget in the deal-file in JSON format.
+```bash
+panacead tx datadeal create-deal ${deal-file-path} \
+  --from ${data-consumer-addr} \
+  --chain-id ${chain-id} \
+  --gas auto --gas-adjustment 1.30 --gas-prices 5umed \
+  --node ${chain-node-rpc-addr}
+```
+
+For `deal-file-path`, create a following JSON file.
+```json
+{
+  "data_schema": [
+    "http://jsonschema.gopanacea.org/vaccination-cert.json"
+  ],
+  "budget": {
+    "denom": "umed",
+    "amount": "1000000"
+  },
+  "max_num_data": 10,
+  "consumer_address": "panacea1..."
+}
+```
+It is very important to set data schema specifically and correctly, so that data being provided can be validated accurately by oracles.
+
+For more details about data deals, please see the [Data Deal](../../3-protocol-devs/1-dep-specs/2-data-deal.md) specification.
+
+
+## Query deals
+
+You can query a deal with its deal ID.
+```bash
+panacead query datadeal deal ${deal-id} \
+  --node ${chain-node-rpc-addr}
+```
+Also, you can query all deals registered in the chain.
+```bash
+panacead query datadeal deals \
+  --node ${chain-node-rpc-addr}
+```
+
+
+## Query consents
+
+If some data providers have data that fit the requirements of your data deal, they will submit consents to the chain.
+The consent means that the data provider has agreed to provide their data to a specific data consumer.
+Also, each consent can contain a data validation certificate issued by an oracle, so that data consumers can trust the validity of data.
+
+As soon as data providers submit their consents, you can query all consents submitted to a specific data deal.
+```bash
+panacead query datadeal consents ${deal-id} \
+  --node ${chain-node-rpc-addr}
+```
+Or, you can query a specific consent, which contains a certain data hash.
+```bash
+panacead query datadeal consent ${deal-id} ${data-hash} \
+  --node ${chain-node-rpc-addr}
+```
+
+For more details about data consents, please see the [Data Provider Consent](../../3-protocol-devs/1-dep-specs/3-data-provider-consent.md) specification.
+
+
+## Access data
+
+A data validation certificate issued by an oracle contains the methods to access the data.
+For example, if the oracle decides to transmit data via [IPFS](https://ipfs.tech/), the certificate will contain a [CID](https://docs.ipfs.io/concepts/content-addressing/) of data.
+If so, you can access any IPFS node connected to the public IPFS network, and obtain the data.
+
+For more details about data validation certificates, please see the [Data Validation](../../3-protocol-devs/1-dep-specs/4-data-validation.md) specification.
+
+In general, the data transmitted is encrypted by oracles, so that only a specific data consumer is able to decrypt it.
+Using the following REST API, you can get a secret key of each data from the oracle that issued the data validation certificate.
+```bash
+curl -v -X GET -H "Authorization: Bearer ${jwt}" \
+  "${oracle-url}/v0/data-deal/secret-key?deal-id=${deal-id}&data-hash=${data-hash}"
+```
+You must specify a JWT issued using your account key in order to prove that you are the data consumer who created the data deal.
+For this authentication, the JWT must be signed by your (data consumer's) chain account private key.
+
+We highly recommend to set the expiration of JWT as short as possible for security reasons.
+You can use the `panacead` CLI to issue JWTs easily by the following command.
+In near future, the protocol will adopt the 'nonce' concept to improve the security of authentications.
+```bash
+panacead issue-jwt ${expiration-duration} --from ${your-account-key-name}
+
+# e.g.
+# panacead issue-jwt 10s --from panacea1zqum...
+```
+
+Please note that the returned secret key is also encrypted, so that only the specific data consumers can decrypt the key using his/her chain account private key.
+Nevertheless, we highly recommend you to communicate with oracles who provides an HTTPS endpoint with SSL/TLS encryption.
+
+Using the encrypted secret key that you obtained from the oracle, you can decrypt data by the following CLI.
+```bash
+panacead decrypt-data ${input-file-path} ${your-account-key-name} ${encrypted-secret-key} \
+  --node ${chain-node-rpc-addr}
+```
+This command will decrypt the secret key using your account key first, and decrypt the data using the decrypted secret key.
+So, please note that you should specify the `your-account-key-name` which is registered in the `panacead` keyring.

.gitbook/1-users/3-data-exchange/2-provide-data.md

@@ -0,0 +1,97 @@
+# Provide data
+
+Data providers can provide their data that match the requirements of the data deal and in return earn a reward.
+
+Since only the data verified by oracle can be provided to a deal, providers should first request data verification to oracle.
+
+As a result of verification, oracle will issue a certificate, then provider can provide their data by submitting a consent with the certificate to Panacea.
+
+In the whole process of data transmission, the data is encrypted so that no one can access the original data.
+
+The transmission of data and the payment of rewards are managed atomically through the Panacea, so consumers can get the data only when the reward payment is completed.
+
+## Request data verification to oracle
+
+Before request to oracle, you should encrypt your data for privacy preserving.
+Encryption can be done using your chain account key and oracle public key which is registered in Panacea.
+This makes only oracles can decrypt and verify your original data in secure area.
+For more details about data secure area, please see [Confidential Oracle](../../3-protocol-devs/1-dep-specs/5-confidential-oracle.md).
+
+You can encrypt data by the following CLI:
+```bash
+panacead encrypt-data ${input-file-path} ${your-account-key-name}
+```
+
+You must specify a JWT issued by yourself in order to prove that you are the data provider.
+For that authentication, the JWT must be signed by your (data provider's) chain account private key.
+
+We highly recommend to set the expiration of JWT as short as possible for security reasons.
+In the near future, the protocol will adopt the 'nonce' concept to improve the security of authentications.
+
+You can issue JWT by the following CLI:
+```bash
+panacead issue-jwt ${expiration-duration} --from ${your-account-key-name}
+
+# e.g.
+# panacead issue-jwt 10s --from panacea1zqum...
+```
+
+Using the following REST API, you can post encrypted data to oracle for verification with deal ID you want to provide.
+```bash
+curl -v -X POST -H "Authorization: Bearer ${jwt}" ${oracle-url}/v0/data-deal/deals/${deal-id}/data -d ${encrpyted-data-json-path}
+```
+
+For `encrpyred-data-json`, create a following JSON file.
+```json
+{
+  "provider_address" : "{your-address}",
+  "data_hash" : "{data-hash-of-original-data}",
+  "encrypted_data_base64" : "{encrypted-data}"
+}
+```
+You have to use data hash of original data with SHA-256 hash function. For example, you can get hash by following CLI:
+```bash
+sha256sum ${original-data-path}
+```
+
+Through this process, the data is safely and securely transmitted to oracle, and the oracle verifies the data hash and data schema.
+For more details about oracle data validation, please see the [Data Validation](../../3-protocol-devs/1-dep-specs/4-data-validation.md) specification.
+
+When the verification is completed, you can get a data certificate that includes the oracle's signature.
+The certificate form is like below:
+```json
+{
+  "unsigned_certificate" : {
+    "cid" : "{ipfs-cid}",
+    "unique_id" : "{oracle-unique-id}",
+    "oracle_address" : "{oracle-address}",
+    "deal_id": "{deal-id}",
+    "provider_address" : "{your-address}",
+    "data_hash" : "{data-hash}"
+  },
+  "signature" : "{oracle-signature}"
+}
+```
+Now you can use this certificate in the next step.
+
+## Submit consent
+
+Broadcast the following `submit-consent` transaction with certificate from oracle.
+```bash
+panacead submit-consent ${certificate-file-path} \
+  --from ${data-provider-addr} \
+  --chain-id ${chain-id} \
+  --gas auto --gas-adjustment 1.30 --gas-prices 5umed \
+  --node ${chain-node-rpc-addr}
+```
+
+After you submit consent, Panacea verifies the certificate and checks the status of the deal. 
+
+When the verification is completed, Panacea makes the data accessible to consumers and makes you can get reward.
+
+## Query consent
+You can query a consent by the deal ID and data hash you provided.
+```bash
+panacead query datadeal consent ${deal-id} ${data-hash} \
+  --node ${chain-node-rpc-addr}
+```

.gitbook/3-protocol-devs/1-dep-specs/0-overview.md

@@ -0,0 +1,19 @@
+# Data Exchange Protocol Specifications
+
+Prior to diving into the technical specifications of Data Exchange Protocol (hereafter 'DEP'),
+we recommend you to understand the definition of DEP, its motivation, and its goals from the [About DEP](../../1-users/3-data-exchange/0-about-dep.md) documentation.
+
+## Specifications
+
+In the following sections, you can find detailed protocol specifications including technical architectures, message formats,
+hardware requirements, and core implementation details.
+
+According to these specifications, protocol developers can make implementations
+based on various programming languages and infrastructure.
+
+1. [User Flow](1-user-flow.md)
+2. [Data Deal](2-data-deal.md)
+3. [Data Provider Consent](3-data-provider-consent.md)
+4. [Data Validation](4-data-validation.md)
+5. [Confidential Oracle](5-confidential-oracle.md)
+6. [Incentives](6-incentives.md)