@excubiae/contracts

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 Design section of the current documentation.

The extensions are ready to use Checker / Policy contracts that give unique features (e.g., enforcing a proof of membership for a Semaphore group with frontrunning resistance).

Please, follow the Guides section for an explanation on how to write, integrate & deploy; your own Checker & Policy contracts.

[!IMPORTANT]
Excubiae is currently in the MVP stage. Audits are not yet available. Expect fast development cycles with potential breaking changes — use at your own risk! Please, refer to release section for latest changes and updates.

Installation

You can install the excubiae contracts with any node package manager (bun, npm, pnpm,yarn):

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 and Foundry, see the Hardhat's documentation to learn more.

Compile contracts

Compile the smart contracts with Hardhat:

yarn compile:hardhat

Compile the smart contracts with Foundry's Forge:

yarn compile:forge

Run both in one command:

yarn compile

Deploy extensions

The package provides deployment scripts for the available extensions.

Semaphore

Deploy a Semaphore extension by providing the Semaphore contract address and group ID. This extension enforces membership proofs for a Semaphore group with frontrunning resistance.

Using Hardhat Ignition:

yarn deploy:semaphore-ignition --parameters '{"semaphoreAddress":"0x1234...5678","groupId":1}' --network sepolia

Using Hardhat task:

yarn deploy:semaphore-task --semaphore-address 0x1234...5678 --group-id 1 --network sepolia

Required parameters per deployment:

• semaphoreAddress: Address of the deployed Semaphore contract
• groupId: ID of the Semaphore group to check membership against
• network: Network to deploy to (e.g., sepolia, hardhat, mainnet)

Testing

Run Mocha to test the contracts (Typescript tests):

yarn test:hardhat

Run Foundry's Forge to test the contracts (Solidity tests):

yarn test:forge

Run both in one command:

yarn test

You can also generate a test coverage report:

yarn test:coverage

Or a test gas report:

yarn test:report-gas

Documentation

You can generate smart contract documentation (book):

yarn docs:forge