aitbc/docs/contracts/PNPM_SETUP.md

pnpm Setup for AITBC Contracts

Level: Intermediate
Prerequisites: Node.js, familiarity with package managers
Estimated Time: 5 minutes
Last Updated: 2026-05-22
Version: 1.0

🧭 Navigation Path:

🏠 Documentation Home → 📜 Contracts → ⚙️ pnpm Setup

breadcrumb: Home → Contracts → pnpm Setup

---

🎯 See Also:

• 📦 Smart Contract Deployment: SMART_CONTRACT_DEPLOYMENT.md - Deployment guide using pnpm
• 🔧 Development Guidelines: DEVELOPMENT_GUIDELINES.md - General development setup
• 📜 Contracts Overview: contracts/README.md - Contract documentation index

---

📦 Overview

AITBC uses pnpm as the package manager for both smart contract projects:

• /opt/aitbc/contracts/ - Main Hardhat project (JavaScript-based)
• /opt/aitbc/packages/solidity/aitbc-token/ - Token contracts (TypeScript-based)

pnpm provides faster installations, better disk efficiency, and stricter dependency management compared to npm.

📋 Configuration Files

.npmrc

contracts/ directory:

auto-install-peers=false
strict-peer-dependencies=true
prefer-frozen-lockfile=true
shamefully-hoist=true

packages/solidity/aitbc-token/ directory:

auto-install-peers=false
strict-peer-dependencies=true
prefer-frozen-lockfile=true
engine-strict=true

Settings explained:

• auto-install-peers=false: Don't automatically install peer dependencies - requires explicit installation
• strict-peer-dependencies=true: Fail if peer dependency requirements aren't met
• prefer-frozen-lockfile=true: Use exact versions from lockfile (recommended for CI)
• shamefully-hoist=true (contracts only): Hoist dependencies to node_modules root for compatibility with older Hardhat
• engine-strict=true (aitbc-token only): Enforce Node.js version requirement (>=24.14.0)

pnpm-lock.yaml

The lockfile is automatically generated and should be committed to version control. It ensures reproducible installs across environments.

🚀 Common Commands

Installation

# For main contracts
cd /opt/aitbc/contracts
pnpm install

# For aitbc-token
cd /opt/aitbc/packages/solidity/aitbc-token
pnpm install

Development Commands

contracts/ (JavaScript-based):

cd /opt/aitbc/contracts
pnpm hardhat compile
pnpm hardhat test
pnpm hardhat run scripts/deploy.js --network localhost
pnpm hardhat verify --network mainnet <ADDRESS> <CONSTRUCTOR_ARGS>

aitbc-token/ (TypeScript-based):

cd /opt/aitbc/packages/solidity/aitbc-token
pnpm run build
pnpm run test
pnpm run lint
pnpm run format
pnpm run deploy

CI/CD Commands

# Install with frozen lockfile (recommended for CI)
pnpm install --frozen-lockfile

🔧 Migration from npm

If you're migrating from npm to pnpm:

1. Delete npm artifacts:

   rm package-lock.json
   rm -rf node_modules
   

2. Install pnpm (if not already installed):

   npm install -g pnpm
   

3. Install dependencies with pnpm:

   pnpm install
   

4. Update scripts: Replace npm with pnpm and npx with pnpm

📊 Benefits of pnpm

• Speed: 2-3x faster installations than npm
• Disk Space: ~50% reduction through content-addressable storage
• Strictness: Better dependency resolution and peer dependency handling
• Reproducibility: More reliable lockfile behavior

🛠️ Troubleshooting

Build scripts fail

If you encounter build script errors, you may need to approve specific packages:

pnpm approve-builds <package-name>

Peer dependency errors

If strict peer dependency checking causes issues, you can temporarily disable it:

pnpm install --strict-peer-dependencies=false

Cache issues

Clear the pnpm cache if you encounter unexpected behavior:

pnpm store prune

🔄 CI/CD Integration

All CI workflows have been updated to use pnpm:

• smart-contract-tests.yml - Tests both contracts/ and aitbc-token/
• package-tests.yml - Tests aitbc-token/ package
• deploy-testnet.yml - Testnet deployment
• deploy-mainnet.yml - Mainnet deployment
• contract-benchmarks.yml - Performance benchmarks
• staking-tests.yml - Staking contract tests

Workflows automatically install pnpm if not available on the runner.

---

Last updated: 2026-05-22
Version: 1.0
Status: Active