diff --git a/.gitbook/about-panacea/panacea-ecosystem.md b/.gitbook/0-about-panacea/0-panacea-ecosystem.md similarity index 69% rename from .gitbook/about-panacea/panacea-ecosystem.md rename to .gitbook/0-about-panacea/0-panacea-ecosystem.md index 0bea0b2b..b52771cb 100644 --- a/.gitbook/about-panacea/panacea-ecosystem.md +++ b/.gitbook/0-about-panacea/0-panacea-ecosystem.md @@ -3,12 +3,12 @@ ## Mission -Allow patients to own their data, provide it, and get incentivized. +Allow patients to own their data, provide the data to data consumers, and get incentivized. ## Goal -Building decentralized healthcare data sharing/exchange protocols +Build decentralized healthcare data sharing/exchange protocols ## Tech Stack @@ -18,7 +18,7 @@ Building decentralized healthcare data sharing/exchange protocols ## Panacea blockchain -The Panacea is a public blockchain based on the Cosmos SDK and the Tendermint. +Panacea is a public blockchain based on the Cosmos SDK and the Tendermint. As the Tendermint implements a partially synchronous BFT (Byzantine fault-tolerant) consensus protocol, Panacea can provide a high-performance, consistent, and secure decentralized network @@ -51,11 +51,11 @@ Then, data verifiers (receivers) can verify that the data has been not tampered ### Data Exchange Coordination Panacea provides a feature of coordinating data exchange deals. -Data consumers can publish deals publicly, specifying which data they want to purchase and how much budget they are willing to pay. -And, data providers (holders) who agree to provide their data with consumers can provide their data securely and earn rewards in MED. +Data consumers can publish deals publicly, specifying 1) which data they want to purchase and 2) how much budget they are willing to pay. +Data providers (holders) who agree to provide their data with the data consumers can provide their data securely and earn MED as rewards. -This on-chain data exchange coordination must work with some off-chain components to verify data validity/integrity and securely deliver data. -For example, some malicious data providers can try to sell data that data consumers don't want or data that was generated by themselves (not by trusted issuers). +This on-chain data exchange coordination must work with some off-chain components to verify data validity/integrity and to deliver data securely. +For example, some malicious data providers ccould try to sell data that the data consumers don't want or that was forged by themselves (not by trusted issuers). Therefore, data should be validated by off-chain data validators before being delivered to data consumers, as described in the [Data Exchange Validation](#data-exchange-validation-with-confidential-computing) section. @@ -67,30 +67,26 @@ Using [Panacea Verifiable Credential SDK](https://github.com/medibloc/vc-sdk), d Since [Verifiable Credential](https://www.w3.org/TR/vc-data-model/) is a standard format defined by W3C, any data receivers can verify credentials without any compatibility issues using the data issuer's (holder's) cryptographic public key that is corresponding with their DID. In other words, the Verifiable Credential SDK works with DID management features of the Panacea blockchain. -In addition, data holders can present their data by masking privacy-sensitive fields that don't need to be revealed. -That can be achieved by Zero-knowledge Proof using BBS+ signatures so that data receivers can verify data integrity even though some fields in the data are masked (technically, ' tampered'). +In addition, data holders can present their data while masking privacy-sensitive fields. +This can be achieved by Zero-knowledge Proof using BBS+ signatures so that data receivers can verify data integrity even though some fields in the data are masked (technically, ' tampered'). ### Data Exchange Validation with Confidential Computing As described in the [Data Exchange Coordination](#data-exchange-coordination) section, Panacea blockchain provides data exchange coordination. However, data that is exchanged between providers and consumers cannot be validated/delivered through a public blockchain because all transaction data is exposed to everyone. Even if transaction data is encrypted, validator nodes should be able to decrypt data to verify data validity/integrity. That could be a huge vulnerability, allowing data to be leaked to anyone other than intended data consumers. -To avoid this vulnerability, we could implement this data exchange validation as smart contracts run on [Secret Network](https://scrt.network/), but still, we didn't want to expose private data on the public blockchain even if all data is encrypted. +To avoid this vulnerability, we could have implemented this data exchange validation as smart contracts run on [Secret Network](https://scrt.network/), but still, we didn't want to expose private data on the public blockchain even if all data is encrypted. Instead of solving this problem on chain, we have introduced an off-chain decentralized oracle powered by confidential computing ([Intel SGX](https://www.intel.com/content/www/us/en/developer/tools/software-guard-extensions/overview.html)). Like Secret Network, all oracle nodes are run in the secure enclave. All data is encrypted so that only oracle nodes can decrypt it to verify data validity/integrity. If data is verified successfully, it is re-encrypted by oracle nodes for the data consumer. Because this process is executed in the secure enclave, decrypted data cannot be stolen by anyone, even oracle node operators. -To avoid the Byzantine problem between decentralized oracle nodes, oracle nodes borrow the voting power from the Panacea blockchain. -Only operators who are running validators on Panacea can run oracle nodes. Then, an oracle node has the same voting power as a corresponding validator. -If an oracle node acts maliciously, its validator's stake is slashed. - ### Secure Data Storage -Based on DIDs, Verifiable Credentials, and Data Exchange Coordination/Validation, it seems that applications that handle privacy data can be implemented. -However, to actually implement applications, it must be decided specifically how data will be stored and how it will be transmitted in decentralized environments. +Based on DIDs, Verifiable Credentials, and Data Exchange Coordination/Validation, it seems that applications that handle privacy data can be implemented on top of Panacea. +However, to actually implement applications, the specific method on how data will be stored and how it will be transmitted in decentralized environments should be decided. Thanks to [IPFS](https://ipfs.io/), data can be transmitted by [content addressing](https://docs.ipfs.tech/concepts/content-addressing/) in environments where ecosystem participants don't know each other's IP addresses and ports. -But, IPFS is also a public network basically that is unsuitable for storing privacy data even if it is encrypted. IPFS also provides a way to set up private clusters, but it is not flexible enough to be used for data exchange based on public blockchains. +However, IPFS is also a public network, which is unsuitable for storing privacy data even if it is encrypted. IPFS also provides a way to set up private clusters, but it is not flexible enough to be used for based on public blockchains. -MediBloc team is researching many secure decentralized data storages including edge databases. \ No newline at end of file +To solve this problem, MediBloc team is still researching many secure decentralized data storages including edge databases. diff --git a/.gitbook/about-panacea/roadmap.md b/.gitbook/0-about-panacea/1-roadmap.md similarity index 60% rename from .gitbook/about-panacea/roadmap.md rename to .gitbook/0-about-panacea/1-roadmap.md index 7a4436cd..747319ec 100644 --- a/.gitbook/about-panacea/roadmap.md +++ b/.gitbook/0-about-panacea/1-roadmap.md @@ -8,13 +8,15 @@ 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! + +-- diff --git a/.gitbook/about-panacea/images/did-vc.png b/.gitbook/0-about-panacea/images/did-vc.png similarity index 100% rename from .gitbook/about-panacea/images/did-vc.png rename to .gitbook/0-about-panacea/images/did-vc.png diff --git a/.gitbook/about-panacea/images/did-vc.xml b/.gitbook/0-about-panacea/images/did-vc.xml similarity index 100% rename from .gitbook/about-panacea/images/did-vc.xml rename to .gitbook/0-about-panacea/images/did-vc.xml diff --git a/.gitbook/about-panacea/images/panacea-ecosystem.png b/.gitbook/0-about-panacea/images/panacea-ecosystem.png similarity index 100% rename from .gitbook/about-panacea/images/panacea-ecosystem.png rename to .gitbook/0-about-panacea/images/panacea-ecosystem.png diff --git a/.gitbook/about-panacea/images/panacea-ecosystem.xml b/.gitbook/0-about-panacea/images/panacea-ecosystem.xml similarity index 100% rename from .gitbook/about-panacea/images/panacea-ecosystem.xml rename to .gitbook/0-about-panacea/images/panacea-ecosystem.xml diff --git a/.gitbook/about-panacea/images/roadmap.png b/.gitbook/0-about-panacea/images/roadmap.png similarity index 100% rename from .gitbook/about-panacea/images/roadmap.png rename to .gitbook/0-about-panacea/images/roadmap.png diff --git a/.gitbook/about-panacea/images/tech-stack.png b/.gitbook/0-about-panacea/images/tech-stack.png similarity index 100% rename from .gitbook/about-panacea/images/tech-stack.png rename to .gitbook/0-about-panacea/images/tech-stack.png diff --git a/.gitbook/about-panacea/images/tech-stack.xml b/.gitbook/0-about-panacea/images/tech-stack.xml similarity index 100% rename from .gitbook/about-panacea/images/tech-stack.xml rename to .gitbook/0-about-panacea/images/tech-stack.xml diff --git a/.gitbook/users/overview.md b/.gitbook/1-users/0-overview.md similarity index 100% rename from .gitbook/users/overview.md rename to .gitbook/1-users/0-overview.md diff --git a/.gitbook/1-users/3-data-exchange/0-about-dep.md b/.gitbook/1-users/3-data-exchange/0-about-dep.md new file mode 100644 index 00000000..456e4600 --- /dev/null +++ b/.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 receive the data that match the criteria specified by them, +decentralized oracles verify and issue certificates for all data being provided by the data provider. + +Panacea 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 + +o guarantee data consumers only receive the data that match the criteria specified by them, +decentralized oracles verify and issue certificates for all data being provided by the data provider. + +### 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. diff --git a/.gitbook/1-users/3-data-exchange/1-consume-data.md b/.gitbook/1-users/3-data-exchange/1-consume-data.md new file mode 100644 index 00000000..e2ea94c8 --- /dev/null +++ b/.gitbook/1-users/3-data-exchange/1-consume-data.md @@ -0,0 +1,115 @@ +# 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 desired data schema and count, and budget specified 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...", + "agreement_terms": [ + { + "id": 1, + "required": true, + "title": "Terms of data provision", + "description": "The provided data will be used for ..." + } + ] +} +``` +It is very important to set data schema specifically and correctly, so that data being provided can be validated accurately by the 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 + +One can query a deal with its deal ID. +```bash +panacead query datadeal deal ${deal-id} \ + --node ${chain-node-rpc-addr} +``` +One can also 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 consumers') 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 should 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 (data consumer) 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 should contain 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 provide 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. diff --git a/.gitbook/1-users/3-data-exchange/2-provide-data.md b/.gitbook/1-users/3-data-exchange/2-provide-data.md new file mode 100644 index 00000000..3192859a --- /dev/null +++ b/.gitbook/1-users/3-data-exchange/2-provide-data.md @@ -0,0 +1,115 @@ +# Provide data + +Data providers can provide their data that match the requirements of the data deal and, in return, earn a reward in MED. + +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 Panacea, so consumers can get the data only when the reward payment is completed. + +## Request data verification to oracle + +Before requesting data verification to oracle, you (data provider) should encrypt the data to preserve privacy. +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 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": , + "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 the certificate from oracle and agreements of terms for data provision. + +**consent.json** + +```json +{ + "deal_id": , + "certificate": { + ... + }, + "agreements": [ + { + "id": 1, + "agreement": true + } + ] +} +``` + +```bash +panacead submit-consent ${consent-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 transmitts rewards to you. + +## 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} +``` diff --git a/.gitbook/dapp-devs/overview.md b/.gitbook/2-dapp-devs/0-overview.md similarity index 100% rename from .gitbook/dapp-devs/overview.md rename to .gitbook/2-dapp-devs/0-overview.md diff --git a/.gitbook/protocol-devs/overview.md b/.gitbook/3-protocol-devs/0-overview.md similarity index 100% rename from .gitbook/protocol-devs/overview.md rename to .gitbook/3-protocol-devs/0-overview.md diff --git a/.gitbook/3-protocol-devs/1-dep-specs/0-overview.md b/.gitbook/3-protocol-devs/1-dep-specs/0-overview.md new file mode 100644 index 00000000..2ddab77b --- /dev/null +++ b/.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) diff --git a/.gitbook/3-protocol-devs/1-dep-specs/1-user-flow.md b/.gitbook/3-protocol-devs/1-dep-specs/1-user-flow.md new file mode 100644 index 00000000..c0be8a4d --- /dev/null +++ b/.gitbook/3-protocol-devs/1-dep-specs/1-user-flow.md @@ -0,0 +1,103 @@ +# User Flow + +- Status: Draft +- Created: 2023-01-11 +- Modified: 2023-01-11 +- Authors + - Youngjoon Lee + - Gyuguen Jang + - Hansol Lee + - Myongsik Gong + - Inchul Song + - Tae Jin Yoon + + +## Synopsis + +This document specifies the entire user flow in the Data Exchange Protocol (hereafter 'DEP'). +This document defines the key players essential to operate the DEP, and describes how the players interact to complete the whole data exchange process. + +It is recommended to walk through this document first before diving deeply into detailed specifications. + +### Motivation + +DEP aims to establish a reliable communication layer between two parties who do not have strong trust in each other in decentralized environments. +To achieve this goal without centralized/authorized mediators, DEP introduces four key players: data consumer, provider, oracle, and chain validator. These key players collaborate to verify all aspects of the data exchange to minimize security/privacy vulnerabilities. + +### Definitions + +#### Key Players + +##### Data Consumer +A data consumer is an individual or an organization who wants to consume certain kinds of data for specific purposes, with or without paying. + +##### Data Provider +A data provider is an individual or an organization that holds data and a permission to provide data to data consumers to obtain benefits, such as incentives or services. + +##### Oracle (Oracle operator) +An oracle is a data validator that guarantees validity and integrity of the data before data is delivered from data providers to data consumers. +Data verification is essential to ensure the atomicity of data delivery and incentive payments. + +##### Panacea Blockchain Validator +A Panacea blockchain validator is a blockchain node operator that participates in the blockchain consensus process to guarantee the integrity of the whole process of DEP, which includes consuming data, providing data, validating data, and executing payments. + + +## Technical Specification + +![](images/user-flow.drawio.png) + +The diagram describes each key player interacts with each other to complete a cycle of data exchange. The whole process consists of several steps below. + +### Data Deal Registration + +A data consumer creates a data deal, specifying data schema, a budget in MED, the maximum number of data to consume, and agreement terms. The data consumer should publish the data deal to a public and secure environment, such as a public blockchain, to ensure that the data deal is not changed by anyone else after it is created. In this document, the Panacea blockchain is used for that public environment. For more details of the data deal, please see the [Data Deal](2-data-deal.md) specification. + +### Data Validation + +A data provider willing to provide data that meet the requirements desired by a data consumer should request a data validation to one of the verified oracles in the network. +The oracle validates the validity and integrity of data based on the requirements specified by the data consumer in the data deal. As a result of the data validation, the oracle issues a data validation certificate with a cryptographic signature. Also, the oracle uploads the data to the storage accessible by the data consumer. +The data is encrypted securely for each communication. For more details on the data validation and encryption, please see the [Data Validation](4-data-validation.md) and the [Confidential Oracle](5-confidential-oracle.md) specifications. + +### Consent Submission + +The data provider submits a consent of data provision, including the data validation certificate issued by the oracle. +The Panacea blockchain, operated by validators, validates the conformance and integrity of the consent and the data validation certificate. +For more details on the consent and the data validation, please see the [Data Provider Consent](3-data-provider-consent.md) and [Data Validation](4-data-validation.md) specifications. + +### Incentive Distribution + +As soon as the consent is accepted by the Panacea blockchain, the proper amount of MED coins are automatically distributed to the data provider and the oracle that issued the data validation certificate. +It is safe to distribute incentives right after the consent submission is accepted because the data consumer can immediately access the provided data. +The amount of incentives for each data provision is calculated by the total budget and the maximum number of data to consume specified by the data consumer in the data deal. The distribution ratio between the data provider and the oracle is determined by the commission rate promised by the oracle in the Panacea blockchain. +For more details, please see the [Incentives](6-incentives.md) specification. + +### Data Delivery + +As a result of the [Data Validation](#data-validation) and [Consent Submission](#consent-submission), the encrypted data is uploaded to the storage, and the data consumer can obtain the unique identifier of the data stored in the storage from the Panacea blockchain. Using the unique identifier, the data consumer fetches the encrypted data from the storage. +To decrypt the data, the data consumer requests a secret key to the oracle that validated the data and issued the validation certificate contained in the submitted consent. + + + +## Backwards Compatibility + +Not applicable. + +## Forwards Compatibility + +To be described. + +## Example Implementations + +TODO: Repo URLs of panacea-core and panacea-oracle with specific tags + +## Other Implementations + +None at present. + +## History + +- 2023-01-11: Initial draft finished + +## Copyright + +All content herein is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). diff --git a/.gitbook/3-protocol-devs/1-dep-specs/2-data-deal.md b/.gitbook/3-protocol-devs/1-dep-specs/2-data-deal.md new file mode 100644 index 00000000..2e97da5a --- /dev/null +++ b/.gitbook/3-protocol-devs/1-dep-specs/2-data-deal.md @@ -0,0 +1,132 @@ +# Data Deal + +- Status: Draft +- Created: 2023-01-03 +- Modified: 2023-01-03 +- Authors + - Youngjoon Lee + - Gyuguen Jang + - Hansol Lee + - Myongsik Gong + - Inchul Song + - Tae Jin Yoon + + +## Synopsis + +This document defines a data deal which is a contract for data collecting and payment for data provision in [DEP](../../1-users/3-data-exchange/0-about-dep.md). +Data consumers create 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. +When a data provider provides data to the deal, the payout is distributed to the provider and the oracle that validated the data. +Also, data consumers can deactivate their data deal whenever they want and the remaining budget would be refunded to the consumer's account. + +### Motivation + +Data consumers want different types of data, and even for the same type of data, they all differ in the desired quantity and desired cost of the data. +Thus, the data deal was devised so that data consumers can determine the type of data they want, the quantity they want, and the cost level they want. + +### Definitions + +`Data Provider`, `Data Consumer` and `Oracle` are defined in [User Flow](./1-user-flow.md) + +## Technical Specification + +Data consumers should be able to post the information described below publicly, so that any data provider can see it. +Also, data providers should be assured that a particular data consumer really posted the information. +To meet these requirements, it is recommended to use a public decentralized state machine as a single source of truth, such as Panacea. + +### Data Structure of Deal + +The structure of data deal. + +```proto +message Deal { + uint64 id = 1; + string address = 2; + repeated string data_schema = 3; + cosmos.base.v1beta1.Coin budget = 4; + uint64 max_num_data = 5; + uint64 cur_num_data = 6; + string consumer_address = 7; + repeated AgreementTerm agreement_terms = 8; + DealStatus status = 9; +} + +message AgreementTerm { + uint32 id = 1; + bool required = 2; + string title = 3; + string description = 4; +} +``` + +- `id`: Auto increment id +- `address`: An address of deal generated when deal is created +- `data_schema`: A list of URLs of desired data schema +- `budget`: A budget for consuming data +- `max_num_data`: The maximum number of data the consumer want +- `cur_num_data`: The current number of data provided +- `consumer_address`: A consumer's account address of the form `panacea1...` +- `agreement_terms`: Terms of agreement of data provision +- `status`: The status of deal. 3 statuses can be possible + - `DEAL_STATUS_ACTIVE`: The status when deal is active (`cur_num_data` < `max_num_data`). + - `DEAL_STATUS_INACTIVE`: The status when deal is deactivated (when consumer deactivated the deal) + - `DEAL_STATUS_COMPLETED`: The status when deal is completed (`max_num_data` of data is provided) + +### Create Data Deal + +Data consumers can create their deal with the followings: + +```proto +message MsgCreateDeal { + repeated string data_schema = 1; + cosmos.base.v1beta1.Coin budget = 2; + uint64 max_num_data = 3; + string consumer_address = 4; + repeated AgreementTerm agreement_terms = 5; +} +``` + +When deal is created, the amount of budget is sent from consumer's account to deal's account. +In other words, the balance of consumer's account should be greater or equal than the budget. + +### Deactivate Data Deal + +The consumer who created the deal can deactivate the deal at any time as long as `max_num_data` of data is not provided. + +To deactivate a deal, the id of the deal should be specified. + +```proto +message MsgDeactivateDeal { + uint64 deal_id = 1; + string requester_address = 2; +} +``` + +When a deal is deactivated, all ramining budget is refunded to the data consumer's account. +After the deal is deactivated, data providers cannot provide their data to this deal, and the status of the deal changes to `DEAL_STATUS_INACTIVE`. + +## Backwards Compatibility + +Not applicable. + +## Forwards Compatibility + +For now, JSON schema validation is used for data validation. +It can be expanded using JSON-LD contexts for verifiable credentials in the future. + +## Example Implementations + +Coming soon. + +## Other Implementations + +None at present. + +## History + +- 2023-01-03: Initial draft finished + +## Copyright + +All content herein is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). diff --git a/.gitbook/3-protocol-devs/1-dep-specs/3-data-provider-consent.md b/.gitbook/3-protocol-devs/1-dep-specs/3-data-provider-consent.md new file mode 100644 index 00000000..559e54cf --- /dev/null +++ b/.gitbook/3-protocol-devs/1-dep-specs/3-data-provider-consent.md @@ -0,0 +1,106 @@ +# Data Provider Consent + +- Status: Draft +- Crated: 2023-01-04 +- Modified: 2023-01-04 +- Authors + - Youngjoon Lee + - Gyuguen Jang + - Hansol Lee + - Myongsik Gong + - Inchul Song + - Tae Jin Yoon + + +## Synopsis + +This document is about providing data through [DEP](../../1-users/3-data-exchange/0-about-dep.md). +Before data providers provide their data to data consumers, the data must be validated by oracle whether it matches the data type specified in the deal. + +Data providers can send a request for validation to one of the oracles registered in Panacea, and the oracle will validate the data using confidential computing without any exposure to the data. +As a result of the data validation, oracle will issue a certificate to the provider. +Providers can consent to provide their data by submitting the certificate to Panacea, and will be rewarded by providing the data. +In all of these processes, the data is transmitted with encryption and stored off-chain. + +### Motivation + +Data should be provided by providers based on their data ownership, and the reward should be distributed in transparent and fair manner. +To do so, providers use digital signature as consent to provide the data. + +### Definitions + +- `Data Provider`, `Data Consumer`, and `Oracle` are defined in [User Flow](./1-user-flow.md) +- `Deal` is defined in [Data Deal](./2-data-deal.md) +- `Certificate`: a certificate that the data is validated to be provided to the deal, which is issued by oracle. + +## Technical Specification + +Before a data provider provides data to a deal, the data should be validated by the oracle. +If the data is successfully validated, the provider will receive a `Certificate` like below (more about [Data Validation](./4-data-validation.md)): + +```proto +message Certificate { + UnsignedCertificate unsigned_certificate = 1; + bytes signature = 2; +} + +message UnsignedCertificate { + string cid = 1; + string unique_id = 2; + string oracle_address = 3; + uint64 deal_id = 4; + string provider_address = 5; + string data_hash = 6; +} +``` + +Using the `Certificate`, the data provider can submit a consent to provide the data with agreement of terms. + +```proto +message MsgSubmitConsent { + Consent consent = 1; +} + +message Consent { + uint64 deal_id = 1; + Certificate certificate = 2; + repeated Agreement agreements = 3; +} + +message Agreement { + uint32 term_id = 1; + bool agreement = 2; +} +``` + +When this consent is submitted, blockchain will check: +- if the data is provided by the owner of the data +- if the data is validated by a registered and active oracle +- if the data is provided in duplicate +- if the provider agrees to the required terms of agreement + +If all checks pass, rewards are distributed to the data provider and the oracle(more about [incentive](./6-incentives.md)). + +## Backwards Compatibility + +Not applicable. + +## Forwards Compatibility + +Not applicable. + +## Example Implementations + +Coming soon. + +## Other Implementations + +None at present. + +## History + +- 2023-01-04: Initial draft finished + +## Copyright + +All content herein is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). diff --git a/.gitbook/3-protocol-devs/1-dep-specs/4-data-validation.md b/.gitbook/3-protocol-devs/1-dep-specs/4-data-validation.md new file mode 100644 index 00000000..d7878997 --- /dev/null +++ b/.gitbook/3-protocol-devs/1-dep-specs/4-data-validation.md @@ -0,0 +1,201 @@ +# Data validation + +- Status: Draft +- Created: 2023-01-04 +- Modified: 2023-01-04 +- Authors + - Gyuguen Jang + - Youngjoon Lee + - Hansol Lee + - Myongsik Gong + - Inchul Song + - Tae Jin Yoon + + +## Synopsis + +This document describes the API specification, data verification, and certificate issuance. + +### Motivation +Data consumers can define their requirements. +This requirement allows them to define the format of the data they want. +DEP supports `JSON schema` to define these requirements. +Oracle can verify the requirements of data consumers according to this JSON schema specification. +Oracle issues a certificate upon successful verification, which can be verified by Panacea. + +### Definitions +`Data Provider`, `Data Consumer`, and `Oracle` and [JSON schema](https://www.w3.org/2019/wot/json-schema) + +## Technical Specification + +### API Specification + +#### Request URI +```http request +POST /v0/data-deal/deals/{dealID}/data +``` + +#### Request Headers +``` +# Authorization: Bearer {jwtToken} +# Content-Type: application/json +``` + +TODO: Guide to JWT generate and verify + +#### Request Body +``` +{ + "provider_address": "panacea1ewugvs354xput6xydl5cd5tvkzcuymkejekwk3", + "encrypted_data_base64": "3TpdyLXP0xObMWYev8XwqlKjxzWsP5OiQQjq6MooWUwiP37JGqFgl8Rv+a43RMoNieSmBml2AeE1M3sIn39T3R3FD5nqOcFx2MbsnUYHMVASzv5mv53EYx+mP/aPl7pTeMCioQkRqXCyNrj+EJVQEoUdt2DgJwstia3O5pFFRUViKdVJsGIpDX8vY7qQdNuId/beVqWpL5ffSayZnQg=", + "data_hash": "13341f91f0da76d2adb67b519e2c9759822ceafd193bd26435ba0d5eee4c3a2b" +} +``` +| Key | Type | Description | +|-----------------------|--------|------------------------------------------------------------------| +| provider_address | string | Data provider's account address | +| encrypted_data_base64 | string | Base64-encoded value after encrypt the original data | +| data_hash | string | A hexadecimal string of a SHA256 hash value of the original data | + +#### Response Headers +``` +# Content-Type: application/json +``` + +#### Response Body +```json +{ + "unsigned_certificate": { + "cid": "QmeSiVLXWagUv9sLEHvbsUJy8rm7r5BoP2pAXrbx4pdbWi", + "unique_id": "9a3da3162aa592af3c77f1bba2d5635c7b4c065249bd36094fe3c11c73c90618", + "oracle_address": "panacea1ewugvs354xput6xydl5cd5tvkzcuymkejekwk3", + "deal_id": 1, + "provider_address": "panacea1ewugvs354xput6xydl5cd5tvkzcuymkejekwk3", + "data_hash": "13341f91f0da76d2adb67b519e2c9759822ceafd193bd26435ba0d5eee4c3a2b" + }, + "signature": "MEQCIEPyGSe9wVIjrUFuzXtQtEc0siwaHkp4QJCMBvC8ttWQAiAUkntIQldgIkIBFdthaTRWXHisDV2Ys/Ufpc9zejUEuQ==" +} +``` + +| Key | Type | Description | +|---------------------------------------|--------|------------------------------------------------------------------------------| +| unsigned_certificate | Object | Unsigned certificate containing data validation information | +| unsigned_certificate.cid | string | A content identifier of a file in IPFS | +| unsigned_certificate.unique_id | string | UniqueID of the oracle that validated the data | +| unsigned_certificate.oracle_address | string | Account address of the oracle that validated the data | +| unsigned_certificate.deal_id | uint | Deal to whom the provider intends to provide data | +| unsigned_certificate.provider_address | string | Data provider's account address | +| unsigned_certificate.data_hash | string | A hexadecimal string of a SHA256 hash value of the original data | +| signature | string | Base64-encoded string signed `unsigned_certificate` with Oracle private key. | + + +### Data validation process + +#### Data Decryption +Provider's encrypted data(`encrypted_data_base64`) can only be decrypted by oracle. + +``` +secret_key = SHA256(ECDH(oracle_private_key, provider_public_key)) + +encrypted_data = Base64.Decode(encrypted_data_base64) + +orginal_data = AES256GCM.Decrypt(secret_key, encrypted_data) +``` + +#### Data Validation +Verify that the original data matches the `data_hash`. +``` +compare(data_hash, Hex.Encode(SHA256(orginal_data)) +``` + +Verify that the `provider_address` of the original data matches the JWT auth token issuer of the request header. +``` +compare(provider_address, jwtToken.issuer) +``` + +The deal information can be retrieved from Panacea using the deal ID + +Before verifying the data, Oracle should check whether the deal status is valid. +If the Deal's status is invalid, oracle does not perform verification work. +``` +compare(deal.status, 'DEAL_STATUS_ACTIVE') +``` + +Validate original data with `data_schema` extracted from Deal. +We currently support JSON schema. +``` +data_schema = deal.data_schema + +JSONSchema.Validate(data_schema, orginal_data) +``` + +#### Data re-encryption and delivery via IPFS + +If data validation is successful, the data must be re-encrypted and stored on IPFS to be delivered to the consumer. + +To re-encrypt the data, a symmetric secret key must be used. The symmetric secret key can be derived from the following logic. +``` +deal_id_bz = convertUint64ToBigEndian(deal_id) +secret_key = SHA256(append(oracle_private_key, deal_id_bz, data_hash)) +``` + +After encrypting the data with the generated `secretKey`, store it to IPFS. + +``` +encrypted_data = AES256GCM.Encrypt(secret_key, orginal_data) + +cid = IPFS.add(encrypted_data) +``` + + +#### Certificate issuance with a cryptographic signature +If all processes succeed, oracle responds to the Provider by issuing a certificate. + +The certificate includes the following contents. +```json +{ + "unsigned_certificate": { + "cid": "QmeSiVLXWagUv9sLEHvbsUJy8rm7r5BoP2pAXrbx4pdbWi", + "unique_id": "9a3da3162aa592af3c77f1bba2d5635c7b4c065249bd36094fe3c11c73c90618", + "oracle_address": "panacea1ewugvs354xput6xydl5cd5tvkzcuymkejekwk3", + "deal_id": 1, + "provider_address": "panacea1ewugvs354xput6xydl5cd5tvkzcuymkejekwk3", + "data_hash": "13341f91f0da76d2adb67b519e2c9759822ceafd193bd26435ba0d5eee4c3a2b" + }, + "signature": "MEQCIEPyGSe9wVIjrUFuzXtQtEc0siwaHkp4QJCMBvC8ttWQAiAUkntIQldgIkIBFdthaTRWXHisDV2Ys/Ufpc9zejUEuQ==" +} +``` + +The certificate requires a signature signed with `oracle_private_key` because Panacea needs to be able to verify that the certificate was generated by a trusted oracle. +The `oracle_public_key` registered in Panacea is a pair with the `oracle_private_key` of a trusted oracle. +So, Panacea can verify signature of the certificate with `oracle_public_key` to ensure that the certificate is correct. + +Signature is a value obtained by signing `unsigned_certificate` with `oracle_private_key`. +``` +signature = sign(oracle_private_key, unsigned_certificate) +``` + + +## Backwards Compatibility + +Not applicable. + +## Forwards Compatibility + +If the JSON-LD validation specification is applied in the future, oracle will also be support. + +## Example Implementations + +TODO: Repo URLs of panacea-core and panacea-oracle with specific tags + +## Other Implementations + +None at present. + +## History + +- 2023-01-04: Initial draft finished + +## Copyright + +All content herein is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). diff --git a/.gitbook/3-protocol-devs/1-dep-specs/5-confidential-oracle.md b/.gitbook/3-protocol-devs/1-dep-specs/5-confidential-oracle.md new file mode 100644 index 00000000..d26d40db --- /dev/null +++ b/.gitbook/3-protocol-devs/1-dep-specs/5-confidential-oracle.md @@ -0,0 +1,72 @@ +# Confidential Oracle + +- Status: Draft +- Created: 2023-01-06 +- Modified: 2023-01-06 +- Authors + - Inchul Song + - Youngjoon Lee + - Gyuguen Jang + - Hansol Lee + - Myongsik Gong + - Tae Jin Yoon + +## Synopsis + +This document explains why the oracles must use confidential computing. + +## Motivation + +In DEP, the data must be verified as explained in the [data validation documentation](./4-data-validation.md). +Verifying data means that the content of the data could be shown to the oracle. However, no one would want their data to be +exposed to the oracle for data verification. There may also be malicious oracles that exploit the data unfairly. To +prevent this, we have designed the oracle in DEP with confidential computing. Confidential computing guarantees that only +selected code (binary) can access data in the secure enclave. Also, it could protect a sensitive data from being leaked +by malicious operators while verifying the data correctly in this decentralized system. + +## Confidential Oracle + +Without confidential computing, the oracle operators(human) could see the content of sensitive data. +For example, if the oracle software stores important sensitive data to the disk or storage without sealing it, +it can be read by anyone who can access the disk or the storage. +So we developed the confidential oracle for preventing the case from the malicious oracle by using below sections. + +### Technical Specification + +For confidential computing environment, we chose Intel SGX, which offers hardware-based memory +encryption for data security, using [Microsoft Azure Confidential Computing VM](https://learn.microsoft.com/en-us/azure/confidential-computing/overview). +Also, we chose [EGo](https://www.edgeless.systems/products/ego/) SDK, which enables the development of confidential apps +written in Go language. + +### Oracle Key + +The oracle key is an asymmetric key that should be shared across all oracles. The request from a data provider and a data consumer that +an oracle receives must be encrypted by the oracle public key. If the secure data encryption and decryption need to be +performed, the corresponding the oracle private key must be held by every oracle securely. How all oracles share the oracle +private key and how they store this key securely will be described in the next section. + +### Oracle Key Handshake + +The oracle private key is sealed by a unique ID, which is derived from the Intel SGX enclave. + +If an oracle operator modifies the source code of the oracle, this unique ID will be changed. +If a malicious oracle operator modifies the source code of the oracle to print logs of sensitive data or to leak the data to somewhere else, it could cause a serious privacy problems. + +This means that the all oracle operators must only use the genuine binary built by selected code. +Only the genuine binary can unseal the data in the SGX secure enclave. +"Rewrite this section" +If the oracle wants to register, it must use remote report composed of the promised security version and unique ID. +So the one of the oracle approves the registration if the new oracle's remote report is valid. +If you want a register the oracle, you can verify remote report that is valid or not using +[CLI](../../5-oracles/7-verfiy-remote-report.md). After the oracle registration passed, the new oracle can retrieve the shared oracle +private key. + +### Sealing Secrets and States + +All secrets and important information, such as the shared oracle private key and the state of blockchain light client, +must be sealed before it is stored to the disk, so that anyone outside the enclave cannot read it. The sealing must be +done with the unique ID of the enclave, so that any modified enclave cannot unseal secrets. + +So how to we set a correct unique ID and how to know it is not malicious binary? The correct unique ID will be +determined by Panacea governance. We can know the correct unique ID from Panacea as Single Source of Truth(SSOT), +and know that what the correct genuine binary is. diff --git a/.gitbook/3-protocol-devs/1-dep-specs/6-incentives.md b/.gitbook/3-protocol-devs/1-dep-specs/6-incentives.md new file mode 100644 index 00000000..eeb639bb --- /dev/null +++ b/.gitbook/3-protocol-devs/1-dep-specs/6-incentives.md @@ -0,0 +1,82 @@ +# Incentives + +- Status: Draft +- Created: 2023-01-06 +- Modified: 2023-01-06 +- Authors + - Youngjoon Lee + - Gyuguen Jang + - Hansol Lee + - Myongsik Gong + - Inchul Song + - Tae Jin Yoon + + +## Synopsis + +When a data deal is created, a budget for the data is deposited from the data consumer account. +The deposit, proposed by the data consumer, is distributed to the data providers and the oracles that verified the data when the data provider submits a consent with the certificate to Panacea. +Data consumers can [deactivate the deal](./2-data-deal.md#Deactivate-Data-Deal) that they created and retrieve the remaining budget at any time if the deal is in status `DEAL_STATUS_ACTIVE`. + +### Motivation + +This is for a transparent distribution of the incentives for providing the data and verifying the data. + +### Definitions + +`Data Provider`, `Data Consumer` and `Oracle` are defined in [User Flow](./1-user-flow.md) + +## Technical Specification + +### Budget Deposit + +When data consumers [create a deal](./2-data-deal.md#create-data-deal), they specify a budget for data provision. +At this time, the total amount of the budget is transferred from the data consumer account to the deal account. + +### Reward Distribution + +When creating a data deal, data consumers specify the quantity as well as the budget for the data. +From these two values, the price per data can be calculated as: + +``` +price_per_data = deposit / max_num_data +``` + +When a data provider submits a consent and a certificate, a portion of the `price_per_data`, is transferred to the oracle and the rest is transferred to the data provider. +This portion is associated with the oracle commision rate that can be set differently for each oracle. + +The data consumer can find out which oracle verified the data by referring to the [certificate](./4-data-validation.md#Response-Body) submitted by the data provider and how much commission fee was paid. + +``` +oracle_reward = price_per_data * oracle_commission_rate +provider_reward = price_per_data * (1 - oracle_commission_rate) +``` + +### Budget Refund + +If consumers want to stop receiving the data and get refund for the rest of their budget, they can deactivate the deal they created. +However, in order to deactivate the deal, the deal must be in the `DEAL_STATUS_ACTIVE` state. + +## Backwards Compatibility + +Not applicable. + +## Forwards Compatibility + +Not applicable. + +## Example Implementations + +Coming soon. + +## Other Implementations + +None at present. + +## History + +- 2023-01-06: Initial draft finished + +## Copyright + +All content herein is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0). diff --git a/.gitbook/3-protocol-devs/1-dep-specs/images/user-flow.drawio.png b/.gitbook/3-protocol-devs/1-dep-specs/images/user-flow.drawio.png new file mode 100644 index 00000000..709306f0 Binary files /dev/null and b/.gitbook/3-protocol-devs/1-dep-specs/images/user-flow.drawio.png differ diff --git a/.gitbook/3-protocol-devs/1-dep-specs/images/user-flow.drawio.xml b/.gitbook/3-protocol-devs/1-dep-specs/images/user-flow.drawio.xml new file mode 100644 index 00000000..ce2aa1da --- /dev/null +++ b/.gitbook/3-protocol-devs/1-dep-specs/images/user-flow.drawio.xml @@ -0,0 +1,2 @@ + +3VpZk6M2EP41rso+jAshg+3HuXaTqt2Kk6lKso8akG0ygLxCjO38+rRAMgjBGK+POV5cqNUIqfvrUx7g22TzhZPV8hsLaTxwnXAzwHcD151OR/ArCduS4CNFWPAoLEmoIjxE/1FFdBQ1j0KaGYyCsVhEK5MYsDSlgTBohHO2NtnmLDa/uiILahEeAhLb1L+jUCxL6sRzKvqvNFos9ZeRo2YSopkVIVuSkK1rJHw/wLecMVE+JZtbGkvZabmU733umN1tjNNU9HnBLV94JnGuzjYjKQkoAeJNzIKnYEmiVO1VbLUAOMvTkMo1nAG+WS8jQR9W8BoQ1qBxoC1FEsMIwWNMHmk8Y1kkIpYCLYC9UQ4Tz5SLCKT6tcEgmFyBxNGilf1aTTwyIVgCE+oMME03nXJAO+kCKilLqOBbYNEvTJVCFCJHariu1LtD37KuWqyIREFqsVu6kjo8KMG3KwFbSnA/wfhP+iOnmZCLS1shgpRMETxKQbl+DLu4eeTwtBCFHHySSNGlj9mqGDstpHUEJ4I1YQGHpgHfrgRoUn+goWgaAvDVkHGxZAuWkvi+ot6YUKh4vjKpxQIA/1IhtsqKSS6YCQ/QEN/+o94vBt/lYOh6eny3qc/ebdWoiSteqqUnrGI6F/tBJc9v+hnCF1Qr3zsUZldwLAf5BtTUIpzGoNZn82ttqFKLz1iUimrliYlf7DVwmbGcB1S9VEHzmnOyrbGtJEPW+zMjPGkAvVyw8bJenc3nGRWDpmns5NTLWkaWtXjSWh7yxyTSxgKOP6PqpJeG8yYSBZqHnhp91+iF5wrKcrCtDWaURyAF6ekqrLeYxT6r6MBtqX8DcQaU+3vM3kDt6/48S6F3pa+bcfYMgZ5baoSouZKPeRJfB4K9FEt29tw09NIb1BTHchFHKb3d5QyVNI8KLZ5pMq7vWqEFt0QW/wSBxbcki6Sp3HJKBDXjSkhJ/CHMBR1mLhdKTl60x+lR9qhg5gwRnvjHxZKT+umxBb6pndVkNODyS84T3b4h+O1G/QHYX8+n9LHtUdq1stmGMymhZmUDP6HliaXlidTyl0KpbybHnLNUqEkkxxkIQFzLShAoKUuppn2O5EmVnwg1RxCTLIuCkqhYULfOz69gb+L9VLq3d6EzImXaFeYh4mZ58u7D/Pj14ryuTGuytYS5ACNadZ5TdUrIo2Z3Dj2/i5Fx/rFdQaO2809OcX7Uha27Iq2BT+jdvfMmhtOug4sI2e4VXUkJl4LOgiVNiN2TkCzf7oHZuclDmd60c5BNlYoGoJcOvusFpzQpKjsH5JlkllJBesLUXCY4ewJ7j6UD0c5+Dk68QdrTGEiiMCyCURtQTCgdpcqNkbpvTQOv69k9lzOx21EjGdJ/y7JcFw31LpQTSEnNQVaypnjFFO6ABK5HsnZ4c8cZOt5oaupNyfLIcD/e09zpCNJnSuyR3YEZS4D8kdNCHLUGjG2fFwQEMgAx3pPS79ottcZj+eauouwoIYtRsxxoxouGV+nMX7QXajYzzXzGyF+r7LSewiIzhVVOrspf+5pBS9/zDHVMb+dkN4t+5ySIbc/zHqP7ywnWqFHU6XuDWlCYnism2J0kS+DvKlvHqFkh+3aEHdvCxKMTCNPujCDnU5GsFpXyK9bJJ6qLD72Z2eVWfXOwDsfVQ/9bw4UdGZd9NDFQ5E5cc4m+ZXhzIew2FuqI8Ide3/i4fcOd+8Lt+7rkfQ+yW0wP4F7kFb2qEWR3xzAV/0fO9MRVVoD9GhiQs9oU4NHz1cWp8wsdLoYyy519fvikF4atlWtrto8eYzzcjDEthUfbPbjvncAv2h0iLN3iLNfd4pSuY7nbt9BSbM8y+yaZg4MuKS7bvmyrgoy7icnp879294PHYxOOuAGzE91q4ybsPfyiW7T2ZfKbbvEnXJ5r9/P+Kituxu2SquzsvaaDOb57iMaNwIQsv4PR0DtPQuba7UNLyG8su3V7NALPlL5q4XwAaeksRwPrEtKzu2vvXHpodEnxjV4z1uvekAr3eqo92IckWxYfvfwFZFsD5wK3zj4ejtHInXjlr+nRz3iz2PIPIl8mjuW9Q5TKyAbHetVm5EHQqTUjx6doRr4xKNaTyf5d9sPQeWgK6PojMwHxX/hn436MwrD6E3fJXv0THt//Dw== \ No newline at end of file diff --git a/.gitbook/validators/overview.md b/.gitbook/4-validators/0-overview.md similarity index 100% rename from .gitbook/validators/overview.md rename to .gitbook/4-validators/0-overview.md diff --git a/.gitbook/validators/cli-installation.md b/.gitbook/4-validators/1-cli-installation.md similarity index 100% rename from .gitbook/validators/cli-installation.md rename to .gitbook/4-validators/1-cli-installation.md diff --git a/.gitbook/validators/deploy-localnet.md b/.gitbook/4-validators/2-deploy-localnet.md similarity index 100% rename from .gitbook/validators/deploy-localnet.md rename to .gitbook/4-validators/2-deploy-localnet.md diff --git a/.gitbook/validators/join-mainnet-testnet.md b/.gitbook/4-validators/3-join-mainnet-testnet.md similarity index 96% rename from .gitbook/validators/join-mainnet-testnet.md rename to .gitbook/4-validators/3-join-mainnet-testnet.md index 31bdb1be..56ca4447 100644 --- a/.gitbook/validators/join-mainnet-testnet.md +++ b/.gitbook/4-validators/3-join-mainnet-testnet.md @@ -9,13 +9,13 @@ This tutorial introduces deploying a new node on [AWS](https://aws.amazon.com/) Choose Ubuntu Server 20.04 LTS 64-bit (x86) with SSD Volume Type. -![](../assets/fullnode/ec2-ami.png) +![](images/ec2-ami.png) ### Choose the instance type Choose the `m5.large` instance type (minimum spec). -![](../assets/fullnode/ec2-instance-type.png) +![](images/ec2-instance-type.png) ### Configure instance details @@ -59,7 +59,7 @@ So, expose them to the network where you perform operational actions. ssh ubuntu@ -i .pem ``` -Install prerequisites by following the [Installation](cli-installation.md) guide. +Install prerequisites by following the [Installation](1-cli-installation.md) guide. ## Setup a New Node @@ -117,7 +117,7 @@ Your node can rapidly sync with the network using state sync without replaying h To set state sync enabled, RPC servers and trusted block info (height and hash) are required. -You can use the following public RPC endpoints provided by Medibloc team. +You can use the following public RPC endpoints provided by MediBloc team. - 3.35.82.40:26657 - 13.124.96.254:26657 - 52.79.108.35:26657 @@ -206,7 +206,7 @@ Environment="DAEMON_NAME=panacead" Environment="DAEMON_ALLOW_DOWNLOAD_BINARIES=false" Environment="DAEMON_RESTART_AFTER_UPGRADE=true" ``` -For more details about those environment variables, please see the [Cosmovisor guide](cosmovisor.md). +For more details about those environment variables, please see the [Cosmovisor guide](4-cosmovisor.md). Then, setup the daemon. ```bash diff --git a/.gitbook/validators/cosmovisor.md b/.gitbook/4-validators/4-cosmovisor.md similarity index 100% rename from .gitbook/validators/cosmovisor.md rename to .gitbook/4-validators/4-cosmovisor.md diff --git a/.gitbook/oracles/overview.md b/.gitbook/4-validators/5-security/0-sentry-nodes.md similarity index 100% rename from .gitbook/oracles/overview.md rename to .gitbook/4-validators/5-security/0-sentry-nodes.md diff --git a/.gitbook/4-validators/5-security/1-validator-backup.md b/.gitbook/4-validators/5-security/1-validator-backup.md new file mode 100644 index 00000000..e69de29b diff --git a/.gitbook/validators/ledger-nano.md b/.gitbook/4-validators/5-security/2-ledger-nano.md similarity index 97% rename from .gitbook/validators/ledger-nano.md rename to .gitbook/4-validators/5-security/2-ledger-nano.md index 176de319..acacae5a 100644 --- a/.gitbook/validators/ledger-nano.md +++ b/.gitbook/4-validators/5-security/2-ledger-nano.md @@ -23,7 +23,7 @@ Note: You need to [install the `Panacea` app](#install-the-panacea-ledger-app) o ### Before you begin -Install `panacead` by following the [guide](cli-installation.md). +Install `panacead` by following the [guide](../1-cli-installation.md). ### Add your Ledger key diff --git a/.gitbook/4-validators/6-software-upgrade-guide.md b/.gitbook/4-validators/6-software-upgrade-guide.md new file mode 100644 index 00000000..e69de29b diff --git a/.gitbook/validators/faq.md b/.gitbook/4-validators/7-faq.md similarity index 99% rename from .gitbook/validators/faq.md rename to .gitbook/4-validators/7-faq.md index d2379220..fc31815e 100644 --- a/.gitbook/validators/faq.md +++ b/.gitbook/4-validators/7-faq.md @@ -261,7 +261,7 @@ There are currently two faults that can result in slashing of funds for a valida Validators should expect to provision one or more data center locations with redundant power, networking, firewalls, HSMs and servers. We expect that a modest level of hardware specifications will be needed initially and that they might rise as network use increases. -For details, please see the [Join the Network](join-mainnet-testnet.md) guide. +For details, please see the [Join the Network](3-join-mainnet-testnet.md) guide. ### What are software requirements? diff --git a/.gitbook/assets/fullnode/ec2-ami.png b/.gitbook/4-validators/images/ec2-ami.png similarity index 100% rename from .gitbook/assets/fullnode/ec2-ami.png rename to .gitbook/4-validators/images/ec2-ami.png diff --git a/.gitbook/assets/fullnode/ec2-instance-type.png b/.gitbook/4-validators/images/ec2-instance-type.png similarity index 100% rename from .gitbook/assets/fullnode/ec2-instance-type.png rename to .gitbook/4-validators/images/ec2-instance-type.png diff --git a/.gitbook/validators/interaction-with-the-network-cli.md b/.gitbook/4-validators/interaction-with-the-network-cli.md similarity index 99% rename from .gitbook/validators/interaction-with-the-network-cli.md rename to .gitbook/4-validators/interaction-with-the-network-cli.md index 033c56b9..bfec395e 100644 --- a/.gitbook/validators/interaction-with-the-network-cli.md +++ b/.gitbook/4-validators/interaction-with-the-network-cli.md @@ -257,7 +257,7 @@ panacead query slashing params ### Create your validator {% hint style="info" %} -This guide assumes that you have already set up your full node by following [the guide](join-mainnet-testnet.md). +This guide assumes that you have already set up your full node by following [the guide](3-join-mainnet-testnet.md). {% endhint %} Your `panaceavalconspub` address (public key) can be used to create a new validator by staking tokens. @@ -308,7 +308,7 @@ In other words, validators cannot be in the active set, if their total stake (= You can confirm that you are in the validator set by the following command: ```bash -panacead query staking validators +panacead query staking 4-validators ``` ### Edit validator description @@ -351,7 +351,7 @@ You can delegate `umed` to a validator. These delegators can receive part of the You can query the list of all validators of a specific chain: ```bash -panacead query staking validators +panacead query staking 4-validators ``` If you want to get the information of a single validator you can check it with: diff --git a/.gitbook/5-oracles/0-about-dep-oracle.md b/.gitbook/5-oracles/0-about-dep-oracle.md new file mode 100644 index 00000000..e69de29b diff --git a/.gitbook/5-oracles/1-operate-oracle-nodes/0-overview.md b/.gitbook/5-oracles/1-operate-oracle-nodes/0-overview.md new file mode 100644 index 00000000..e69de29b diff --git a/.gitbook/5-oracles/1-operate-oracle-nodes/1-oracle-installation.md b/.gitbook/5-oracles/1-operate-oracle-nodes/1-oracle-installation.md new file mode 100644 index 00000000..43a95946 --- /dev/null +++ b/.gitbook/5-oracles/1-operate-oracle-nodes/1-oracle-installation.md @@ -0,0 +1,43 @@ +# Installation + +## Hardware Requirement + +The oracle only works on [SGX](https://www.intel.com/content/www/us/en/developer/tools/software-guard-extensions/overview.html)-[FLC](https://github.com/intel/linux-sgx/blob/master/psw/ae/ref_le/ref_le.md) environment with a [quote provider](https://docs.edgeless.systems/ego/#/reference/attest) installed. +You can check if your hardware supports SGX and is enabled in the BIOS by following [EGo guide](https://docs.edgeless.systems/ego/#/getting-started/troubleshoot?id=hardware). + +## Installation: Use Docker + +### Pull an image +You can pull a docker image by following CLI: +```bash +docker pull ghcr.io/medibloc/panacea-oracle:latest +``` +It is highly recommended to use a specific Docker image tag instead of `latest`. +You can find the image tags from the [GitHub Packages page](https://github.com/medibloc/panacea-oracle/pkgs/container/panacea-oracle). + +### Run a container using SGX +This is a sample command to show you how to run a container using SGX in your host. +```bash +docker run \ + --device /dev/sgx_enclave \ + --device /dev/sgx_provision \ + -v ${ANY_DIR_ON_HOST}:/oracle \ + ghcr.io/medibloc/panacea-oracle:latest \ + ego run /usr/bin/oracled --help +``` +After a successful installation, go to the process of [initializing oracle](5-oracles/1-operate-oracle-nodes/2-oracle-intialization.md). + + +### How about building from source? + +You can build from source by referring to the following [installation-from-source](https://github.com/medibloc/panacea-oracle/blob/main/docs/installation-src.md). + +However, we highly recommend installing using docker. +This is because the uniqueID in `EGo` is sensitive to changes on the Go dependency or local debug environment. + +You should check the uniqueID with following CLI when you want to use the binary you built yourself. +```bash +ego sign ${enclave-json-path} # docker image use enclave in /scripts/enclave-prod.json +ego uniqueid ${oracle-binary-path} +``` + diff --git a/.gitbook/5-oracles/1-operate-oracle-nodes/2-oracle-intialization.md b/.gitbook/5-oracles/1-operate-oracle-nodes/2-oracle-intialization.md new file mode 100644 index 00000000..2fc8c956 --- /dev/null +++ b/.gitbook/5-oracles/1-operate-oracle-nodes/2-oracle-intialization.md @@ -0,0 +1,129 @@ +# Oracle Initialization + +#### Before running the oracle, you should initialize the oracle configuration. + +## Preparations + +Before initializing the oracle, you should install the oracle described +in [oracle-installation](./1-oracle-installation.md). +After installing the oracle, create an empty directory on your host, to be mounted as the `/home_mnt` directory in the +enclave. + +```bash +mkdir /oracle +``` + +```bash +export ORACLE_CMD="docker run --rm \ + --device /dev/sgx_enclave \ + --device /dev/sgx_provision \ + -v /oracle:/oracle ghcr.io/medibloc/panacea-oracle:latest \ + ego run /usr/bin/oracled" +``` + +## Command Line of Initialization + +```bash +$ORACLE_CMD init --home /home_mnt/.oracle +``` + +When running the above CLI for initializing the oracle, the `config.toml` file will be generated under +the `/.oracle` in the enclave. +The default `config.toml` file will look like below. + +```toml +# This is a TOML config file. +# For more information, see https://github.com/toml-lang/toml +# Write comment later +############################################################################### +### Base Configuration ### +############################################################################### + +log-level = "info" +oracle-mnemonic = "" +oracle-acc-num = "0" +oracle-acc-index = "0" +data-dir = "data" + +oracle-priv-key-file = "oracle_priv_key.sealed" +oracle-pub-key-file = "oracle_pub_key.json" +node-priv-key-file = "node_priv_key.sealed" + +############################################################################### +### Panacea Configuration ### +############################################################################### + +[panacea] + +chain-id = "" +grpc-addr = "http://127.0.0.1:9090" +rpc-addr = "tcp://127.0.0.1:26657" +default-gas-limit = "400000" +default-fee-amount = "2000000umed" + +# A primary RPC address for light client verification + +light-client-primary-addr = "tcp://127.0.0.1:26657" + +# Witness addresses (comma-separated) for light client verification + +light-client-witness-addrs = "tcp://127.0.0.1:26657" + +# Setting log information for light client + +light-client-log-level = "error" + +############################################################################### +### IPFS Configuration ### +############################################################################### + +[ipfs] + +ipfs-node-addr = "127.0.0.1:5001" + +############################################################################### +### API Configuration ### +############################################################################### + +[api] + +listen-addr = "127.0.0.1:8080" +write-timeout = "60" +read-timeout = "15" +``` + +## Configuring Some Default Setting + +#### Base Configuration + +In `Base Configuration`, you need to configure `oracle-mnemonic`, `oracle-acc-num`, and `oracle-acc-index`. These +components should correspond to the account that you registered in Panacea. + +#### Panacea Configuration + +In `Panacea Configuration`, you need to configure the chain ID of Panacea. If you want to join as an oracle to Panacea +mainnet or testnet, please check the chain IDs +in [mainnet-repoistory](https://github.com/medibloc/panacea-mainnet#intro) +or [testnet-repository](https://github.com/medibloc/panacea-testnet#intro), respectively. + +The default `grpc-addr` and `rpc-addr` setting is based on the localnet. So if you want to connect with Panacea +mainnet, the `grpc-addr` should be `https://grpc.gopanacea.org` and the `rpc-addr` should be `https://rpc.gopanacea.org`. +Also, the `light-client-primary-addr` and `light-client-witness-addrs` are as same as `rpc-addr`, if you want to +connect with Panacea mainnet. + +The `default-gas-limit` and `default-fee-amount` are set as `400000` and `2000000umed`, since the remote report has +large bytes for oracle registration and oracle upgrade. Once you finish an oracle registration or an upgrade, you +could set a lower gas limit and fee amount than the default setting. + +#### IPFS Configuration + +The oracle will use a public IPFS node for now. If you want to run a local IPFS node, the `ipfs-node-addr` is same as +default setting. Also, you need to check that the IPFS gateway and the oracle `listen-addr` are at the same port. You can +change the IPFS gateway in `$HOME/.ipfs/config`. If you want to know more about RPC API of the IPFS, please refer +the [IPFS documentation](https://docs.ipfs.tech/reference/kubo/rpc/). + +## Next + +If you have done the oracle initialization, you could register the oracle based on above configuration. If you want to know +how to register oracle, please refer to the [oracle-registration](./4-oracle-registration.md) documentation. + diff --git a/.gitbook/5-oracles/1-operate-oracle-nodes/3-genesis-oracle.md b/.gitbook/5-oracles/1-operate-oracle-nodes/3-genesis-oracle.md new file mode 100644 index 00000000..7e2dbc00 --- /dev/null +++ b/.gitbook/5-oracles/1-operate-oracle-nodes/3-genesis-oracle.md @@ -0,0 +1,217 @@ +# Genesis Oracle + +- Status: Draft +- Created: 2023-01-11 +- Modified: 2023-01-11 +- Authors + - Gyuguen Jang + - Youngjoon Lee + - Hansol Lee + - Myongsik Gong + - Inchul Song + - Tae Jin Yoon(tj@medibloc.org) + + +## Synopsis +This document describes how to register a genesis oracle with Panacea. + +In order for DEP to operate properly, one or more trusted oracles must be registered in Panacea. +In general, the genesis oracle will already be registered on the testnet or mainnet. +This guide is useful for testing on the localnet. + +## Genesis Oracle Registration +To register a genesis oracle, you must first complete the [oracle-initialization](./2-oracle-initialization.md) step. +Panancea needs to complete the steps before executing `panacead start` in [deploy-localnet](../../4-validators/2-deploy-localnet.md). +You must first register the genesis oracle in `genesis.json` of Panacea + +### UniqueID +UniqueID can be extracted from Oracle's binary. +Execute the command in oracle as follows: +```shell +docker run \ + --device /dev/sgx_enclave \ + --device /dev/sgx_provision \ + ghcr.io/medibloc/panacea-oracle:latest \ + ego uniqueid /usr/bin/oracled +``` +**Output** +``` +EGo v1.0.1 (e1e48c9dbfdfd3cb2f2fda7602729162c9f762cc) + +``` + +### Genesis Oracle Registration in Panacea + +After the uniqueID extraction is completed, the genesis oracle must be registered in `genesis.json` of Panacea. + +We provide a CLI for this process. +``` +panacead add-genesis-oracle \ + --oracle-unique-id + --oracle-account \ + --oracle-commission-rate \ + --oracle-commission-max-rate \ + --oracle-commission-max-change-rate \ + --oracle-endpoint {oracle_endpoint} +``` + +| Argument | Requirement | Description | +|-----------------------------------|-------------|------------------------------------------------------------------------------------------------------| +| oracle-unique-id | optional | The uniqueID to be set in the params of the oracle module and the genesis oracle | +| oracle-account | optional | The address or key name of the account to be registered as an genesis oracle | +| oracle-commission-rate | optional | The desired initial oracle commission rate | +| oracle-commission-max-rate | optional | The maximum oracle commission rate. The oracle commission rate cannot be greater than this max rate. | +| oracle-commission-max-change-rate | optional | The maximum rate that an oracle can change once. It will be reset 24 hours after the last change. | +| oracle-endpoint | optional | The endpoint of oracle to be used | + +You can check the oracle registered in `genesis.json` +``` +cat $HOME/.panacea/config/genesis.json | jq .app_state.oracle.oracles +``` +**Output** +```json +[ + { + "oracle_address": "", + "unique_id": "", + "endpoint": "", + "update_time": "", + "oracle_commission_rate": "", + "oracle_commission_max_rate": "", + "oracle_commission_max_change_rate": "" + } +] +``` + +### Start block generation in Panacea +You need to launch Panacea to start generating blocks. +```shell +panacead start +``` + +## Oracle Key Pair and Remote Report + +The genesis oracle must create an oracle private key and public key to use for data encryption/decryption. +This oracle also issues a remote report to allow others to prove that the genesis oracle is running inside secure enclave and the oracle key pair is generated inside the enclave. + +### Generates oracle key pair and remote report in oracle + +The genesis oracle needs to generate an oracle key pair and a remote report. +However, before generating the oracle keys and remote reports, the genesis oracle needs to know the trusted block information from Panacea +even though this information is not a necessary component of the oracle key pair generation or the remote report generation. +This information is not a necessary component because the two generation processes do not retrieve data from Panacea. + +When the oracle participates in the verification operation (`oracled start`), the oracle needs to use a light client as it will retrieve data from Panacea. Therefore, unless trusted block information is received during the process of generating an oracle key, the genesis oracle has no way to retrieve this block information; this is why we retrieve the trusted block information during the oracle key pair and remote report generation. + +You can get trusted block information by: +```shell +BLOCK=$(panacead q block --node ) + +HEIGHT=$(echo $BLOCK | jq -r .block.header.height) +HASH=$(echo $BLOCK | jq -r .block_id.hash) +``` + +After getting the height and hash of the block, you can generate the necessary keys and remote report via the CLI below. +``` +docker run \ + --device /dev/sgx_enclave \ + --device /dev/sgx_provision \ + -v :/oracle \ + ghcr.io/medibloc/panacea-oracle:latest \ + ego run /usr/bin/oracled gen-oracle-key \ + --trusted-block-height $HEIGHT \ + --trusted-block-hash $HASH + +``` + +| Argument | Requirement | Description | +|----------------------|-------------|-------------------------------------------------------------| +| trusted-block-height | required | Trusted block height of Panacea | +| trusted-block-hash | required | Block hash corresponding to trusted block height of Panacea | + + +When the oracle key and remote report are generated successfully, they are stored as file with the below structure: + +``` +# Oracle home +. +├── config.toml +├── data +│   └── light-client.db +│   ├── 000001.log +│   ├── CURRENT +│   ├── LOCK +│   ├── LOG +│   └── MANIFEST-000000 +├── oracle_priv_key.sealed +└── oracle_pub_key.json +``` +- `data/light-client.db`: Repository of Light client. +- `oracle_priv_key.sealed`: Oracle private key sealed file. +- `oracle_pub_key.json`: A json file containing oracle's public key and remote report. + +**oracle_pub_key.json** +```json +{ + "public_key_base64": "", + "remote_report_base64": "" +} +``` + +### Submit a parameter change proposal +The generated oracle public key and its remote report should be set by governance, a proposal for changing module parameter of oracle module. + +```shell +panacead tx gov submit-proposal param-change proposal.json \ + --from \ + --chain-id \ + --gas auto \ + --gas-adjustment 1.3 \ + --gas-prices 5umed \ + -y +``` +**proposal.json** +```json +{ + "title": "", + "description": "<description>", + "changes": [ + { + "subspace": "oracle", + "key": "OraclePublicKey", + "value": "<oracle-pub-key-base64>" + }, + { + "subspace": "oracle", + "key": "OraclePubKeyRemoteReport", + "value": "<oracle-remote-report-base64>" + } + ], + "deposit": "100000000000umed" +} +``` + +After submitting the proposal, vote on the proposal and wait for it to pass. +```shell +panacead tx gov vote {proposal_id} yes \ + --from <key> \ + --chain-id <chain_id> \ + --fees 1000000umed \ + -y +``` + +If the proposal passes, you can check the changes with the following CLI. +```shell +panacead q oracle params +``` +**Output** +```shell +params: + oracle_pub_key_remote_report: "<oracle-remote-report-base64>" + oracle_public_key: "<oracle-public-key-base64>" + unique_id: "<unique-id>" +``` + +When all these processes are completed, the genesis oracle can operate normally. + +Next, see [Running node](./5-running-node.md) where you can run the genesis oracle. diff --git a/.gitbook/5-oracles/1-operate-oracle-nodes/4-oracle-registration.md b/.gitbook/5-oracles/1-operate-oracle-nodes/4-oracle-registration.md new file mode 100644 index 00000000..0b05a151 --- /dev/null +++ b/.gitbook/5-oracles/1-operate-oracle-nodes/4-oracle-registration.md @@ -0,0 +1,112 @@ +# Oracle Registration + +This document is an instruction to register an oracle to Panacea + +## Get Trusted Block Information + +To request an oracle registration to Panacea, trusted block information (height and hash), which will be used for [light client](), is required and need to be verified by other registered oracle. + +You can get trusted block information by: +```bash +BLOCK=$(panacead q block --node <node-rpc-address>) + +HEIGHT=$(echo $BLOCK | jq -r .block.header.height) +HASH=$(echo $BLOCK | jq -r .block_id.hash) +``` + +If you need more information about public RPC endpoints provided by MediBloc team, you can refer to [this](https://github.com/medibloc/panacea-mainnet#public-endpoints) + +## Request to Register Oracle + +In addition to the trusted block information, the following arguments are also required in the oracle registration. + +| Argument | requirement | Description | +|-----------------------------------|-------------|------------------------------------------------------------------------------------------------------| +| oracle-commission-rate | required | The desired initial oracle commission rate | +| oracle-commission-max-rate | required | The maximum oracle commission rate. The oracle commission rate cannot be greater than this max rate. | +| oracle-commission-max-change-rate | required | The maximum rate that an oracle can change once. It will be reset 24 hours after the last change. | +| oracle-endpoint | optional | The endpoint of oracle to be used | + +With the above arguments, you can now request to register your oracle to Panacea. + +```bash +docker run \ + --device /dev/sgx_enclave \ + --device /dev/sgx_provision \ + -v <directory-you-want>/oracle:/oracle \ + ghcr.io/medibloc/panacea-oracle:latest \ + ego run /usr/bin/oracled register-oracle \ + --trusted-block-height ${HEIGHT} \ + --trusted-block-hash ${HASH} \ + --oracle-commission-rate 0.1 \ + --oracle-commission-max-rate 0.3 \ + --oracle-commission-max-change-rate 0.01 \ + --oracle-endpoint "<your-oracle-endpoint>" +``` + +Then, a new key pair, called `Node Key`, and its remote report will be generated. +The `Node Key` is used to transfer the oracle private key securely. +Since the oracle private key must be shared in a very secure way, the key will be encrypted with the public key of the `Node Key` so that only the oracle can decrypt it. + +{% hint style="danger" %} +The private key of `Node Key` is also stored in a secure way as a sealed file, named `node_priv_key.sealed` in default. +This `node_priv_key.sealed` file is the only clue to decrypt the encrypted oracle private key, and, hence, we highly recommend you to manage it very carefully in case you need to restore the oracle private key again later. +{% endhint %} + +If you have tried to request `register-oracle` before, previously generated `node_priv_key.sealed` would exist. +And the app will ask, + +``` +There is an existing node key. +Are you sure to delete and re-generate node key? +``` + +If you're sure to re-generate the `Node Key` and re-request oracle registration, please enter `y`. +Or, we recommend to back up the existing `node_priv_key.sealed` file. + +## Subscribe Approval of Registration + +If the transaction for requesting oracle registration succeeds, the newly registered oracle will start subscribing to `ApproveOracleRegistrationEvent`. +Other oracles that are already registered will do some verifications of this registration by checking if: +- correct version of oracle binary is used +- the oracle is running inside an enclave +- the `Node Key` is generated inside the enclave +- the trusted block information is valid + +When the registration is verified successfully, other oracles will send a transaction for approval of the oracle registration. +Since the oracle is already subscribing to the event, it will detect the approval, and then retrieve the oracle private key. +As a result of the oracle private key retrieval, a sealed file named `oracle_priv_key.sealed` (default file name) will be generated. +Using this sealed oracle private key, the oracle is now ready to perform tasks such as verifying data or other oracles. + +For more information about what oracle does, please refer the [running an oracle node](5-running-node#what-oracle-does.md). + +{% hint style="danger" %} +Like `node_priv_key.sealed`, `oracle_priv_key.sealed` is also very important for working as a valid oracle. +Thus, we highly recommend you to manage the `oracle_priv_key.sealed` file very carefully. +In case an operator loses the `oracle_priv_key.sealed` file for any reason, it can be retrieved again using `get-oracle-key` CLI with the `node_priv_key.sealed` file, which is generated when oracle registration is requested as above. +{% endhint %} + +## Manually Retrieve Oracle Private Key + +Because of any unforseen reasons, the oracle could stop before the oracle private key is retrieved. +In this case, you can also retrieve the oracle private key through `get-oracle-key` CLI. +If at least one registered oracle approves this registration, you will be able to retrieve the oracle private key successfully. + +```bash +docker run \ + --device /dev/sgx_enclave \ + --device /dev/sgx_provision \ + -v ${ANY_DIR_ON_HOST}:/oracle \ + ghcr.io/medibloc/panacea-oracle:latest \ + ego run /usr/bin/oracled get-oracle-key +``` + +You can check the status of your registration with the uniqueID and oracle address. + +```bash +panacead q oracle oracle-registration <unique-id> <oracle-address> +``` + +If at least one oracle approves this registration, the `encrypted_oracle_priv_key` will not be empty. + +Now, you are ready to run your own oracle. Please refer the [running a node](./5-running-node.md) instructions. diff --git a/.gitbook/5-oracles/1-operate-oracle-nodes/5-running-oracle-node.md b/.gitbook/5-oracles/1-operate-oracle-nodes/5-running-oracle-node.md new file mode 100644 index 00000000..5fbd3c1e --- /dev/null +++ b/.gitbook/5-oracles/1-operate-oracle-nodes/5-running-oracle-node.md @@ -0,0 +1,90 @@ +# Running an Oracle Node + +## Overview + +If you have completed previous steps, now is the time to actually run oracle. + +The oracle is responsible for validating the data provider's data and +ensuring that the data is transmitted to the data consumer securely using the `oracle key`. + +In this process, oracle operators can earn commissions according to the commission rate registered to Panacea. +The oracle also serves to validate and approve `registration/upgrade` requests from other oracles. + +You can see the details in [What oracle does](#what-oracle-does). + +## Prerequisites +- [Hardware Requirement](5-oracles/1-operate-oracle-nodes/1-oracle-installation.md) +- Complete [Oracle Registration](5-oracles/1-operate-oracle-nodes/4-oracle-registration.md) or [Genesis Oracle](5-oracles/1-operate-oracle-nodes/3-genesis-oracle.md) + - Your oracle have to be registered in Panacea + - The `oracle_priv_key.sealed` must be in the oracle home path + +## Start oracle + +You can start an oracle with the following CLI: +```bash +docker run \ + --device /dev/sgx_enclave \ + --device /dev/sgx_provision \ + -v ${ANY_DIR_ON_HOST}:/oracle \ + ghcr.io/medibloc/panacea-oracle:latest \ + ego run /usr/bin/oracled start +``` +If the oracle is successful started, you will see the following log message: +``` +EGo v1.1.0 (4625a610928f4f4b1ea49262c363376b1e574b6c) +[erthost] loading enclave ... +[erthost] entering enclave ... +[ego] starting application ... +time="2023-01-11T07:40:31Z" level=info msg="successfully connect to IPFS node" +time="2023-01-11T07:40:31Z" level=info msg="dialing to Panacea gRPC endpoint: http://127.0.0.1:9090" +time="2023-01-11T07:40:31Z" level=info msg="Panacea event subscriber is started" +time="2023-01-11T07:40:31Z" level=info msg="subscribe RegisterOracleEvent. query: message.action = 'RegisterOracle'" +time="2023-01-11T07:40:31Z" level=info msg="subscribe UpgradeOracleEvent. query: message.action = 'UpgradeOracle'" +time="2023-01-11T07:40:31Z" level=info msg="HTTP server is started: 127.0.0.1:8081" +``` + +## What oracle does + +### Validate provider data & issue certificate + +Oracle provides a REST API to validate data provided by a data provider and issue a certificate. + +The validation procedure is as follows: +1. Check the address of the data provider who is requesting data validation with JWT +2. Check the status of the related `deal` +3. Decrypt the data provider's encrypted data & check the data hash and the data schema + +If the validation passes successfully, the oracle issues a certificate as follows: +1. Generate a `secret key` by combining `oracle private key`, deal ID, and data hash +2. Re-encrypt the data using the `secret key` and put it in `IPFS` +3. Issue a certificate with `oracle private key` signature + +Data providers will be able to submit a consent to Panacea with the issued certificate. +Panacea ensures that a commission is paid to the oracle operator who issued the certificate when the data delivery is successfully completed. + +### Safely transmit the data accessibility to the data consumer + +Oracle provides a REST API to get data accessibility to the data consumer. + +After the `submit-consent` transaction succeeds in Panacea, the oracle transmits a secret key that enables data access to the data consumer. +The detailed process is as follows: +1. Check the address of the data consumer who is requesting data access with JWT +2. Check if the requesting consumer is the owner of the `deal` +3. Check if the `submit-consent` transaction is present and successful +4. Make `encrypted secret key` using `consumer public key` +5. Respond with `encrypted secret key` to the data consumer + +The data consumer can obtain the `secret key` through his/her `private key`, and can decrypt data from `IPFS`. + +### Validate and approve registration/upgrade requests of other oracles + +The oracle subscribes to `registration/upgrade` events from Panacea. + +When another oracle sends a `registration/upgrade`, the running oracle do verifications by checking if: +- a correct version of the oracle binary is used +- the oracle is running inside an enclave +- the `Node Key` is generated inside the enclave +- the trusted block information is valid +- the oracle is registered (at upgrade requests) + +When the `registration/upgrade` is verified successfully, the oracle sends a transaction for approval of the oracle `registration/upgrade`. diff --git a/.gitbook/5-oracles/1-operate-oracle-nodes/6-update-oracle-info.md b/.gitbook/5-oracles/1-operate-oracle-nodes/6-update-oracle-info.md new file mode 100644 index 00000000..99556a02 --- /dev/null +++ b/.gitbook/5-oracles/1-operate-oracle-nodes/6-update-oracle-info.md @@ -0,0 +1,34 @@ +# Update Oracle Information + +This document outlines how to edit the oracle information (endpoint and commission rate) + +## Command Line for Updating + +Using below CLI, you can update your endpoint and/or commission rate + +```bash +docker run \ + --device /dev/sgx_enclave \ + --device /dev/sgx_provision \ + -v <directory-you-want>/oracle:/oracle \ + ghcr.io/medibloc/panacea-oracle:latest \ + ego run /usr/bin/oracled update-oracle-info \ + --oracle-endpoint "<your-new-endpoint>" \ + --oracle-commission-rate <your-new-commission-rate> +``` + +| Flag | requirement | Description | +|-----------------------------------|-------------|-----------------------------| +| endpoint | optional | The endpoint of oracle | +| oracle-commission-rate | optional | The oracle commission rate. | + +As you can see from above table, both flags are optional. +You can choose and enter only the flags you want to change. +It is noted that the oracle commission rate cannot be greater than oracle max change rate. +And once changed, the oracle commission rate cannot be changed within the next 24 hours. + +You can confirm the changes you made when the transaction succeeds + +```bash +panacead q oracle oracle <your-oracle-address> +``` diff --git a/.gitbook/5-oracles/1-operate-oracle-nodes/7-oracle-upgrade.md b/.gitbook/5-oracles/1-operate-oracle-nodes/7-oracle-upgrade.md new file mode 100644 index 00000000..cbb02324 --- /dev/null +++ b/.gitbook/5-oracles/1-operate-oracle-nodes/7-oracle-upgrade.md @@ -0,0 +1,113 @@ +# Oracle Upgrade + +This document is about the entire process of oracle upgrade. + +## Oracle Upgrade Process + +All oracles registered in Panacea are forced to run the oracle with the same unique ID stored in the oracle module. +Since the new version (to be upgraded) of oracle will have a unique ID different from the existing one, a new unique ID should be registered in Panacea. +This process is determined by on-chain governance; thus, an upgrade can be proposed by an `oracle-upgrade` proposal. + +### Submit Proposal for Oracle Upgrade + +Oracle upgrade can be proposed by submitting an `oracle-upgrade` proposal as shown below: + +```bash +panacead tx gov submit-proposal oracle-upgrade \ + --title "<proposal-title>" \ + --description "<proposal-description>" \ + --upgrade-height <upgrade-target-height> \ + --upgrade-unique-id "<oracle-unique-id>" \ + --deposit "<deposit-in-umed>" \ + --from "<proposer-key-name>" \ + --chain-id "<chain-id>" \ + --fees "1000000umed" +``` + +- title: The title of oracle upgrade proposal +- description: A description of oracle upgrade proposal +- upgrade-height: A target height to be upgraded +- upgrade-unique-id: The unique ID of oracle to be upgraded +- deposit: A deposit for proposal + +If the proposal passes, you can check the oracle upgrade information with the below CLI. + +```bash +panacead q oracle oracle-upgrade-info +``` + +### Upgrade Oracle Node + +{% hint style="info" %} +You can upgrade your oracle any time after an `oracle-upgrade` proposal has passed (even before the upgrade target height is reached). +However, since the new version of oracle can be active after the target height, the current version of oracle must be running before the target height. + +You do not have to stop the old version of oracle when upgrading to a new version of oracle. +You can run different versions of oracle at the same time using the `home` flag. +{% endhint %} + +#### Initialization + +The `oracle_priv_key.sealed` used in the previous version cannot be used in the new version of oracle because it cannot be decrypted in the new version of oracle. For more info, refer to [this](../../3-protocol-devs/1-dep-specs/5-confidential-oracle.md) + +Therefore, the new version of oracle should also know the oracle private key. +The oracle can retrieve the oracle private key with a similar process to registering an oracle. + +Let's start with [initialization](2-oracle-intialization.md) of the new version of oracle. + +```bash +export ORACLE_CMD="docker run --rm \ + --device /dev/sgx_enclave \ + --device /dev/sgx_provision \ + -v <directory-you-want>/oracle:/oracle ghcr.io/medibloc/panacea-oracle:latest \ + ego run /usr/bin/oracled" + + $ORACLE_CMD init --home /home_mnt/.oracle-new +``` + +You can rename the path where you want to store the configuration file of the new version of oracle. +For this document, we will use `.oracle-new`. +After initialization, complete the configuration by referring to the [Configuring Some Default Setting](2-oracle-intialization#configuring-some-default-setting.md). + +#### Request to Upgrade Oracle + +The purpose of this request is to securely receive the oracle private key for a new version of oracle. +It is similar to sharing the oracle private key in [oracle registration](4-oracle-registration#request-to-register-oracle.md). +Prior to the request, trusted block information is also required. +You can get trusted block information with the following command: + +```bash +BLOCK=$(panacead q block --node <node-rpc-address>) + +HEIGHT=$(echo $BLOCK | jq -r .block.header.height) +HASH=$(echo $BLOCK | jq -r .block_id.hash) +``` + +Then, request an upgrade using this trusted block information. + +```bash +$ORACLE_CMD upgrade-oracle \ + --trusted-block-height ${HEIGHT} \ + --trusted-block-hash ${HASH} + --home /home_mnt/.oracle-new +``` + +Like oracle registration, a `Node Key` to be used for sharing the oracle private key will be generated and stored. +You will find that the `node_priv_key.sealed` file is stored in `<directory-you-want>/oracle/.oracle-new`. +This `node_priv_key.sealed` file is also necessary to retrieve the oracle private key, so it is highly recommended to manage it safely. + +#### Subscribe Approval of Upgrade + +If the transaction for `upgrade-oracle` succeeds, the oracle will start subscribing to the `ApproveOracleUpgradeEvent`. +Upon approval by other oracles, this new version of oracle can retrieve the oracle private key. +This process is similar to [oracle-registration](4-oracle-registration#subscribe-approval-of-registration.md), so please refer it for details. + +#### Running the Upgraded Oracle + +After reaching the target height of the upgrade, you can start the new version of oracle. + +```bash +$ORACLE_CMD start --home /home_mnt/.oracle-new +``` + +See [running-oracle](5-running-node.md) for more information. diff --git a/.gitbook/5-oracles/1-operate-oracle-nodes/8-verify-remote-report.md b/.gitbook/5-oracles/1-operate-oracle-nodes/8-verify-remote-report.md new file mode 100644 index 00000000..44df05da --- /dev/null +++ b/.gitbook/5-oracles/1-operate-oracle-nodes/8-verify-remote-report.md @@ -0,0 +1,99 @@ +# Verify Remote Report + +# Genesis Oracle + +- Status: Draft +- Created: 2023-01-12 +- Modified: 2023-01-12 +- Authors + - Gyuguen Jang <gyuguen.jang@medibloc.org> + - Youngjoon Lee <yjlee@medibloc.org> + - Hansol Lee <hansol@medibloc.org> + - Myongsik Gong <myongsik_gong@medibloc.org> + - Inchul Song <icsong@medibloc.org> + - Tae Jin Yoon <tj@medibloc.org> + + +## Synopsis + +This document describes how to validate remote reports generated by an oracle. + +## Remote Report + +Remote reports are one of the core elements of this protocol. This remote report must be submitted when the genesis oracle or a new oracle participant registers to Panacea. A remote report can verify that the genesis oracle or a new oracle participant is the correct oracle. + +The correct oracle means the oracle with a unique ID agreed upon in Panacea. +If the unique ID is different, it can be determined that one is an invalid oracle. +See [oracle-key-handshake](../../3-protocol-devs/1-dep-specs/5-confidential-oracle.md#oracle-key-handshake) documentation for details on this. + +- For the remote report generated by the genesis oracle, you can see [genesis oracle](./3-genesis-oracle.md) section. +- For the remote report generated by a new oracle registration, you can see [oracle registration](./4-oracle-registration.md) section. +- On how to verify correct oracle via remote report, you can see [confidential oracle](../../3-protocol-devs/1-dep-specs/5-confidential-oracle.md) section. + +### Validation a genesis oracle + +To verify the genesis oracle, you need the oracle public key and a remote report generated based on the oracle public key. +This information can be obtained from Panacea's oracle module parameters. + +You need to create `public_key_info.json` file through the process below. +```shell +ORACLE_PUBLIC=$(panacead q oracle params --node <node-rpc-address> -o json) +ORACLE_PUBLIC_KEY=$(panacead q oracle params --node <node-rpc-address> -o json | jq -r .params.oracle_public_key) +ORACLE_PUBLIC_REMOTE_REPORT=$(panacead q oracle params --node <node-rpc-address> -o json | jq -r .params.oracle_pub_key_remote_report) + +jq -n --arg public_key_base64 $ORACLE_PUBLIC_KEY --arg remote_report_base64 $ORACLE_PUBLIC_REMOTE_REPORT '{public_key_base64: $public_key_base64, remote_report_base64: $remote_report_base64}' > public_key_info.json +``` + +**oracle_public_key_info.json** +```json +{ + "public_key_base64": "<public-key-base64>", + "remote_report_base64": "<remote-report-base64>" +} +``` + +Move the generated json file to the oracle home path and perform remote report validation. +```shell +mv ./oracle_public_key_info.json <directory-you-want>/.oracle + +docker run \ + --device /dev/sgx_enclave \ + --device /dev/sgx_provision \ + -v <directory-you-want>:/oracle \ + ghcr.io/medibloc/panacea-oracle:main \ + ego run /usr/bin/oracled verify-report /home_mnt/.oracle/oracle_public_key_info.json +``` + +**Output** +``` +time="2023-01-12T01:45:45Z" level=info msg="remote report is verified successfully" +``` + +### Validation on a new oracle registration + +To verify a newly registered oracle, the public key of the node registered by this oracle and the remote report are required. This information can be found in oracle registration store on Panacea. + +```shell +ORACLE_REGISTRATION=$(panacead q oracle oracle-registration <unique-id> <oracle-address> --node <node-rpc-address> -o json) +NODE_PUBLIC_KEY=$(echo $ORACLE_REGISTRATION | jq -r .oracle_registration.node_pub_key) +NODE_PUBLIC_REMOTE_REPORT=$(echo $ORACLE_REGISTRATION | jq -r .oracle_registration.node_pub_key_remote_report) + +jq -n --arg public_key_base64 $NODE_PUBLIC_KEY --arg remote_report_base64 $NODE_PUBLIC_REMOTE_REPORT '{public_key_base64: $public_key_base64, remote_report_base64: $remote_report_base64}' > node_public_key_info.json +``` + +Move the generated json file to the oracle home path and perform remote report validation. +```shell +mv ./node_public_key_info.json <directory-you-want>/.oracle + +docker run \ + --device /dev/sgx_enclave \ + --device /dev/sgx_provision \ + -v <directory-you-want>:/oracle \ + ghcr.io/medibloc/panacea-oracle:main \ + ego run /usr/bin/oracled verify-report /home_mnt/.oracle/oracle_public_key_info.json +``` + +**Output** +```shell +time="2023-01-12T01:45:45Z" level=info msg="remote report is verified successfully" +``` diff --git a/.gitbook/README.md b/.gitbook/README.md index a5dd5ca8..d961e87e 100644 --- a/.gitbook/README.md +++ b/.gitbook/README.md @@ -1,8 +1,8 @@ # MediBloc Panacea Documentation -- [About Panacea](about-panacea/panacea-ecosystem.md) -- [For Users](users/overview.md) -- [For dApp Developers](dapp-devs/overview.md) -- [For Protocol Developers](protocol-devs/overview.md) -- [For Validators](validators/overview.md) -- [For Oracles](oracles/overview.md) +- [About Panacea](0-about-panacea/0-panacea-ecosystem.md) +- [For Users](1-users/0-overview.md) +- [For dApp Developers](2-dapp-devs/0-overview.md) +- [For Protocol Developers](3-protocol-devs/0-overview.md) +- [For Validators](4-validators/0-overview.md) +- [For Oracles](5-oracles/0-about-dep-oracle.md) diff --git a/.gitbook/SUMMARY.md b/.gitbook/SUMMARY.md index 0e666e7d..83335c24 100644 --- a/.gitbook/SUMMARY.md +++ b/.gitbook/SUMMARY.md @@ -2,12 +2,12 @@ ## Overview -* [Panacea Ecosystem](about-panacea/panacea-ecosystem.md) -* [Roadmap](about-panacea/roadmap.md) +* [Panacea Ecosystem](0-about-panacea/0-panacea-ecosystem.md) +* [Roadmap](0-about-panacea/1-roadmap.md) ## For Users -* [Overview](users/overview.md) +* [Overview](1-users/0-overview.md) * Basic Concepts * MED * Transactions, Gas & Fees @@ -15,9 +15,9 @@ * CLI Keyring * GUI Wallets * Data Exchange - * Concepts - * Consume data - * Provide data + * [About DEP](1-users/3-data-exchange/0-about-dep.md) + * [Consume data](1-users/3-data-exchange/1-consume-data.md) + * [Provide data](1-users/3-data-exchange/2-provide-data.md) * Staking * Governance * Overview @@ -27,36 +27,48 @@ ## For dApp Devs -* [Overview](dapp-devs/overview.md) +* [Overview](2-dapp-devs/0-overview.md) * Endpoints * Client Libraries ## For Protocol Devs -* [Overview](protocol-devs/overview.md) +* [Overview](3-protocol-devs/0-overview.md) * Data Exchange Protocol Specs + * [Overview](3-protocol-devs/1-dep-specs/0-overview.md) + * [User Flow](3-protocol-devs/1-dep-specs/1-user-flow.md) + * [Data Deal](3-protocol-devs/1-dep-specs/2-data-deal.md) + * [Data Provider Consent](3-protocol-devs/1-dep-specs/3-data-provider-consent.md) + * [Data Validation](3-protocol-devs/1-dep-specs/4-data-validation.md) + * [Confidential Oracle](3-protocol-devs/1-dep-specs/5-confidential-oracle.md) + * [Incentives](3-protocol-devs/1-dep-specs/6-incentives.md) * Modules * Dev Guides ## For Validators -* [Overview](validators/overview.md) -* [CLI Installation](validators/cli-installation.md) -* [Deploy Localnet](validators/deploy-localnet.md) -* [Join Mainnet/Testnet](validators/join-mainnet-testnet.md) -* [Cosmovisor](validators/cosmovisor.md) +* [Overview](4-validators/0-overview.md) +* [CLI Installation](4-validators/1-cli-installation.md) +* [Deploy Localnet](4-validators/2-deploy-localnet.md) +* [Join Mainnet/Testnet](4-validators/3-join-mainnet-testnet.md) +* [Cosmovisor](4-validators/4-cosmovisor.md) * Security * Sentry Nodes * Validator Backup - * [Ledger Nano](validators/ledger-nano.md) + * [Ledger Nano](4-validators/5-security/2-ledger-nano.md) * Software Upgrade Guide -* [FAQ](validators/faq.md) +* [FAQ](4-validators/7-faq.md) ## For Oracles -* [Overview](oracles/overview.md) -* Data Exchange Protocol - * Concepts - * Oracle +* [About DEP Oracle](5-oracles/0-about-dep-oracle.md) * Operate Oracle Nodes -* FAQ \ No newline at end of file + * [Overview](5-oracles/1-operate-oracle-nodes/0-overview.md) + * [Oracle Installation](5-oracles/1-operate-oracle-nodes/1-oracle-installation.md) + * [Oracle Initialization](5-oracles/1-operate-oracle-nodes/2-oracle-intialization.md) + * [Genesis Oracle](5-oracles/1-operate-oracle-nodes/3-genesis-oracle.md) + * [Oracle Registration](5-oracles/1-operate-oracle-nodes/4-oracle-registration.md) + * [Running a Node](5-oracles/1-operate-oracle-nodes/5-running-node.md) + * [Updating Oracle Information](5-oracles/1-operate-oracle-nodes/6-update-oracle-info.md) + * [Oracle Upgrade](5-oracles/1-operate-oracle-nodes/7-oracle-upgrade.md) + * [Verify a Remote Report](5-oracles/1-operate-oracle-nodes/8-verify-remote-report.md) \ No newline at end of file diff --git a/.gitbook/assets/banner.png b/.gitbook/assets/banner.png deleted file mode 100644 index a2436968..00000000 Binary files a/.gitbook/assets/banner.png and /dev/null differ diff --git a/.gitbook/assets/image.png b/.gitbook/assets/image.png deleted file mode 100644 index bcf69bf5..00000000 Binary files a/.gitbook/assets/image.png and /dev/null differ