From 63926b361dfc3909c791532946c0948d8ccc9c3b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20=27birdy=27=20Danjou?= Date: Tue, 30 Jul 2024 20:22:06 +0200 Subject: [PATCH] docs: add documentation skeleton --- .github/config/commitlint.config.js | 26 ++++++++ .github/release.yml | 17 +++++ .github/workflows/commitlint.yml | 22 +++++++ .github/workflows/linkchecker.yml | 20 ++++++ docs/README.md | 53 ++++++++++++++++ docs/SUMMARY.md | 62 +++++++++++++++++++ docs/developer/contribute.md | 8 +++ docs/developer/roadmap.md | 1 + docs/fundamentals/fhevm/architecture.md | 1 + docs/fundamentals/fhevm/backend.md | 1 + docs/fundamentals/fhevm/contracts.md | 1 + docs/fundamentals/fhevm/dal.md | 1 + docs/fundamentals/fhevm/genesis.md | 1 + docs/fundamentals/fhevm/inputs.md | 1 + docs/fundamentals/fhevm/storage.md | 1 + docs/fundamentals/gateway/asc.md | 1 + docs/fundamentals/gateway/decryption.md | 1 + docs/fundamentals/gateway/proof.md | 1 + docs/fundamentals/gateway/reencryption.md | 1 + docs/fundamentals/glossary.md | 15 +++++ docs/fundamentals/overview.md | 0 docs/fundamentals/tkms/architecture.md | 1 + docs/fundamentals/tkms/blockchain.md | 1 + docs/fundamentals/tkms/threshold.md | 1 + docs/fundamentals/tkms/zama.md | 1 + docs/getting_started/fhevm/configuration.md | 1 + docs/getting_started/fhevm/contracts.md | 1 + docs/getting_started/fhevm/coprocessor.md | 1 + docs/getting_started/fhevm/geth.md | 9 +++ docs/getting_started/fhevm/native.md | 1 + docs/getting_started/gateway/configuration.md | 1 + docs/getting_started/quick_start.md | 1 + docs/getting_started/tkms/contract.md | 1 + docs/getting_started/tkms/create.md | 1 + docs/getting_started/tkms/run.md | 1 + docs/getting_started/tkms/zama.md | 1 + docs/guides/benchmark.md | 1 + docs/guides/hardware.md | 1 + docs/references/fhevm_api.md | 1 + docs/references/gateway_api.md | 1 + 40 files changed, 262 insertions(+) create mode 100644 .github/config/commitlint.config.js create mode 100644 .github/release.yml create mode 100644 .github/workflows/commitlint.yml create mode 100644 .github/workflows/linkchecker.yml create mode 100644 docs/README.md create mode 100644 docs/SUMMARY.md create mode 100644 docs/developer/contribute.md create mode 100644 docs/developer/roadmap.md create mode 100644 docs/fundamentals/fhevm/architecture.md create mode 100644 docs/fundamentals/fhevm/backend.md create mode 100644 docs/fundamentals/fhevm/contracts.md create mode 100644 docs/fundamentals/fhevm/dal.md create mode 100644 docs/fundamentals/fhevm/genesis.md create mode 100644 docs/fundamentals/fhevm/inputs.md create mode 100644 docs/fundamentals/fhevm/storage.md create mode 100644 docs/fundamentals/gateway/asc.md create mode 100644 docs/fundamentals/gateway/decryption.md create mode 100644 docs/fundamentals/gateway/proof.md create mode 100644 docs/fundamentals/gateway/reencryption.md create mode 100644 docs/fundamentals/glossary.md create mode 100644 docs/fundamentals/overview.md create mode 100644 docs/fundamentals/tkms/architecture.md create mode 100644 docs/fundamentals/tkms/blockchain.md create mode 100644 docs/fundamentals/tkms/threshold.md create mode 100644 docs/fundamentals/tkms/zama.md create mode 100644 docs/getting_started/fhevm/configuration.md create mode 100644 docs/getting_started/fhevm/contracts.md create mode 100644 docs/getting_started/fhevm/coprocessor.md create mode 100644 docs/getting_started/fhevm/geth.md create mode 100644 docs/getting_started/fhevm/native.md create mode 100644 docs/getting_started/gateway/configuration.md create mode 100644 docs/getting_started/quick_start.md create mode 100644 docs/getting_started/tkms/contract.md create mode 100644 docs/getting_started/tkms/create.md create mode 100644 docs/getting_started/tkms/run.md create mode 100644 docs/getting_started/tkms/zama.md create mode 100644 docs/guides/benchmark.md create mode 100644 docs/guides/hardware.md create mode 100644 docs/references/fhevm_api.md create mode 100644 docs/references/gateway_api.md diff --git a/.github/config/commitlint.config.js b/.github/config/commitlint.config.js new file mode 100644 index 00000000..136b4350 --- /dev/null +++ b/.github/config/commitlint.config.js @@ -0,0 +1,26 @@ +const RuleConfigSeverity = require('@commitlint/types').RuleConfigSeverity; +const Configuration = { + /* + * Resolve and load @commitlint/config-conventional from node_modules. + * Referenced packages must be installed + */ + extends: ['@commitlint/config-conventional'], + /* + * Resolve and load conventional-changelog-atom from node_modules. + * Referenced packages must be installed + */ + parserPreset: 'conventional-changelog-conventionalcommits', + /* + * Resolve and load @commitlint/format from node_modules. + * Referenced package must be installed + */ + formatter: '@commitlint/format', + /* + * Any rules defined here will override rules from @commitlint/config-conventional + */ + rules: { + 'type-empty': [RuleConfigSeverity.Error, 'never'], + }, +}; + +module.exports = Configuration; diff --git a/.github/release.yml b/.github/release.yml new file mode 100644 index 00000000..0f15e793 --- /dev/null +++ b/.github/release.yml @@ -0,0 +1,17 @@ +changelog: + categories: + - title: Breaking Changes + labels: + - breaking-changes + - title: New features + labels: + - features + - title: Improvements + labels: + - improvements + - title: Fixes + labels: + - fix + - title: Other Changes + labels: + - "*" diff --git a/.github/workflows/commitlint.yml b/.github/workflows/commitlint.yml new file mode 100644 index 00000000..49964107 --- /dev/null +++ b/.github/workflows/commitlint.yml @@ -0,0 +1,22 @@ +name: Run commitlint on PR + +on: + pull_request: + +jobs: + commitlint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6 + with: + fetch-depth: 0 + - name: Setup Node + uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.2 + with: + node-version: 20.x + - run: npm ci + - name: Install commitlint + run: | + npm install -g @commitlint/cli@^18 + - name: Validate all commits from PR + run: npx commitlint --config .github/config/commitlint.config.js --from ${{ github.event.pull_request.base.sha }} --to ${{ github.event.pull_request.head.sha }} --verbose diff --git a/.github/workflows/linkchecker.yml b/.github/workflows/linkchecker.yml new file mode 100644 index 00000000..1a73339f --- /dev/null +++ b/.github/workflows/linkchecker.yml @@ -0,0 +1,20 @@ +name: Check Markdown links + +on: + pull_request: + push: + branches: + - main + schedule: + # Run everyday at 9:00 AM (See https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html#tag_20_25_07) + - cron: "0 9 * * *" + +jobs: + markdown-link-check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@master + - uses: gaurav-nelson/github-action-markdown-link-check@d53a906aa6b22b8979d33bc86170567e619495ec # v1.0.15 + with: + use-quiet-mode: "yes" + use-verbose-mode: "yes" diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..1122803a --- /dev/null +++ b/docs/README.md @@ -0,0 +1,53 @@ +--- +description: >- + fhEVM is a technology that enables confidential smart contracts on the EVM + using Fully Homomorphic Encryption (FHE). +layout: + title: + visible: true + description: + visible: true + tableOfContents: + visible: true + outline: + visible: true + pagination: + visible: false +--- + +# Welcome to fhEVM + +## Get started + +Learn the basics of fhEVM, set it up, and make it run with ease. + +
What is fhEVMUnderstand the basic concepts of fhEVM library.start1.pngoverview.md
Write contractStart writing fhEVM smart contract using Hardhat templatestart4.pnghardhat.md
Deploy on fhEVM nativeGet 10 Zama token to start working with fhEVM nativestart2.pngdevnet.md
Deploy on EthereumComing soon!start5.pngethereum.md
+ +### References + +Refer to the API and access additional resources for in-depth explanations while working with fhEVM. + +- [fhEVM API specifications](references/fhevm_api.md) +- [Gateway API specifications](references/gateway_api.md) + +### Supports + +Ask technical questions and discuss with the community. Our team of experts usually answers within 24 hours in working days. + +- [Community forum](https://community.zama.ai/c/fhevm/15) +- [Discord channel](https://discord.com/invite/fhe-org) +- [Telegram](https://t.me/+Ojt5y-I7oR42MTkx) + +### Developers + +Collaborate with us to advance the FHE spaces and drive innovation together. + +- [Contribute to fhEVM](developer/contribute.md) +- [Follow the development roadmap](developer/roadmap.md) +- [See the latest test release note](https://github.com/zama-ai/fhevm-backend/releases) +- [Request a feature](https://github.com/zama-ai/fhevm-backend/issues/new) +- [Report a bug](https://github.com/zama-ai/fhevm-backend/issues/new) + +--- + +We value your feedback! [Take a 5-question developer survey](http://zama.ai/developer-survey) to improve the fhEVM library and the documentation and help other developers use FHE. diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 00000000..508d00ca --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,62 @@ +# Table of contents + +- [Welcome to fhEVM](README.md) + +## Getting Started + +- [Quick start](getting_started/quick_start.md) +- fhEVM + - [go-ethereum integration](getting_started/fhevm/geth.md) + - [Run Coprocessor](getting_started/fhevm/coprocessor.md) + - [Run Native](getting_started/fhevm/native.md) + - [Deploy initial contracts](getting_started/fhevm/contracts.md) + - [Configuration](getting_started/fhevm/configuration.md) +- Gateway + - [Configuration](getting_started/gateway/configuration.md) +- TKMS + - [Use Zama's TKMS](getting_started/tkms/zama.md) + - [Request the creation of a new private key](getting_started/tkms/create.md) + - [Application Smart Contract](getting_started/tkms/contract.md) + - [Run a KMS](getting_started/tkms/run.md) + +## Fundamentals + +- [Architecture](fundamentals/overview.md) +- fhEVM + - [Architecture](fundamentals/fhevm/architecture.md) + - [Contracts](fundamentals/fhevm/contracts.md) + - [Backend](fundamentals/fhevm/backend.md) + - [Execution](fundamentals/fhevm/execution.md) + - [Storage](fundamentals/fhevm/storage.md) + - [Inputs](fundamentals/fhevm/inputs.md) + - [Data Availability Layer](fundamentals/fhevm/dal.md) + - [Genesis](fundamentals/fhevm/genesis.md) +- Gateway + - [Decryption](fundamentals/gateway/decryption.md) + - [Reencryption](fundamentals/gateway/reencryption.md) + - [Inclusion proof](fundamentals/gateway/proof.md) + - [Decryption and reencryption request on TKMS](fundamentals/gateway/asc.md) +- TKMS + - [Architecture](fundamentals/tkms/architecture.md) + - [Blockchain](fundamentals/tkms/blockchain.md) + - [Threshold protocol](fundamentals/tkms/threshold.md) + - [Zama's TKMS](fundamentals/tkms/zama.md) +- [Glossary](getting_started/glossary.md) + +## Guides + +- [Node hardware](guides/hardware.md) +- [Run a benchmark](guides/benchmark.md) + +## References + +- [fhEVM API specifications](references/fhevm_api.md) +- [Gateway API specifications](references/gateway_api.md) + +## Developer + +- [Contributing](developer/contribute.md) +- [Development roadmap](developer/roadmap.md) +- [Release note](https://github.com/zama-ai/fhevm/releases) +- [Feature request](https://github.com/zama-ai/fhevm/issues/new) +- [Bug report](https://github.com/zama-ai/fhevm/issues/new) diff --git a/docs/developer/contribute.md b/docs/developer/contribute.md new file mode 100644 index 00000000..a7013914 --- /dev/null +++ b/docs/developer/contribute.md @@ -0,0 +1,8 @@ +# Contributing + +There are two ways to contribute to the Zama fhEVM: + +- [Open issues](https://github.com/zama-ai/fhevm/issues/new/choose) to report bugs and typos, or to suggest new ideas +- Request to become an official contributor by emailing [hello@zama.ai](mailto:hello@zama.ai). + +Becoming an approved contributor involves signing our Contributor License Agreement (CLA)). Only approved contributors can send pull requests, so please make sure to get in touch before you do! diff --git a/docs/developer/roadmap.md b/docs/developer/roadmap.md new file mode 100644 index 00000000..437766dd --- /dev/null +++ b/docs/developer/roadmap.md @@ -0,0 +1 @@ +# Roadmap diff --git a/docs/fundamentals/fhevm/architecture.md b/docs/fundamentals/fhevm/architecture.md new file mode 100644 index 00000000..c79bec1a --- /dev/null +++ b/docs/fundamentals/fhevm/architecture.md @@ -0,0 +1 @@ +# Architecture diff --git a/docs/fundamentals/fhevm/backend.md b/docs/fundamentals/fhevm/backend.md new file mode 100644 index 00000000..781894a4 --- /dev/null +++ b/docs/fundamentals/fhevm/backend.md @@ -0,0 +1 @@ +# Backend diff --git a/docs/fundamentals/fhevm/contracts.md b/docs/fundamentals/fhevm/contracts.md new file mode 100644 index 00000000..97404c22 --- /dev/null +++ b/docs/fundamentals/fhevm/contracts.md @@ -0,0 +1 @@ +# Contracts diff --git a/docs/fundamentals/fhevm/dal.md b/docs/fundamentals/fhevm/dal.md new file mode 100644 index 00000000..536f5e14 --- /dev/null +++ b/docs/fundamentals/fhevm/dal.md @@ -0,0 +1 @@ +# Data Availability Layer diff --git a/docs/fundamentals/fhevm/genesis.md b/docs/fundamentals/fhevm/genesis.md new file mode 100644 index 00000000..3b3fdac9 --- /dev/null +++ b/docs/fundamentals/fhevm/genesis.md @@ -0,0 +1 @@ +# Genesis diff --git a/docs/fundamentals/fhevm/inputs.md b/docs/fundamentals/fhevm/inputs.md new file mode 100644 index 00000000..345ade04 --- /dev/null +++ b/docs/fundamentals/fhevm/inputs.md @@ -0,0 +1 @@ +# Inputs diff --git a/docs/fundamentals/fhevm/storage.md b/docs/fundamentals/fhevm/storage.md new file mode 100644 index 00000000..e0e8ac41 --- /dev/null +++ b/docs/fundamentals/fhevm/storage.md @@ -0,0 +1 @@ +# Storage diff --git a/docs/fundamentals/gateway/asc.md b/docs/fundamentals/gateway/asc.md new file mode 100644 index 00000000..9fa2002a --- /dev/null +++ b/docs/fundamentals/gateway/asc.md @@ -0,0 +1 @@ +# Decryption and reencryption request on TKMS diff --git a/docs/fundamentals/gateway/decryption.md b/docs/fundamentals/gateway/decryption.md new file mode 100644 index 00000000..160ca24e --- /dev/null +++ b/docs/fundamentals/gateway/decryption.md @@ -0,0 +1 @@ +# Decryption diff --git a/docs/fundamentals/gateway/proof.md b/docs/fundamentals/gateway/proof.md new file mode 100644 index 00000000..7d255738 --- /dev/null +++ b/docs/fundamentals/gateway/proof.md @@ -0,0 +1 @@ +# Inclusion proof diff --git a/docs/fundamentals/gateway/reencryption.md b/docs/fundamentals/gateway/reencryption.md new file mode 100644 index 00000000..251e25d0 --- /dev/null +++ b/docs/fundamentals/gateway/reencryption.md @@ -0,0 +1 @@ +# Reencryption diff --git a/docs/fundamentals/glossary.md b/docs/fundamentals/glossary.md new file mode 100644 index 00000000..26c739cd --- /dev/null +++ b/docs/fundamentals/glossary.md @@ -0,0 +1,15 @@ +# Glossary + +## Smart Contracts + +### fhEVM + +- _ACL smart contract_: Smart contract deployed on the fhEVM blockchain to manage access control of ciphertexts. dApp contracts use this to persists their own access rights and to delegate access to other contracts. + +- _Gateway smart contract_: Smart contract deployed on the fhEVM blockchain that is used by a dApp smart contract to request a decrypt. This emits an event that triggers the gateway. + +- _KMS smart contract_: Smart contract running on the fhEVM blockchain that is used by a dApp contract to verify decryption results from the KMS. To that end, it contains the identity of the KMS and is used to verify its signatures. + +### TKMS + +- _fhEVM ASC_: Smart contract to which transaction from the gateway (connector) are submitted to. This contract contains all customization logic required to work with the specific fhEVM blockchain. diff --git a/docs/fundamentals/overview.md b/docs/fundamentals/overview.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/fundamentals/tkms/architecture.md b/docs/fundamentals/tkms/architecture.md new file mode 100644 index 00000000..c79bec1a --- /dev/null +++ b/docs/fundamentals/tkms/architecture.md @@ -0,0 +1 @@ +# Architecture diff --git a/docs/fundamentals/tkms/blockchain.md b/docs/fundamentals/tkms/blockchain.md new file mode 100644 index 00000000..fd677760 --- /dev/null +++ b/docs/fundamentals/tkms/blockchain.md @@ -0,0 +1 @@ +# Blockchain diff --git a/docs/fundamentals/tkms/threshold.md b/docs/fundamentals/tkms/threshold.md new file mode 100644 index 00000000..65f313b0 --- /dev/null +++ b/docs/fundamentals/tkms/threshold.md @@ -0,0 +1 @@ +# Threshold diff --git a/docs/fundamentals/tkms/zama.md b/docs/fundamentals/tkms/zama.md new file mode 100644 index 00000000..fdfd296c --- /dev/null +++ b/docs/fundamentals/tkms/zama.md @@ -0,0 +1 @@ +# Zama's TKMS diff --git a/docs/getting_started/fhevm/configuration.md b/docs/getting_started/fhevm/configuration.md new file mode 100644 index 00000000..a025a48b --- /dev/null +++ b/docs/getting_started/fhevm/configuration.md @@ -0,0 +1 @@ +# Configuration diff --git a/docs/getting_started/fhevm/contracts.md b/docs/getting_started/fhevm/contracts.md new file mode 100644 index 00000000..60ebf8b8 --- /dev/null +++ b/docs/getting_started/fhevm/contracts.md @@ -0,0 +1 @@ +# Deploy initial contracts diff --git a/docs/getting_started/fhevm/coprocessor.md b/docs/getting_started/fhevm/coprocessor.md new file mode 100644 index 00000000..e9694198 --- /dev/null +++ b/docs/getting_started/fhevm/coprocessor.md @@ -0,0 +1 @@ +# Coprocessor diff --git a/docs/getting_started/fhevm/geth.md b/docs/getting_started/fhevm/geth.md new file mode 100644 index 00000000..875d47c0 --- /dev/null +++ b/docs/getting_started/fhevm/geth.md @@ -0,0 +1,9 @@ +# Integration + +This document is a guide listing detailed steps to integrate `fhevm-backend` into [go-ethereum](https://github.com/ethereum/go-ethereum) or any other implementations that follow the same architecture. + +{% hint style="info" %} +This document is based on go-ethereum v1.13.5 +{% endhint %} + +## Todo diff --git a/docs/getting_started/fhevm/native.md b/docs/getting_started/fhevm/native.md new file mode 100644 index 00000000..7e052a37 --- /dev/null +++ b/docs/getting_started/fhevm/native.md @@ -0,0 +1 @@ +# Native diff --git a/docs/getting_started/gateway/configuration.md b/docs/getting_started/gateway/configuration.md new file mode 100644 index 00000000..a025a48b --- /dev/null +++ b/docs/getting_started/gateway/configuration.md @@ -0,0 +1 @@ +# Configuration diff --git a/docs/getting_started/quick_start.md b/docs/getting_started/quick_start.md new file mode 100644 index 00000000..754bef8a --- /dev/null +++ b/docs/getting_started/quick_start.md @@ -0,0 +1 @@ +# Quick start diff --git a/docs/getting_started/tkms/contract.md b/docs/getting_started/tkms/contract.md new file mode 100644 index 00000000..bc3b56c9 --- /dev/null +++ b/docs/getting_started/tkms/contract.md @@ -0,0 +1 @@ +# Application Smart Contract diff --git a/docs/getting_started/tkms/create.md b/docs/getting_started/tkms/create.md new file mode 100644 index 00000000..8137a599 --- /dev/null +++ b/docs/getting_started/tkms/create.md @@ -0,0 +1 @@ +# Request the creation of a new private key diff --git a/docs/getting_started/tkms/run.md b/docs/getting_started/tkms/run.md new file mode 100644 index 00000000..e3c50122 --- /dev/null +++ b/docs/getting_started/tkms/run.md @@ -0,0 +1 @@ +# Run a KMS diff --git a/docs/getting_started/tkms/zama.md b/docs/getting_started/tkms/zama.md new file mode 100644 index 00000000..f286d2a1 --- /dev/null +++ b/docs/getting_started/tkms/zama.md @@ -0,0 +1 @@ +# Use Zama's TKMS diff --git a/docs/guides/benchmark.md b/docs/guides/benchmark.md new file mode 100644 index 00000000..a9433136 --- /dev/null +++ b/docs/guides/benchmark.md @@ -0,0 +1 @@ +# Run a benchmark diff --git a/docs/guides/hardware.md b/docs/guides/hardware.md new file mode 100644 index 00000000..84abdd13 --- /dev/null +++ b/docs/guides/hardware.md @@ -0,0 +1 @@ +# Node hardware diff --git a/docs/references/fhevm_api.md b/docs/references/fhevm_api.md new file mode 100644 index 00000000..aa9b9274 --- /dev/null +++ b/docs/references/fhevm_api.md @@ -0,0 +1 @@ +# fhEVM API specifications diff --git a/docs/references/gateway_api.md b/docs/references/gateway_api.md new file mode 100644 index 00000000..d4894644 --- /dev/null +++ b/docs/references/gateway_api.md @@ -0,0 +1 @@ +# Gateway API specifications