Develop secure smart contracts using OpenZeppelin Contracts libraries. Use when users need to integrate OpenZeppelin library components — including token standards (ERC20, ERC721, ERC1155), access control (Ownable, AccessControl, AccessManager), security primitives (Pausable, ReentrancyGuard), governance (Governor, timelocks), or accounts (multisig, account abstraction) — into existing or new contracts. Covers pattern discovery from library source, CLI contract generators, and library-first integration. Supports Solidity, Cairo, Stylus, and Stellar.
For conceptual questions ("How does Ownable work?"), explain without generating code. For implementation requests, proceed with the workflow below.
Before generating code or suggesting changes:
Glob for **/*.sol, **/*.cairo, **/*.rs, etc.)If a file cannot be read, surface the failure explicitly — report the path attempted and the reason. Ask whether the path is correct. Never silently fall back to a generic response as if the file does not exist.
Before writing ANY logic, search the OpenZeppelin library for an existing component:
NEVER copy or embed library source code into the user's contract. Always import from the dependency so the project receives security updates. Never hand-write what the library already provides:
paused modifier when Pausable or ERC20Pausable existsrequire(msg.sender == owner) when Ownable existsThe primary workflow is pattern discovery from library source code:
See Pattern Discovery and Integration below for the full step-by-step procedure.
Use npx @openzeppelin/contracts-cli to generate reference implementations for pattern discovery:
generate a baseline to a file, generate with a feature enabled to another file, diff them, and apply the changes to the user's code. The CLI output is the canonical correct integration — use it as the source of truth for what imports, inheritance, storage, and overrides a feature requires.
See CLI Generators for details on the generate-compare-apply workflow.
If no CLI command exists for what's needed, use the generic pattern discovery methodology from Pattern Discovery and Integration. The absence of a CLI command does not mean the library lacks support — it only means there is no generator.
Procedural guide for discovering and applying OpenZeppelin contract integration patterns by reading dependency source code. Works for any ecosystem and any library version.
Prerequisite: Always follow the library-first decision tree above (prefer library components over custom code, never copy/embed source).
Glob for **/*.sol, **/*.cairo, **/*.rs,
or the relevant extension from the lookup table below.node_modules/@openzeppelin/contracts/ (Hardhat/npm) or
lib/openzeppelin-contracts/ (Foundry/forge)Scarb.toml dependencies — source cached by ScarbCargo.toml — source in target/ or the cargo registry cache
(~/.cargo/registry/src/)Cargo.toml — same cargo cache locations as StylusGlob
patterns against the installed source (e.g., node_modules/@openzeppelin/contracts/**/*.sol).
Do not assume knowledge of the library's contents — always verify by listing directories.///, /** */) in Solidity,
doc comments (///) in Rust and Cairo, and README files in the component's directory.test/, tests/, examples/, or mocks/ directories.From Step 2, construct the minimal set of changes needed:
If the contract is upgradeable, any of the above may affect storage compatibility. Consult the relevant upgrade skill before applying.
Do not include anything beyond what the dependency requires. This is the minimal diff between "contract without the feature" and "contract with the feature."
Edit tool. Do not replace the entire file —
integrate into existing code.| Ecosystem | Repository | Documentation | File Extension | Dependency Location |
|---|---|---|---|---|
| Solidity | openzeppelin-contracts | docs.openzeppelin.com/contracts | .sol | node_modules/@openzeppelin/contracts/ or lib/openzeppelin-contracts/ |
| Cairo | cairo-contracts | docs.openzeppelin.com/contracts-cairo | .cairo | Scarb cache (resolve from Scarb.toml) |
| Stylus | rust-contracts-stylus | docs.openzeppelin.com/contracts-stylus | .rs | Cargo cache (~/.cargo/registry/src/) |
| Stellar | stellar-contracts (Architecture) | docs.openzeppelin.com/stellar-contracts | .rs | Cargo cache (~/.cargo/registry/src/) |
Where to find components within each repository:
| Category | Solidity | Cairo | Stylus | Stellar |
|---|---|---|---|---|
| Tokens | contracts/token/{ERC20,ERC721,ERC1155}/ | packages/token/ | contracts/src/token/ | packages/tokens/ |
| Access control | contracts/access/ | packages/access/ | contracts/src/access/ | packages/access/ |
| Governance | contracts/governance/ | packages/governance/ | — | packages/governance/ |
| Proxies / Upgrades | contracts/proxy/ | packages/upgrades/ | contracts/src/proxy/ | packages/contract-utils/ |
| Utilities / Security | contracts/utils/ | packages/utils/, packages/security/ | contracts/src/utils/ | packages/contract-utils/ |
| Accounts | contracts/account/ | packages/account/ | — | packages/accounts/ |
Browse these paths first when searching for a component.
Do not assume override points from prior knowledge — always verify by reading the installed source. Functions that were virtual in an older version may no longer be in the current one, making them non-overridable. The source NatSpec will indicate the correct override point (e.g., NOTE: This function is not virtual, {X} should be overridden instead).
A known example: the Solidity ERC-20 transfer hook changed between v4 and v5. Read the installed ERC20.sol to confirm which function is virtual before recommending an override.
The @openzeppelin/contracts-cli package generates reference OpenZeppelin contract implementations from the command line. Use it as the reference source in the generate-compare-apply workflow whenever a command exists for the contract type.
Run npx @openzeppelin/contracts-cli --help to list available commands. Each command corresponds to a contract type (e.g., solidity-erc20, cairo-erc721, stellar-fungible). Run npx @openzeppelin/contracts-cli <command> --help to see the available options. Do not rely on prior knowledge of what options exist; check --help at the start of a conversation since the CLI may have been updated.
When a CLI command exists for the contract type, pipe generated output to temporary files and diff them to keep generated contract code out of the conversation context:
npx @openzeppelin/contracts-cli solidity-erc20 --name MyToken --symbol MTK > /tmp/oz-baseline.sol
npx @openzeppelin/contracts-cli solidity-erc20 --name MyToken --symbol MTK --pausable > /tmp/oz-variant.sol
diff /tmp/oz-baseline.sol /tmp/oz-variant.sol
For interacting features (e.g., access control + upgradeability), generate a combined variant as well.
The absence of a CLI command does NOT mean the library lacks support. It only means there is no generator for that contract type. Always fall back to the generic pattern discovery methodology in Pattern Discovery and Integration.
Similarly, when a CLI command exists but does not expose an option for a specific feature, do not stop there. Fall back to pattern discovery for that feature: read the installed library source to find the relevant component, extract the integration requirements, and apply them to the user's contract.