|
| 1 | +# Contract Dependency Manager (CDM) |
| 2 | + |
| 3 | +A CLI tool for managing PVM smart contract dependencies on Polkadot. CDM automates contract deployment ordering, cross-contract address resolution, and TypeScript type generation. |
| 4 | + |
| 5 | +## Quick Install |
| 6 | + |
| 7 | +```bash |
| 8 | +curl -fsSL https://raw.githubusercontent.com/paritytech/contract-dependency-manager/main/install.sh | bash |
| 9 | +``` |
| 10 | + |
| 11 | +## Quick Start |
| 12 | + |
| 13 | +```bash |
| 14 | +# Start a local network (Product Preview Net) |
| 15 | +curl -sL https://raw.githubusercontent.com/paritytech/ppn-proxy/main/install.sh | bash |
| 16 | +cd ppn && make start |
| 17 | + |
| 18 | +# Scaffold a new project |
| 19 | +cdm template my-project |
| 20 | +cd my-project |
| 21 | + |
| 22 | +# Build contracts |
| 23 | +cdm build |
| 24 | + |
| 25 | +# Deploy to local Asset Hub (bootstrap mode) |
| 26 | +cdm deploy --bootstrap ws://127.0.0.1:10020 |
| 27 | + |
| 28 | +# Add a contract library to your TypeScript project |
| 29 | +cdm add @polkadot/reputation --registry 0x... |
| 30 | +``` |
| 31 | + |
| 32 | +## Local Network (PPN) |
| 33 | + |
| 34 | +CDM requires a running Polkadot chain with the Revive pallet for contract deployment. For local development, use **Product Preview Net (PPN)**, which spins up both a Bulletin and Asset Hub parachain locally. |
| 35 | + |
| 36 | +```bash |
| 37 | +# Install and start PPN |
| 38 | +curl -sL https://raw.githubusercontent.com/paritytech/ppn-proxy/main/install.sh | bash |
| 39 | +cd ppn && make start |
| 40 | +``` |
| 41 | + |
| 42 | +Once running, Asset Hub is available at `ws://127.0.0.1:10020`. This is the default URL used by CDM scripts for local development. |
| 43 | + |
| 44 | +## How It Works |
| 45 | + |
| 46 | +CDM solves the "chicken-and-egg" problem of smart contract deployment. When contracts depend on each other, they need to know each other's addresses - but addresses aren't known until deployment. |
| 47 | + |
| 48 | +CDM uses an on-chain **ContractRegistry** to resolve addresses at runtime: |
| 49 | + |
| 50 | +1. Contracts declare dependencies via `#[pvm::contract(cdm = "@scope/name")]` |
| 51 | +2. CDM scans your workspace, builds a dependency graph, and topologically sorts it |
| 52 | +3. Contracts are deployed in order, each registered in the ContractRegistry |
| 53 | +4. At runtime, `cdm_reference()` looks up the latest address from the registry |
| 54 | + |
| 55 | +## Commands |
| 56 | + |
| 57 | +### `cdm build` |
| 58 | +Build all contracts with the ContractRegistry address baked in. |
| 59 | + |
| 60 | +```bash |
| 61 | +CONTRACTS_REGISTRY_ADDR=0x... cdm build |
| 62 | +cdm build --contracts counter counter_writer # Build specific contracts |
| 63 | +cdm build --root /path/to/workspace # Custom workspace root |
| 64 | +``` |
| 65 | + |
| 66 | +### `cdm deploy <url>` |
| 67 | +Deploy and register all contracts to a chain. |
| 68 | + |
| 69 | +```bash |
| 70 | +# Bootstrap: deploy ContractRegistry + all contracts from scratch (local PPN) |
| 71 | +cdm deploy --bootstrap ws://127.0.0.1:10020 |
| 72 | + |
| 73 | +# Standard: deploy CDM contracts (registry already exists) |
| 74 | +CONTRACTS_REGISTRY_ADDR=0x... cdm deploy ws://127.0.0.1:10020 |
| 75 | + |
| 76 | +# Options |
| 77 | +cdm deploy --signer Bob ws://127.0.0.1:10020 # Use different signer |
| 78 | +cdm deploy --dry-run ws://127.0.0.1:10020 # Preview deployment plan |
| 79 | +cdm deploy --skip-build ws://127.0.0.1:10020 # Use pre-built artifacts |
| 80 | +``` |
| 81 | + |
| 82 | +### `cdm add <library>` |
| 83 | +Add a CDM contract library for use with polkadot-api. Queries the on-chain registry for the contract's ABI metadata and installs it locally. |
| 84 | + |
| 85 | +```bash |
| 86 | +cdm add @polkadot/reputation --registry 0x... |
| 87 | +cdm add @polkadot/disputes --url wss://asset-hub.polkadot.io |
| 88 | +``` |
| 89 | + |
| 90 | +### `cdm template [dir]` |
| 91 | +Scaffold a complete example project with 3 contracts demonstrating cross-contract CDM dependencies. |
| 92 | + |
| 93 | +```bash |
| 94 | +cdm template my-project # Create in ./my-project |
| 95 | +cdm template # Create in current directory |
| 96 | +``` |
| 97 | + |
| 98 | +## Writing CDM Contracts |
| 99 | + |
| 100 | +Annotate your contract with a CDM package name: |
| 101 | + |
| 102 | +```rust |
| 103 | +#[pvm::contract(cdm = "@yourscope/mycontract")] |
| 104 | +mod mycontract { |
| 105 | + #[pvm::constructor] |
| 106 | + pub fn new() -> Result<(), Error> { Ok(()) } |
| 107 | + |
| 108 | + #[pvm::method] |
| 109 | + pub fn do_something() -> u32 { 42 } |
| 110 | +} |
| 111 | +``` |
| 112 | + |
| 113 | +To call another CDM contract: |
| 114 | + |
| 115 | +```rust |
| 116 | +// Add the contract as a Cargo dependency |
| 117 | +// Then use cdm_reference() for runtime address lookup |
| 118 | +let other = other_contract::cdm_reference(); |
| 119 | +other.do_something().expect("call failed"); |
| 120 | +``` |
| 121 | + |
| 122 | +## Example: Shared Counter |
| 123 | + |
| 124 | +The included shared-counter template demonstrates a 3-contract system: |
| 125 | + |
| 126 | +- **counter** - Stores a shared count value |
| 127 | +- **counter-writer** - Calls counter to increment (depends on counter via CDM) |
| 128 | +- **counter-reader** - Queries counter for the current value (depends on counter via CDM) |
| 129 | + |
| 130 | +``` |
| 131 | +cdm template my-counter |
| 132 | +cd my-counter |
| 133 | +cdm deploy --bootstrap ws://127.0.0.1:10020 |
| 134 | +cd ts && bun install && bun run src/validate.ts |
| 135 | +``` |
| 136 | + |
| 137 | +## Development |
| 138 | + |
| 139 | +```bash |
| 140 | +git clone https://github.com/paritytech/contract-dependency-manager.git |
| 141 | +cd contract-dependency-manager |
| 142 | +./scripts/setup.sh |
| 143 | + |
| 144 | +# Run in dev mode |
| 145 | +bun run src/cli.ts --help |
| 146 | + |
| 147 | +# Run tests |
| 148 | +make test |
| 149 | + |
| 150 | +# Build native binary |
| 151 | +make compile |
| 152 | + |
| 153 | +# Cross-compile for all platforms |
| 154 | +make compile-all |
| 155 | +``` |
| 156 | + |
| 157 | +## Architecture |
| 158 | + |
| 159 | +``` |
| 160 | +src/ |
| 161 | + cli.ts Entry point (Commander.js) |
| 162 | + commands/ |
| 163 | + build.ts Build contracts with registry address |
| 164 | + deploy.ts Deploy + register contracts on-chain |
| 165 | + add.ts Add contract types via papi |
| 166 | + template.ts Scaffold example project |
| 167 | + lib/ |
| 168 | + detection.ts Workspace scanning, dependency graph, topological sort |
| 169 | + deployer.ts On-chain deployment + ABI encoding |
| 170 | + connection.ts WebSocket / Smoldot chain connections |
| 171 | + signer.ts sr25519 key derivation |
| 172 | +contracts/ |
| 173 | + registry/ ContractRegistry on-chain contract (Rust/PolkaVM) |
| 174 | +templates/ |
| 175 | + shared-counter/ Example project template |
| 176 | +``` |
| 177 | + |
| 178 | +## License |
| 179 | + |
| 180 | +Apache-2.0 |
0 commit comments