From 3b19b24c03178a4ea9631874d167ef5e0893ffdf Mon Sep 17 00:00:00 2001 From: Giacomo Date: Tue, 3 Dec 2024 19:31:35 +0100 Subject: [PATCH 1/2] docs: add first version of readmes --- README.md | 99 +++++++++++++++++++++++++- packages/contracts/contracts/README.md | 76 +++++++++++++++++++- 2 files changed, 172 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 98b2934..11578b8 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,98 @@ -# excubiae +# Excubiae -an on-chain flexible & modular framework for implementing custom gatekeepers. +Excubiae is a composable framework for building custom attribute-based access control policies on Ethereum. + +The framework provides a set of common, abstract, and flexible smart contracts to simplify the creation of reusable, attribute-based criteria. These contracts, called "gatekeepers," are solution-agnostic, enforcing checks against user-provided evidence and maintaining records of those who meet the criteria. + +This approach enables seamless interoperability across different protocols. For instance, a single check could combine verifiable attributes from Semaphore and MACI, ensuring flexible and composable access control based on two different protocols. Indeed, for example, you can define criteria to verify token ownership or/and validate a zero-knowledge proof (ZKP). Using these criteria, you can create a policy to enforce the checks and integrate it seamlessly into your smart contract logic. A practical use case might involve requiring verification before registering a new voter for a poll (e.g., in a MACI-based voting system). + +You can learn more in this [design document](https://hackmd.io/@0xjei/B1RXoTh71e). + +> [!IMPORTANT] +> Excubiae is currently in the MVP stage. Official documentation and audits are not yet available. Expect fast development cycles with potential breaking changes — use at your own risk! + +## Installation + +Clone this repository: + +```bash +git clone https://github.com/privacy-scaling-explorations/excubiae.git +``` + +and install the dependencies: + +```bash +cd excubiae && yarn +``` + +## Usage + +### Format + +Run [Prettier](https://prettier.io/) to check formatting rules: + +```bash +yarn format +``` + +or to automatically format the code: + +```bash +yarn format:write +``` + +### Lint + +Combination of [ESLint](https://eslint.org/) & [Solhint](https://protofire.github.io/solhint/) + +```bash +yarn lint +``` + +### Testing + +Test the code: + +```bash +yarn test +``` + +### Build + +Build all packages & apps: + +```bash +yarn build +``` + +Compile all contracts: + +```bash +yarn compile:contracts +``` + +### Releases + +1. Bump a new version of the package with: + +```bash +yarn version:bump +# e.g. yarn version:bump imt.sol 2.0.0 +``` + +This step creates a commit and a git tag. + +2. Push the changes to main: + +```bash +git push origin main +``` + +3. Push the new git tag: + +```bash +git push origin - +# e.g. git push origin excubiae-v0.1.0 +``` + +After pushing the new git tag, a workflow will be triggered and will publish the package on [npm](https://www.npmjs.com/) and release a new version on Github with its changelogs automatically. diff --git a/packages/contracts/contracts/README.md b/packages/contracts/contracts/README.md index c9f9bb7..3128bea 100644 --- a/packages/contracts/contracts/README.md +++ b/packages/contracts/contracts/README.md @@ -1 +1,75 @@ -contracts/README.md +# Excubiae Smart Contracts + +This package contains the smart contracts which define the composable framework for building custom attribute-based access control policies on Ethereum. + +You can learn more in the Smart Contracts section of this [design document](https://hackmd.io/@0xjei/B1RXoTh71e#Smart-Contracts). + +> [!IMPORTANT] +> Excubiae is currently in the MVP stage. Official documentation and audits are not yet available. Expect fast development cycles with potential breaking changes — use at your own risk! + +## Installation + +You can install the excubiae contracts with any node package manager (`bun`, `npm`, `pnpm`,`yarn`): + +```bash +bun add @excubiae/contracts +npm i @excubiae/contracts +pnpm add @excubiae/contracts +yarn add @excubiae/contracts +``` + +## Usage + +This package is configured to support the combination of [Hardhat](https://hardhat.org/) and [Foundry](https://book.getfoundry.sh/), see the Hardhat [documentation](https://hardhat.org/hardhat-runner/docs/advanced/hardhat-and-foundry) to learn more. + +### Compile contracts + +Compile the smart contracts with [Hardhat](https://hardhat.org/): + +```bash +yarn compile:hardhat +``` + +Compile the smart contracts with Foundry's [Forge](https://book.getfoundry.sh/forge/): + +```bash +yarn compile:forge +``` + +Run both in one command: + +```bash +yarn compile +``` + +### Testing + +Run [Mocha](https://mochajs.org/) to test the contracts (Typescript tests): + +```bash +yarn test:hardhat +``` + +Run Foundry's [Forge](https://book.getfoundry.sh/forge/) to test the contracts (Solidity tests): + +```bash +yarn test:forge +``` + +Run both in one command: + +```bash +yarn test +``` + +You can also generate a test coverage report: + +```bash +yarn test:coverage +``` + +Or a test gas report: + +```bash +yarn test:report-gas +``` From 55f6037ce29fb1d44196ec4ae066de7483851ad2 Mon Sep 17 00:00:00 2001 From: Giacomo Date: Wed, 4 Dec 2024 12:03:58 +0100 Subject: [PATCH 2/2] docs: small nits on readmes --- README.md | 10 +++++----- packages/contracts/contracts/README.md | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 11578b8..654f99c 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ # Excubiae -Excubiae is a composable framework for building custom attribute-based access control policies on Ethereum. +Excubiae is a composable framework for creating custom attribute-based access control policies on EVM-compatible networks. -The framework provides a set of common, abstract, and flexible smart contracts to simplify the creation of reusable, attribute-based criteria. These contracts, called "gatekeepers," are solution-agnostic, enforcing checks against user-provided evidence and maintaining records of those who meet the criteria. +It provides a set of abstract and flexible smart contracts, known as "gatekeepers," to streamline the definition of reusable criteria. These solution-agnostic contracts enforce checks against user-provided evidence and track those who satisfy the requirements. -This approach enables seamless interoperability across different protocols. For instance, a single check could combine verifiable attributes from Semaphore and MACI, ensuring flexible and composable access control based on two different protocols. Indeed, for example, you can define criteria to verify token ownership or/and validate a zero-knowledge proof (ZKP). Using these criteria, you can create a policy to enforce the checks and integrate it seamlessly into your smart contract logic. A practical use case might involve requiring verification before registering a new voter for a poll (e.g., in a MACI-based voting system). +This approach enables seamless interoperability across different protocols. For instance, a single check could combine verifiable attributes from Semaphore and MACI, ensuring flexible and composable access control. Indeed, for example, you can define criteria to verify token ownership and/or validate a zero-knowledge proof (ZKP). Using these criteria, you can create a policy to enforce the checks and integrate it seamlessly into your smart contract logic. A practical use case might involve requiring verification before registering a new voter for a poll (e.g., in a MACI-based voting system). You can learn more in this [design document](https://hackmd.io/@0xjei/B1RXoTh71e). @@ -77,7 +77,7 @@ yarn compile:contracts ```bash yarn version:bump -# e.g. yarn version:bump imt.sol 2.0.0 +# e.g. yarn version:bump excubiae 0.2.0 ``` This step creates a commit and a git tag. @@ -92,7 +92,7 @@ git push origin main ```bash git push origin - -# e.g. git push origin excubiae-v0.1.0 +# e.g. git push origin excubiae-v0.2.0 ``` After pushing the new git tag, a workflow will be triggered and will publish the package on [npm](https://www.npmjs.com/) and release a new version on Github with its changelogs automatically. diff --git a/packages/contracts/contracts/README.md b/packages/contracts/contracts/README.md index 3128bea..e5393b7 100644 --- a/packages/contracts/contracts/README.md +++ b/packages/contracts/contracts/README.md @@ -20,7 +20,7 @@ yarn add @excubiae/contracts ## Usage -This package is configured to support the combination of [Hardhat](https://hardhat.org/) and [Foundry](https://book.getfoundry.sh/), see the Hardhat [documentation](https://hardhat.org/hardhat-runner/docs/advanced/hardhat-and-foundry) to learn more. +This package is configured to support the combination of [Hardhat](https://hardhat.org/) and [Foundry](https://book.getfoundry.sh/), see the Hardhat's [documentation](https://hardhat.org/hardhat-runner/docs/advanced/hardhat-and-foundry) to learn more. ### Compile contracts