Skip to content

add README to contracts dir #403

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
emnul wants to merge 1 commit into
base: main
Choose a base branch
from
Open

add README to contracts dir #403

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 93 additions & 0 deletions contracts/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
# Contracts README

This package contains the Compact smart contract source files, compiled artifacts, witness implementations, and test infrastructure for OpenZeppelin Contracts for Compact.

## Directory Structure

```
contracts/
├── src/ # Source files
│ ├── access/ # Access control contracts
│ ├── security/ # Security utility contracts
│ ├── token/ # Token standard contracts
│ ├── utils/ # General utility contracts
│ ├── archive/ # Archived/deprecated contracts
│ └── test-utils/ # Shared test helpers
├── artifacts/ # Compiled contract outputs (generated)
└── dist/ # Compiled TypeScript witness outputs (generated)
```
Comment on lines +7 to +18
Copy link

@coderabbitai coderabbitai bot Mar 18, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add fenced code block languages to satisfy markdownlint (MD040).

Line 7 and Line 24 use unlabeled fences. Add a language (e.g., text) to avoid lint noise in docs CI.

Proposed fix 
-```
+```text
 contracts/
 ├── src/                    # Source files
 │   ├── access/             # Access control contracts
 │   ├── security/           # Security utility contracts
 │   ├── token/              # Token standard contracts
 │   ├── utils/              # General utility contracts
 │   ├── archive/            # Archived/deprecated contracts
 │   └── test-utils/         # Shared test helpers
 ├── artifacts/              # Compiled contract outputs (generated)
 └── dist/                   # Compiled TypeScript witness outputs (generated)

@@
- +text
/
├── .compact # Contract source
├── witnesses/ # TypeScript witness implementations
└── test/
├── .test.ts # Test suite
├── mocks/ # Mock contracts (test-only — see warning below)
└── simulators/ # Simulator helpers for testing

Also applies to: 24-32

🧰 Tools
🪛 markdownlint-cli2 (0.21.0)

[warning] 7-7: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@contracts/README.md` around lines 7 - 18, The two unlabeled fenced code
blocks in contracts/ README.md (the directory tree block beginning with
"contracts/" and the example module block beginning with "<module>/") should be
updated to include a language label (e.g., text) after the opening triple
backticks to satisfy MD040; locate the two code fences and change ``` to ```text
for both the directory tree block and the module example block so the markdown
linter stops flagging unlabeled fences.

Copy link
Contributor Author

@emnul emnul Mar 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We dont use this tool

Copy link

@coderabbitai coderabbitai bot Mar 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@emnul, understood — I'll skip markdownlint-specific suggestions for this repository going forward. Thanks for clarifying!

✏️ Learnings added 
Learnt from: emnul
Repo: OpenZeppelin/compact-contracts PR: 403
File: contracts/README.md:7-18
Timestamp: 2026-03-18T20:40:13.037Z
Learning: The OpenZeppelin/compact-contracts repository does not use markdownlint. Do not raise markdownlint-specific issues (e.g., MD040 fenced code block language) in code reviews for this repository.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

🧠 Learnings used 
Learnt from: emnul
Repo: OpenZeppelin/compact-contracts PR: 366
File: packages/compact/README.md:26-26
Timestamp: 2026-02-11T18:46:22.809Z
Learning: PR `#366` ("upgrade-contracts-versions-0.28.0") is actually targeting Compact version 0.29.0, not 0.28.0 as the branch name suggests. The README.md correctly shows version 0.29.0 in its examples.


## src/

The `src/` directory is organized by module category. Each module follows the same internal layout:

```
<module>/
├── <Contract>.compact # Contract source
├── witnesses/ # TypeScript witness implementations
└── test/
├── <Contract>.test.ts # Test suite
├── mocks/ # Mock contracts (test-only — see warning below)
└── simulators/ # Simulator helpers for testing
```

### src/access/

Access control primitives for restricting who can call contract circuits.

| File | Description |
|------|-------------|
| `AccessControl.compact` | Role-based access control |
| `Ownable.compact` | Single-owner access control |
| `ShieldedAccessControl.compact` | Role-based access control with shielded (private) role assignments |
| `ZOwnablePK.compact` | Single-owner access control with shielded ownership |

### src/security/

Contracts that add common security patterns on top of other modules.

| File | Description |
|------|-------------|
| `Initializable.compact` | One-time initialization mechanism |
| `Pausable.compact` | Emergency pause/unpause mechanism |

### src/token/

Implementations of standard token interfaces.

| File | Description |
|------|-------------|
| `FungibleToken.compact` | ERC-20-style fungible token |
| `NonFungibleToken.compact` | ERC-721-style non-fungible token |
| `MultiToken.compact` | ERC-1155-style multi-token |

### src/utils/

Low-level utilities shared across modules.

| File | Description |
|------|-------------|
| `Utils.compact` | Common helper circuits |

### src/archive/

Contracts that are no longer actively maintained. Do not use in new projects.

### src/test-utils/

Shared TypeScript helpers used across test suites (e.g. address utilities). Not part of the public API.

---

## > ⚠️ Mock Contracts Are For Testing Only

Each module's `test/mocks/` directory contains `Mock*.compact` files (e.g. `MockFungibleToken.compact`, `MockOwnable.compact`, `MockAccessControl.compact`).

**These contracts exist solely to expose internal state and circuits for testing purposes. They must never be used in production.**

Mock contracts typically:
- Expose internal or protected circuits publicly for direct testing
- Skip access control or safety checks to isolate specific behaviors
- Introduce additional state that makes testing easier but is unsafe in deployment

**Using a Mock contract in production would undermine the security guarantees the corresponding production contract is designed to provide.**
Loading