diff --git a/.vitepress/config.mts b/.vitepress/config.mts index 25fbfc6e..9cadf5bd 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -91,7 +91,7 @@ export default defineConfig({ { text: 'Core Concept', link: '/core-concept/glossary' }, ], outline: { - level: [2, 3], + level: [2, 4], }, sidebar: getSidebar(), diff --git a/.vitepress/sidebar.ts b/.vitepress/sidebar.ts index bc73f038..6a0aa60c 100644 --- a/.vitepress/sidebar.ts +++ b/.vitepress/sidebar.ts @@ -65,7 +65,6 @@ export function getSidebar() { }, { text: 'πŸ“– Guides', - link: '/manage-data/guides', items: [ { text: 'Create and Share Access to Protected Data', @@ -76,24 +75,19 @@ export function getSidebar() { link: '/manage-data/guides/handle-schemas-dataset-types', }, { - text: 'Manage Data Monetization', - link: '/manage-data/guides/manage-data-monetization', + text: 'Monetize Protected Data', + link: '/manage-data/guides/monetize-protected-data', }, ], }, { text: 'πŸ” DataProtector', link: '/manage-data/dataProtector', - collapsed: true, items: [ { text: 'Getting Started', link: '/manage-data/dataProtector/getting-started', }, - { - text: 'Guides', - link: '/manage-data/dataProtector/guides', - }, { text: 'DataProtector Core', link: '/manage-data/dataProtector/dataProtectorCore', diff --git a/README.md b/README.md index afe0bd68..3b257617 100644 --- a/README.md +++ b/README.md @@ -97,6 +97,7 @@ Fork this repository and ensure you're working on the `main` branch: ``` 3. Start the development server: + ```bash npm run dev ``` @@ -138,14 +139,24 @@ Fork this repository and ensure you're working on the `main` branch: > - All pull requests are reviewed by our team before being merged > - Feel free to ask questions in the pull request if you need clarification -## πŸ“„ License - -This project is part of the iExec ecosystem. Please refer to the main iExec -repositories for licensing information. - ## πŸ†˜ Support - πŸ“– [Documentation](https://docs.iex.ec) - πŸ’¬ [Discord Community](https://discord.com/invite/pbt9m98wnU) - πŸ› [Issue Tracker](https://github.com/iExecBlockchainComputing/documentation/issues) + +## TODO + +- Add Arbitrum support +- On arbitrum hide : Oracle Factory ? , DataProtector Sharing ?? +- Adapt hardcoded address to feat with new contracts deployed on arbitrum +- Add link to the new explorer feature Asset_Types in the guide => + `handle-schemas-dataset-types` +- Add link to remix for deploying whitelist +- Move `manage-data/dataProtector/advanced/iApp` (Deserializer doc) in an other + way to be more visible (may in build-iApp section) +- complete `use-iapp` section +- complete `explorer` section +- complete `build-iapp` section +- complete `deep-dive`section diff --git a/package-lock.json b/package-lock.json index 4b5257ee..a5f7545b 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,10 +1,12 @@ { - "name": "documentation", + "name": "iexec-documentation", + "version": "0.0.0", "lockfileVersion": 3, "requires": true, "packages": { "": { - "name": "documentation", + "name": "iexec-documentation", + "version": "0.0.0", "dependencies": { "@iexec/dataprotector": "^2.0.0-beta.17", "@iexec/dataprotector-deserializer": "^0.1.1", diff --git a/src/index.md b/src/index.md index 9629ccef..893add4e 100644 --- a/src/index.md +++ b/src/index.md @@ -25,7 +25,7 @@ features: details: Secure your data with advanced encryption and control access while maintaining privacy using DataProtector - link: /manage-data/dataProtector/what-is-protected-data + link: /manage-data/what-is-protected-data - icon: πŸ€– title: Build iApps details: @@ -43,7 +43,7 @@ features: details: Create revenue streams from your data while maintaining full control and privacy - link: /manage-data/guides/manage-data-monetization + link: /manage-data/guides/monetize-protected-data - icon: 🧠 title: Core Concepts details: diff --git a/src/manage-data/dataProtector/dataProtectorCore/grantAccess.md b/src/manage-data/dataProtector/dataProtectorCore/grantAccess.md index 09b4a0eb..78c0c34f 100644 --- a/src/manage-data/dataProtector/dataProtectorCore/grantAccess.md +++ b/src/manage-data/dataProtector/dataProtectorCore/grantAccess.md @@ -44,7 +44,8 @@ import { type GrantAccessParams } from '@iexec/dataprotector'; **Type:** `AddressOrENS` -The ethereum address of the protected data supplied by the user. +The ethereum address of the protected data supplied by the user (returned when +you created it). **You must own this data** to grant access. ```ts twoslash import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; @@ -68,9 +69,9 @@ The address of the application you wish to authorize to process the single application or an application whitelist. To specify a whitelist, you provide the ETH address of an [iExec Whitelist Smart Contract](https://github.com/iExecBlockchainComputing/whitelist-smart-contract/tree/main). -This smart contract aggregates multiple application versions. This allows you to -introduce new versions of your application without needing to grant access for -the `protectedData` each time you do so. +This smart contract should aggregates multiple application versions. This allows +you to introduce new versions of your application without needing to grant +access for the `protectedData` each time you do so. ```ts twoslash import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; @@ -180,12 +181,14 @@ used. It is not technically possible to set an unlimited number of accesses, but you can set `numberOfAccess` to `10000` for example. -::: info Important Notes: If you attempt to process the protected data more -times than specified in `numberOfAccess`, you will encounter a **"no dataset -orders"** error. +::: info + +If you attempt to process the protected data more times than specified in +`numberOfAccess`, you will encounter a **"no dataset orders"** error. To prevent this error, ensure the `numberOfAccess` is properly set when calling -the `grantAccess` method. +the `grantAccess` method. + ::: ```ts twoslash diff --git a/src/manage-data/dataProtector/getting-started.md b/src/manage-data/dataProtector/getting-started.md index bb0045fb..b387c9ab 100644 --- a/src/manage-data/dataProtector/getting-started.md +++ b/src/manage-data/dataProtector/getting-started.md @@ -1,10 +1,241 @@ --- title: Getting Started -description: DataProtector getting started guide +description: DataProtector getting started --- # Getting Started -This page is under development. +[![GitHub package.json version (branch)](https://img.shields.io/badge/npm-2.0.0--beta-green)](https://www.npmjs.com/package/@iexec/dataprotector) - +## Overview + +### Prerequisites + +Before getting started, ensure that you have the following installed on your +system: + +\- [**Node.js**](https://nodejs.org/en/) version 18 or higher + +\- [**NPM**](https://docs.npmjs.com/) (Node.js package manager) + +### Installation + +::: code-group + +```sh [npm] +npm install @iexec/dataprotector +``` + +```sh [yarn] +yarn add @iexec/dataprotector +``` + +```sh [pnpm] +pnpm add @iexec/dataprotector +``` + +```sh [bun] +bun add @iexec/dataprotector +``` + +::: + +**This package is an ESM package. Your project needs to use ESM too.** + [**Read more**](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) + +If you use it with **Webpack**, some polyfills will be needed. You can find a +minimal working project +[here](https://github.com/iExecBlockchainComputing/dataprotector-sdk/tree/115b797cf62dcff0f41e2ba783405d5083d78922/packages/demo/browser-webpack). + +### Instantiate SDK + +Depending on your project's requirements, you can instantiate the SDK using the +umbrella module for full functionality or opt for one of the submodules to +access specific sets of features. + +#### Instantiate using the umbrella module + +For projects requiring the full functionality of the SDK, including both core +and sharing functions. + +::: code-group + +```ts twoslash [Browser] +declare global { + interface Window { + ethereum: any; + } +} +// ---cut--- +import { IExecDataProtector } from '@iexec/dataprotector'; + +const web3Provider = window.ethereum; +// Instantiate using the umbrella module for full functionality +const dataProtector = new IExecDataProtector(web3Provider); + +const dataProtectorCore = dataProtector.core; +const dataProtectorSharing = dataProtector.sharing; +``` + +```ts twoslash [NodeJS] +import { IExecDataProtector, getWeb3Provider } from '@iexec/dataprotector'; + +// Get Web3 provider from a private key +const web3Provider = getWeb3Provider('YOUR_PRIVATE_KEY'); + +// Instantiate using the umbrella module for full functionality +const dataProtector = new IExecDataProtector(web3Provider); + +const dataProtectorCore = dataProtector.core; // access to core methods +const dataProtectorSharing = dataProtector.sharing; // access to methods +``` + +::: + +#### Instantiate only the `core` module + +For projects focusing solely on core data protection functions. + +::: code-group + +```ts twoslash [Browser] +declare global { + interface Window { + ethereum: any; + } +} +// ---cut--- +import { IExecDataProtectorCore } from '@iexec/dataprotector'; + +const web3Provider = window.ethereum; +// Instantiate only the Core module +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); +``` + +```ts twoslash [NodeJS] +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +// Get Web3 provider from a private key +const web3Provider = getWeb3Provider('YOUR_PRIVATE_KEY'); + +// Instantiate only the Core module +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); +``` + +::: + +#### Instantiate only the `sharing` module + +For projects that need access management functions specifically. + +::: code-group + +```ts twoslash [Browser] +declare global { + interface Window { + ethereum: any; + } +} +// ---cut--- +import { IExecDataProtectorSharing } from '@iexec/dataprotector'; + +const web3Provider = window.ethereum; +// Instantiate only the Sharing module +const dataProtectorSharing = new IExecDataProtectorSharing(web3Provider); +``` + +```ts twoslash [NodeJS] +import { + IExecDataProtectorSharing, + getWeb3Provider, +} from '@iexec/dataprotector'; + +// Get Web3 provider from a private key +const web3Provider = getWeb3Provider('YOUR_PRIVATE_KEY'); + +// Instantiate only the Sharing module +const dataProtectorSharing = new IExecDataProtectorSharing(web3Provider); +``` + +::: + +#### Instantiate without a Web3 provider + +For projects that only require read functions, you can instantiate the SDK +without a Web3 provider. + +::: code-group + +```ts twoslash [Singleton Modules] +import { + IExecDataProtectorSharing, + IExecDataProtectorCore, +} from '@iexec/dataprotector'; + +// Instantiate only the Core module for read-only core methods +const dataProtectorCore = new IExecDataProtectorCore(); +// Instantiate only the Sharing module for read-only sharing methods +const dataProtectorSharing = new IExecDataProtectorSharing(); +``` + +```ts twoslash [Umbrella Module] +import { IExecDataProtector } from '@iexec/dataprotector'; + +// Instantiate using the umbrella module for read-only functions +const dataProtector = new IExecDataProtector(); + +// Access to read-only core methods +const dataProtectorCore = dataProtector.core; +// Access to read-only sharing methods +const dataProtectorSharing = dataProtector.sharing; +``` + +::: + +#### Advanced configuration + +To add optional parameters, see +[advanced configuration](./advanced/advanced-configuration.md). + +::: info + +πŸ§ͺ While protected data are processed in **TEE** by **intel SGX** technology by +default, `@iexec/dataprotector` can be configured to create and process +protected data in the experimental **intel TDX** environment. + +For more details see: + +- [configure DataProtector TDX](./advanced/advanced-configuration.md#iexecoptions) +- [create TDX protected data](./dataProtectorCore/protectData.md#usage) +- [process TDX protected data](./dataProtectorCore/processProtectedData.md#workerpool) + +⚠️ Keep in mind: TDX mode is experimental and can be subject to instabilities or +discontinuity. + +::: + +## Sandbox + +### Core methods + + + ⚑  Code Sandbox + + +Corresponding GitHub repository: + + + πŸ”Ž  GitHub repository sandbox + + +### Sharing methods + + + ⚑  Code Sandbox + + +Corresponding GitHub repository: + + + πŸ”Ž  GitHub repository sandbox + diff --git a/src/manage-data/dataProtector/guides.md b/src/manage-data/dataProtector/guides.md deleted file mode 100644 index 8d68ac6d..00000000 --- a/src/manage-data/dataProtector/guides.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -description: DataProtector Guides ---- - -# DataProtector Guides - -## Structure proposΓ©e - -- Create and Share Access to Protected Data -- Schemas, Dataset Types, etc. (links to iApps) -- Manage Monetization - -## Contenu Γ  dΓ©velopper - -Cette section sera dΓ©veloppΓ©e avec des guides pratiques pour utiliser -DataProtector. diff --git a/src/manage-data/dataProtector/types.md b/src/manage-data/dataProtector/types.md index 9940edd0..96881529 100644 --- a/src/manage-data/dataProtector/types.md +++ b/src/manage-data/dataProtector/types.md @@ -2,129 +2,97 @@ Types in DataProtector. -## GrantedAccess +## πŸ”‘ GrantedAccess -### dataset +### dataset: `string` -`string` +- Address of the `protectedData` containing user data -Address of the `protectedData` containing user data +### datasetprice: `string` -### datasetprice +- Price (iun nRLC) to charge the user specified in `requesterrestrict` for each + use of this `protectedData` -`string` +### volume: `string` -Price (iun nRLC) to charge the user specified in `requesterrestrict` for each -use of this `protectedData` +- Number of authorized uses of this `protectedData`; each use decrements this + counter -### volume +### tag: `string` -`string` +- Defines whether a `protectedData` is usable in a TEE environment; `0x00` is + TEE while `0x03` is non-TEE -Number of authorized uses of this `protectedData`; each use decrements this -counter +### apprestrict: `string` -### tag +- Address of the authorized application; a value of 0x0 indicates any + application may access this data -`string` +### requesterrestrict: `string` -Defines whether a `protectedData` is usable in a TEE environment; `0x00` is TEE -while `0x03` is non-TEE +- Address of the requester authorized to use this `protectedData` in workloads; + a value of 0x0 indicates any requester may use this data -### apprestrict +### workerpoolrestrict: `string` -`string` +- Address of the decentralized infrastructure (worker pool) authorized to + execute the application; a value of 0x0 indicates any worker pool may access + this data -Address of the authorized application; a value of 0x0 indicates any application -may access this data +### salt: `string` -### requesterrestrict +- Random value to make an order unique and reusable as nonce in a blockchain + transaction -`string` +### sign: `string` -Address of the requester authorized to use this `protectedData` in workloads; a -value of 0x0 indicates any requester may use this data +- Order signature of all the `grantedAccess` fields -### workerpoolrestrict +## πŸ” ProtectedData -`string` +### name: `string` -Address of the decentralized infrastructure (worker pool) authorized to execute -the application; a value of 0x0 indicates any worker pool may access this data +- Name specified when the protected data was created. This piece of information + is public and visible on-chain. -### salt +### address: `Address` -`string` +- Ethereum address of the protected data. -Random value to make an order unique and reusable as nonce in a blockchain -transaction +### owner: `Address` -### sign +- Ethereum address of the protected data owner. -`string` +### schema: `DataSchema` -Order signature of all the `grantedAccess` fields +- Data schema for the protected data as defined when the protected data was + created (see [protectedData](./dataProtectorCore/protectData.md)). `schema` + provides a structured representation of the protected data format and + attributes. This field plays a crucial role in understanding and interpreting + the underlying structure of the sensitive information. -## ProtectedData +### creationTimestamp: `number` -### name +- Timestamp specifying when the protected data was created, expressed in + milliseconds since the epoch. This timestamp provides precise information + about the moment of creation and can be used for chronological ordering or + time-based operations. -`string` +### multiaddr: `string` | `undefined` -Name specified when the protected data was created. This piece of information is -public and visible on-chain. +- The multiaddr field is the IPFS path of your encrypted data. -### address +## ❌ RevokedAccess -`Address` +### access: [`GrantedAccess`](#πŸ”‘-grantedaccess) -Ethereum address of the protected data. +- The granted access that was revoked. -### owner +### txHash: `string` -`Address` - -Ethereum address of the protected data owner. - -### schema - -`DataSchema` - -Data schema for the protected data as defined when the protected data was -created (see [protectedData](./dataProtectorCore/protectData.md)). `schema` -provides a structured representation of the protected data format and -attributes. This field plays a crucial role in understanding and interpreting -the underlying structure of the sensitive information. - -### creationTimestamp - -`number` - -Timestamp specifying when the protected data was created, expressed in -milliseconds since the epoch. This timestamp provides precise information about -the moment of creation and can be used for chronological ordering or time-based -operations. - -### multiaddr - -`string` | `undefined` - -The multiaddr field is the IPFS path of your encrypted data. - -## RevokedAccess - -### access - -[`GrantedAccess`](./types.md#grantedaccess) - -The granted access that was revoked. - -### txHash - -`string` - -The ID of the transaction that happened on iExec's side chain. You may view -details on the transaction using the [iExec explorer](https://explorer.iex.ec). +- The ID of the transaction that happened on iExec's side chain. You may view + details on the transaction using the + [iExec explorer](https://explorer.iex.ec). _Hash example:_ `0xc9c2d58fc01fe54149b7daf49a0026d4ab1fdd3d10fb7c76350790fff03fe24d` @@ -133,14 +101,13 @@ _Hash example:_ `0xc9c2d58fc01fe54149b7daf49a0026d4ab1fdd3d10fb7c76350790fff03fe You can read more about he iExec Explorer [here](https://protocol.docs.iex.ec/for-developers/toolbox/iexec-explorer). -## SuccessWithTransactionHash - -### txHash +## βœ… SuccessWithTransactionHash -`string` +### txHash: `string` -The hash of the transaction that happened on iExec's side chain. You may view -details on the transaction using the [iExec explorer](https://explorer.iex.ec). +- The hash of the transaction that happened on iExec's side chain. You may view + details on the transaction using the + [iExec explorer](https://explorer.iex.ec). _Hash example:_ `0xc9c2d58fc01fe54149b7daf49a0026d4ab1fdd3d10fb7c76350790fff03fe24d` diff --git a/src/manage-data/guides.md b/src/manage-data/guides.md deleted file mode 100644 index 91501aff..00000000 --- a/src/manage-data/guides.md +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: DataProtector Guides -description: Step-by-step guides for using iExec DataProtector ---- - -# πŸ“– DataProtector Guides - -Discover how to protect, share, and monetize your data using iExec's -DataProtector technology through these comprehensive guides. - -## Getting Started Guides - -### πŸš€ [Quick Start Guide](/manage-data/dataProtector/getting-started) - -Learn the basics of protecting your first dataset and granting access to others. - -### πŸ” [Understanding Protected Data](/manage-data/dataProtector/what-is-protected-data) - -Deep dive into the concepts behind data protection and privacy-preserving -computation. - -## Core Features Guides - -### πŸ“Š Data Protection - -- [Protect Your Data](/manage-data/dataProtector/dataProtectorCore/protectData) - - Encrypt and register data -- [Retrieve Protected Data](/manage-data/dataProtector/dataProtectorCore/getProtectedData) - - Access your protected datasets -- [Transfer Ownership](/manage-data/dataProtector/dataProtectorCore/transferOwnership) - - Change data ownership - -### πŸ”‘ Access Management - -- [Grant Access](/manage-data/dataProtector/dataProtectorCore/grantAccess) - - Give permissions to users -- [View Granted Access](/manage-data/dataProtector/dataProtectorCore/getGrantedAccess) - - See who has access -- [Revoke Access](/manage-data/dataProtector/dataProtectorCore/revokeAllAccess) - - Remove permissions - -### ⚑ Data Processing - -- [Process Protected Data](/manage-data/dataProtector/dataProtectorCore/processProtectedData) - - Run computations -- [Get Results](/manage-data/dataProtector/dataProtectorCore/getResultFromCompletedTask) - - Retrieve computation outputs - -## Data Sharing & Monetization - -### πŸ“¦ Collections - -- [Create Collections](/manage-data/dataProtector/dataProtectorSharing/collection/createCollection) - - Group related datasets -- [Manage Collections](/manage-data/dataProtector/dataProtectorSharing/collection/addToCollection) - - Add/remove data - -### πŸ’° Monetization Options - -- [Rent Your Data](/manage-data/dataProtector/dataProtectorSharing/renting) - - Time-based access -- [Sell Your Data](/manage-data/dataProtector/dataProtectorSharing/selling) - - Permanent transfers -- [Subscription Model](/manage-data/dataProtector/dataProtectorSharing/subscription) - - Recurring access - -## Advanced Topics - -### πŸ”§ [Advanced Configuration](/manage-data/dataProtector/advanced/advanced-configuration) - -Customize DataProtector for your specific needs. - -### πŸ—οΈ [Smart Contracts](/manage-data/dataProtector/advanced/dps-smart-contract) - -Understand the underlying blockchain technology. - -### πŸ“± [App Whitelisting](/manage-data/dataProtector/advanced/apps-whitelist) - -Control which applications can access your data. - -## Migration Guide - -### πŸ”„ [Migrate from v1 to v2](/manage-data/dataProtector/migrate-from-v1) - -Upgrade from the previous version of DataProtector. - ---- - -_These guides will help you master data protection and unlock the full potential -of your datasets._ diff --git a/src/manage-data/guides/create-and-share-access.md b/src/manage-data/guides/create-and-share-access.md index 92e8749c..b91de133 100644 --- a/src/manage-data/guides/create-and-share-access.md +++ b/src/manage-data/guides/create-and-share-access.md @@ -1,10 +1,230 @@ --- title: Create and Share Access to Protected Data -description: Create and share access to protected data +description: + Learn how to protect data and grant secure access for specific apps and users --- -# Create and Share Access to Protected Data +# πŸ›‘οΈ Create and Share Access to Protected Data -This page is under development. +**Want to keep your data private while still using it in confidential +applications?** - +DataProtector lets you encrypt data and control access through orders - +specifying who can use it, how many times, and at what price. Protected data is +only accessible in secure enclaves (TEEs) by authorized users and iApps. + +## Installation + +First, install DataProtector in your project: + +::: code-group + +```bash [npm] +npm install @iexec/dataprotector +``` + +```bash [yarn] +yarn add @iexec/dataprotector +``` + +```bash [pnpm] +pnpm add @iexec/dataprotector +``` + +```bash [bun] +bun add @iexec/dataprotector +``` + +::: + +## Protect Your Data + +**Here's what happens:** Your data gets encrypted client-side and stored as an +NFT. Only you control who can decrypt and use it. + +```ts twoslash +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); +// ---cut--- +const protectedData = await dataProtectorCore.protectData({ + name: 'My Email Contact', + data: { + email: 'alice@example.com', + firstName: 'Alice', + lastName: 'Smith', + }, +}); + +console.log('Protected data address:', protectedData.address); +``` + +### What You Can Protect + +**Data**: Any kind of data you want to keep private and make available for +computations by authorized users and iApps. + +**Supported types**: Common data types like text, numbers, true/false values, +and files. See the [full list here](/manage-data/dataProtector/types). + +**Storage**: Store your data on IPFS or Arweave. For larger files, you can use +your own IPFS node. + +::: tip + +Need Help ? Check our +[Schema and Dataset Types guide](/manage-data/guides/handle-schemas-dataset-types) +for detailed formatting instructions. + +::: + +### Debug Mode Option + +Debug mode lets you test with debug iApps during development. As "debug" iApps +don't have the same security standards, we recommend using this mode only during +iApp development. + +```ts twoslash +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); +// ---cut--- + +const protectedData = await dataProtectorCore.protectData({ + data: { + email: 'test@example.com', + }, + allowDebug: true, // [!code focus] +}); +``` + +## Grant Access + +By default, your protected data is private. To let others use it, you need to +grant access to both: + +- An authorized user (who can trigger the processing) +- An authorized iApp (the application that will process the data in the private + environment) + +This ensures that only specific users can use specific applications to process +your data. Here's how to set it up: + +```ts twoslash +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); +// ---cut--- + +const grantedAccess = await dataProtectorCore.grantAccess({ + protectedData: '0x123abc...', // Your protected data address + authorizedApp: '0x456def...', // iApp that can process the data + authorizedUser: '0x789cba...', // User who can trigger the processing + pricePerAccess: 0, // Cost per use (in nRLC) + numberOfAccess: 10, // Maximum number of uses +}); +``` + +### Parameters + +```ts twoslash +import { type GrantAccessParams } from '@iexec/dataprotector'; +``` + +#### protectedData + +**Type:** `AddressOrENS` + +The ethereum address of the protected data supplied by the user (returned when +you created it). **You must own this data** to grant access. + +#### authorizedApp + +**Type:** `AddressOrENS` + +**What it is**: The iApp address that's allowed to process your data inside the +secure enclave. + +**Why needed**: This ensures only specific, audited applications can access your +data. No random code can touch it. + +**Pro tip**: Use app whitelists for production. Instead of a single app address, +you can specify a whitelist contract that contains multiple app versions. Very +useful for when you need to upgrade your iApps, without losing all the granted +access. + +```ts +// Single app +authorizedApp: 'web3mail.apps.iexec.eth'; + +// Or use a whitelist (recommended for production) +authorizedApp: '0x781482C39CcE25546583EaC4957Fb7Bf04C277D2'; // Web3Mail whitelist +``` + +#### authorizedUser + +**Type:** `AddressOrENS` + +**What it is**: The wallet address of the user that is allowed to process this +data. + +**Why needed**: Even with an authorized app, only specific users can trigger the +computation. This gives you granular control over who uses your data. + +**Don't forget**: Even if you are the owner of the data, you need to authorize +yourself! + +**Special case**: Set to `0x0000000000000000000000000000000000000000` to allow +**any user** to trigger processing (useful for public datasets). + +#### pricePerAccess + +**Type:** `number` +**Default:** `0` + +**Quick explanation**: How much you charge per data usage (in nano RLC - nRLC). + +Set to `0` for free access, or specify a price to monetize your data +automatically. + +**Example**: `pricePerAccess: 1_000_000_000` = 1 RLC per access + +β†’ **Want to learn more monetization capabilities?** See our detailed +[Monetize Protected Data guide](/manage-data/guides/monetize-protected-data) + +#### numberOfAccess + +**Quick explanation**: Maximum number of times this authorization can be used. + +::: warning + +Important If someone tries to process your data more times than allowed, they'll +get a "no dataset orders" error. Set this high enough for your use case. + +::: + +**Example values**: + +- `1` - Single use (great for one-time data analysis) +- `100` - Limited campaign (email marketing with usage cap) +- `10000` - Effectively unlimited for most use cases + +## What's Next? + +**You now have protected data with controlled access.** Here are your next +steps: + +- **Process the data**: Use + [processProtectedData](/manage-data/dataProtector/dataProtectorCore/processProtectedData) + to run computations +- **Manage access**: + [Revoke](/manage-data/dataProtector/dataProtectorCore/revokeOneAccess) or + [modify permissions](/manage-data/dataProtector/dataProtectorCore/grantAccess) + anytime +- **Learn data types**: Deep dive into + [schemas and dataset types](/manage-data/guides/handle-schemas-dataset-types) +- **Monetize data**: Explore + [data monetization strategies](/manage-data/guides/monetize-protected-data) diff --git a/src/manage-data/guides/handle-schemas-dataset-types.md b/src/manage-data/guides/handle-schemas-dataset-types.md index 1b221530..17d865cb 100644 --- a/src/manage-data/guides/handle-schemas-dataset-types.md +++ b/src/manage-data/guides/handle-schemas-dataset-types.md @@ -1,10 +1,271 @@ --- title: Handle Schemas and Dataset Types -description: Handle schemas and dataset types +description: + Learn how schemas work in DataProtector and how to use them in your iApps --- -# Handle Schemas and Dataset Types +# 🏷️ Handle Schemas and Dataset Types -This page is under development. +**Schemas are like content labels that describe what's inside your protected +data.** - +They define the structure and types of your data automatically when you protect +it, making it easy for iApps to know what they're working with. + +Think of schemas as **data fingerprints** - they tell iApps "this protected data +contains an email address and a phone number" without revealing the actual +values. + +## How Schemas Work + +When you protect data with DataProtector, the SDK automatically analyzes your +JSON object and generates a schema. **No manual schema definition needed** - +it's all handled for you. + +```ts twoslash +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); +// ---cut--- +const protectedData = await dataProtectorCore.protectData({ + name: 'User Contact', + data: { + email: 'alice@example.com', + phoneNumber: '+1234567890', + preferences: { + newsletter: true, + notifications: false, + }, + }, +}); + +console.log('βœ… Protected data created!'); +console.log('πŸ“ Address:', protectedData.address); +``` + +**🏷️ Generated Schema:** + +```json +{ + "email": "string", + "phoneNumber": "string", + "preferences": { + "newsletter": "bool", + "notifications": "bool" + } +} +``` + +::: info Schema Structure + +The schema automatically maps your data structure to types that iApps can +understand and validate. + +::: + +## Supported Data Types + +The schema automatically detects these types: + +| Type | Description | Example | +| ------------------------------- | -------------- | --------------------- | +| `string` | Text data | `"alice@example.com"` | +| `bool` | Boolean values | `true`, `false` | +| `f64` | Numbers | `42`, `3.14` | +| `i128` | Big integers | `BigInt(123456789)` | +| `application/octet-stream` | Binary data | File contents | +| `image/jpeg`, `image/png`, etc. | Media files | Images, videos | + +::: tip Auto-Detection + +The SDK automatically detects file types based on content. No need to specify +MIME types manually. + +::: + +## Why Schemas Matter + +- **Clarity**: Makes your data easier to understand and reuse +- **Safety**: Ensures iExec apps don’t process the wrong data +- **Structure**: Facilitates structured communication between **front-end and + iApp logic** + +### 🎯 **For iApp Development** + +Schemas let your iApps validate and process data safely: + +```ts twoslash +import { IExecDataProtectorDeserializer } from '@iexec/dataprotector-deserializer'; + +const deserializer = new IExecDataProtectorDeserializer(); +// ---cut--- +// Inside your iApp +const email = await deserializer.getValue('email', 'string'); +const preferences = await deserializer.getValue( + 'preferences.newsletter', + 'bool' +); +``` + +### πŸ›‘οΈ **For Type Safety** + +Prevents your iApps from processing incompatible data types. + +### πŸ” **For Data Discovery** + +Users can find relevant protected data without seeing the actual content: + +```ts twoslash +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); +// ---cut--- +const listProtectedData = await dataProtectorCore.getProtectedData({ + requiredSchema: { + email: 'string', + }, +}); +``` + +## Real Examples + +### Simple User Profile + +```ts twoslash +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); +// ---cut--- +const userData = await dataProtectorCore.protectData({ + data: { + email: 'user@example.com', + age: 25, + isSubscribed: true, + }, +}); +``` + +**🏷️ Generated Schema:** + +```json +{ + "email": "string", + "age": "f64", + "isSubscribed": "bool" +} +``` + +### Nested Contact Information + +```ts twoslash +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); +// ---cut--- +const contactData = await dataProtectorCore.protectData({ + data: { + personal: { + firstName: 'Alice', + lastName: 'Smith', + }, + contact: { + email: 'alice@example.com', + phone: '+1234567890', + }, + preferences: { + marketing: false, + notifications: true, + }, + }, +}); +``` + +**🏷️ Generated Schema:** + +```json +{ + "personal": { + "firstName": "string", + "lastName": "string" + }, + "contact": { + "email": "string", + "phone": "string" + }, + "preferences": { + "marketing": "bool", + "notifications": "bool" + } +} +``` + +### File Data + +```ts twoslash +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +// Mock function for the example +function createArrayBufferFromFile(file: File): Promise { + return Promise.resolve(new ArrayBuffer(0)); +} + +// Get file from input element +const file = new File([''], 'example.jpg', { type: 'image/jpeg' }); + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); +// ---cut--- +const fileBuffer = await createArrayBufferFromFile(file); + +const fileData = await dataProtectorCore.protectData({ + data: { + fileName: file.name, + fileContent: fileBuffer, + uploadDate: Date.now(), + }, +}); +``` + +**🏷️ Schema for file upload:** + +```json +{ + "fileName": "string", + "fileContent": "image/jpeg", + "uploadDate": "f64" +} +``` + +## Using Schemas in iApps + +Once you have protected data with a schema, you'll want to process it inside an +iApp. + +::: warning Type Matching + +**Your iApp and frontend must use the same field names and types.** If they +don't match, you'll get runtime errors when processing the data. + +::: + +β†’ **Ready to build an iApp?** Check out our detailed +[Inputs and Outputs guide](/build-iapp/guides/inputs-and-outputs) to learn how +to access schema fields inside your iApp using the deserializer. + +## Next Steps + +**You now understand how schemas work with protected data.** Here's what to +explore next: + +- **Build an iApp**: Check out the + [iApp Generator guide](/build-iapp/iapp-generator) to create your first data + processor +- **Process data**: Learn about + [processProtectedData](/manage-data/dataProtector/dataProtectorCore/processProtectedData) + for running computations +- **See it in action**: Try our [Hello World tutorial](/overview/helloWorld) for + a complete example diff --git a/src/manage-data/guides/manage-data-monetization.md b/src/manage-data/guides/manage-data-monetization.md deleted file mode 100644 index 4f1c74f8..00000000 --- a/src/manage-data/guides/manage-data-monetization.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Manage Data Monetization -description: Manage data monetization ---- - -# Manage Data Monetization - -This page is under development. - - diff --git a/src/manage-data/guides/monetize-protected-data.md b/src/manage-data/guides/monetize-protected-data.md new file mode 100644 index 00000000..90ca0e08 --- /dev/null +++ b/src/manage-data/guides/monetize-protected-data.md @@ -0,0 +1,256 @@ +--- +title: Monetize Protected Data +description: + Explore different ways to monetize your protected data with signed orders + (usage-based) and time-based access (time-period payments) +--- + +# πŸ’° Monetize Protected Data + +**Your protected data can generate revenue automatically.** + +iExec offers two fundamental approaches for monetizing your data: + +- **DataProtector Core**: **Signed orders** with pay-per-use counting - specify + exact conditions, users pay for each individual data processing +- **DataProtector Sharing**: **Time-based access** with period payments - users + pay for unlimited access during specific time periods + +## πŸ“ Signed Orders (DataProtector Core) + +**How it works**: You create and publish signed orders that specify the exact +conditions for accessing your protected data. Each order defines: + +- **Authorized App**: Which iApp can process your data +- **Authorized User**: Who can access your data (specific address or any user) +- **Price per Access**: Cost for each individual use +- **Number of Access**: Maximum times the data can be used +- **Usage Counting**: Each data processing decrements the available access count + +```ts twoslash +import { IExecDataProtectorCore, getWeb3Provider } from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorCore = new IExecDataProtectorCore(web3Provider); +// ---cut--- +// Create a signed order with specific conditions +const grantedAccess = await dataProtectorCore.grantAccess({ + protectedData: '0x123abc...', // Your data address + authorizedApp: 'email-processor.apps.iexec.eth', // Specific iApp only + authorizedUser: '0x456def...', // Specific user only + pricePerAccess: 5000000000, // 5 RLC per individual use + numberOfAccess: 100, // Maximum 100 total uses +}); + +console.log('Signed order created:', grantedAccess); +``` + +**Perfect for**: + +- Direct partnerships with known clients +- Precise control over access conditions +- Simple setup with specific partners +- Exact counting of data usage + +## πŸ“… Time-Based Access Implementation (DataProtector Sharing) + +**How it works**: Instead of counting individual uses, DataProtector Sharing +provides **time-based access periods**. Users purchase access for specific +durations (hours, days, months) and can use your protected data unlimited times +during that period. Smart contracts handle all distribution automatically. + +**Key Innovation**: Shift from usage counting to time-based access - users buy +access time, not individual transactions. + +**Access Models Available**: + +- **Rental**: Pay once to access to individual protected data (not all the + collection) +- **Subscription**: Recurring payments for ongoing access +- **Sale**: Permanent ownership transfer + +::: tip See It Live + +The [Content Creator demo](/overview/use-case-demo/content-creator) shows +DataProtector Sharing in action with file monetization. While it uses the +content-delivery iApp for file streaming, the same patterns work for any iApp - +AI models, data processing, oracles, etc. + +::: + +### **Step 1: Create a Collection** + +```ts twoslash +import { + IExecDataProtectorSharing, + getWeb3Provider, +} from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorSharing = new IExecDataProtectorSharing(web3Provider); +// ---cut--- +// Create a collection to group your data and provide +// a set of protectedData available for the subscription. +const collection = await dataProtectorSharing.createCollection(); +console.log('Collection address:', collection.collectionId); + +// Add your protected data to the collection +await dataProtectorSharing.addToCollection({ + protectedData: '0x123abc...', // Your protected data address + collectionId: collection.collectionId, + addOnlyAppWhitelist: '0x256bcd881c33bdf9df952f2a0148f27d439f2e64', // iExec apps whitelist +}); +``` + +### **Step 2: Choose Your Distribution Model** + +**DataProtector Sharing offers three distribution models:** + +#### **Time-Based Rental Model** + +Users pay once for **unlimited access during a specific time period** (not per +use). For a specific protectedData of the created collection : + +```ts twoslash +import { + IExecDataProtectorSharing, + getWeb3Provider, +} from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorSharing = new IExecDataProtectorSharing(web3Provider); +// ---cut--- +// DATA OWNER: Set up time-based rental terms +await dataProtectorSharing.setProtectedDataToRenting({ + protectedData: '0x123abc...', + price: 5000000000, // 5 RLC for the entire period + duration: 604800, // 7 days of unlimited access +}); + +// CLIENT/SUBSCRIBER: Rent access for the full time period +const rental = await dataProtectorSharing.rentProtectedData({ + protectedData: '0x123abc...', + price: 5000000000, // One payment for full period + duration: 604800, // Unlimited use for 7 days +}); +``` + +**Perfect for**: + +- Time-sensitive datasets (event data, seasonal trends) +- Expensive datasets where users need intensive short-term access +- Content that loses value over time +- Users who need to run multiple analyses during a period + +#### **Time-Based Subscription Model** + +Users pay for **recurring time-based access** to a bundle of data. Unlimited +usage during each subscription period. + +```ts twoslash +import { + IExecDataProtectorSharing, + getWeb3Provider, +} from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorSharing = new IExecDataProtectorSharing(web3Provider); + +// Mock collection for the example +const collection = { collectionId: 123 }; +// ---cut--- +// DATA OWNER: Set time-based subscription parameters +await dataProtectorSharing.setSubscriptionParams({ + collectionId: collection.collectionId, + price: 20000000000, // 20 RLC per 30-day period + duration: 2592000, // 30 days unlimited access +}); + +// DATA OWNER: Add protected data to the time-based subscription bundle +await dataProtectorSharing.setProtectedDataToSubscription({ + protectedData: '0x123abc...', +}); + +// DATA OWNER: Add more data to the same subscription +await dataProtectorSharing.setProtectedDataToSubscription({ + protectedData: '0x456def...', // Additional dataset +}); + +// CLIENT/SUBSCRIBER: Get time-based subscription access +const subscription = await dataProtectorSharing.subscribeToCollection({ + collectionId: collection.collectionId, + price: 20000000000, // Pay for full period + duration: 2592000, // 30 days unlimited usage +}); +``` + +**Perfect for**: + +- Growing datasets (daily market data, news feeds) +- Educational content series +- Research datasets that expand over time +- SaaS-style data access + +#### **Sale Model** + +Transfer permanent ownership of your data to the buyer. + +```ts twoslash +import { + IExecDataProtectorSharing, + getWeb3Provider, +} from '@iexec/dataprotector'; + +const web3Provider = getWeb3Provider('PRIVATE_KEY'); +const dataProtectorSharing = new IExecDataProtectorSharing(web3Provider); +// ---cut--- +// DATA OWNER: List data for sale +await dataProtectorSharing.setProtectedDataForSale({ + protectedData: '0x123abc...', + price: 100000000000, // 100 RLC purchase price +}); + +// CLIENT/BUYER: Purchase ownership +const purchase = await dataProtectorSharing.buyProtectedData({ + protectedData: '0x123abc...', + price: 100000000000, +}); +``` + +**Perfect for**: + +- Unique datasets or models +- Digital assets and NFT data +- One-time valuable insights +- When you want to exit data ownership + +## Which Approach to Choose? + +| **Signed Orders (Core)** | **Time-Based Access (Sharing)** | +| ---------------------------- | ------------------------------- | +| Usage counting & pay-per-use | Time periods & unlimited usage | +| Direct signed orders | Smart contract automation | +| High control, simple setup | Medium control, flexible models | + +**Choose Signed Orders when**: You need precise control, direct partnerships, +and usage-based billing. + +**Choose Time-Based Access when**: You want automated distribution, unlimited +usage periods, and flexible pricing models. + +## Next Steps + +**Ready to start monetizing your data?** Here are your next steps: + +- **See it in action**: Try the + [Content Creator demo](/overview/use-case-demo/content-creator) to understand + the full flow +- **Start simple**: Begin with + [pay-per-use via grantAccess](/manage-data/guides/create-and-share-access) +- **Explore sharing**: Try + [DataProtector Sharing](/manage-data/dataProtector/dataProtectorSharing) for + automated distribution +- **Build collections**: Learn about + [collection management](/manage-data/dataProtector/dataProtectorSharing/collection) +- **Set up subscriptions**: Implement + [recurring revenue models](/manage-data/dataProtector/dataProtectorSharing/subscription) diff --git a/src/manage-data/what-is-protected-data.md b/src/manage-data/what-is-protected-data.md index eb29223d..44afe224 100644 --- a/src/manage-data/what-is-protected-data.md +++ b/src/manage-data/what-is-protected-data.md @@ -5,54 +5,205 @@ description: Understanding iExec's data protection mechanisms # ❓ What Is Protected Data? -Protected Data is iExec's revolutionary approach to data privacy and ownership. -It allows you to maintain control over your data while enabling computation on -it without exposing the raw information. +Protected Data refers to any data encrypted using the **iExec Data Protector +tool**. This end-to-end encryption solution enables users to protect, manage and +monetize their data within the Web3 ecosystem. -## Key Concepts - -### Data Ownership - -- **You own your data**: The original data never leaves your control -- **Granular permissions**: Decide who can access and use your data -- **Revocable access**: Grant and revoke permissions at any time - -### Privacy-Preserving Computation - -- **Encrypted processing**: Data is encrypted during computation -- **TEE (Trusted Execution Environment)**: Secure enclaves protect data during - processing -- **Zero-knowledge**: Compute on data without revealing it +
+

Unlike standard datasets, Protected Data exposes its data types on-chain (for example, indicating that it contains an email address or a photo). This allows anyone to identify entries with the corresponding types.

+
-### Monetization +## Key Concepts -- **Data marketplaces**: Sell access to your protected data -- **Usage tracking**: Monitor how your data is being used -- **Fair compensation**: Get paid for data usage +### πŸ‘‘ Data Governance + +
+ +
+
+
+ β€’ +
+ You own your data: The original data never leaves your control +
+
+
+ β€’ +
+ Granular permissions: Decide who can access and use your data +
+
+
+ β€’ +
+ Revocable access: Grant and revoke permissions at any time +
+
+
+
+ +### πŸ”’ Privacy-Preserving Computation + +
+ +
+
+
+ β€’ +
+ Encrypted Processing: Maintains a complete chain of trust. +
+
+
+ β€’ +
+ TEE (Trusted Execution Environment): Secure enclaves protect data during processing +
+
+
+ β€’ +
+ Secret storage: Secrets stored in a TEE database. +
+
+
+
+ +### πŸ’° Monetization + +
+ +
+
+
+ β€’ +
+ Data marketplaces: Sell access to your protected data +
+
+
+ β€’ +
+ Usage tracking: Monitor how your data is being used +
+
+
+ β€’ +
+ Fair compensation: Get paid for data usage +
+
+
+
## How It Works -1. **Protect**: Encrypt and register your data on the iExec network -2. **Share**: Grant access permissions to specific users or applications -3. **Monitor**: Track usage and maintain control -4. **Monetize**: Earn from your data while keeping it private +
+
+
+ 1. +
+ Protect: Encrypt and register your data on the iExec network +
+
+
+ 2. +
+ Share: Authorize specific users and applications to access your data +
+
+
+ 3. +
+ Monitor: Track usage and maintain control +
+
+
+ 4. +
+ Monetize: Earn from your data while keeping it private +
+
+
+ 5. +
+ Compute: Authorized users can compute on your data with the authorized iApps +
+
+
+
## Use Cases -- **Personal Data**: Health records, financial data, personal preferences -- **Business Intelligence**: Market research, customer analytics, proprietary - datasets -- **AI Training**: Training models without exposing sensitive data -- **Research**: Collaborative research with privacy guarantees +
+
+
+ πŸ‘€ +

Personal Data

+
+
    +
  • Health records
  • +
  • Financial data
  • +
  • Personal preferences
  • +
+
+ +
+
+ 🏒 +

Business Intelligence

+
+
    +
  • Market research
  • +
  • Customer analytics
  • +
  • Proprietary datasets
  • +
+
+ +
+
+ πŸ€– +

AI Training

+
+
    +
  • Training models without exposing sensitive data
  • +
  • Federated learning
  • +
  • Privacy-preserving ML
  • +
+
+ +
+
+ πŸ”¬ +

Research

+
+
    +
  • Collaborative research with privacy guarantees
  • +
  • Cross-institutional studies
  • +
  • Clinical trial data
  • +
+
+
+ +
+

Ready to protect your data? Start with our DataProtector guides and learn how to secure your sensitive information while unlocking its value.

+
## Next Steps -Ready to protect your data? Check out: - -- [Getting Started with DataProtector](/manage-data/dataProtector/getting-started) -- [DataProtector Guides](/manage-data/guides) - ---- - -_Protect your data, maintain control, and unlock its value with iExec's -DataProtector._ +
+
+
+ πŸ“š + +
+
+ πŸš€ +
+ Getting Started: DataProtector Quick Start Guide +
+
+
+