113 lines
4.9 KiB
Markdown
113 lines
4.9 KiB
Markdown
# AGENTS.md
|
||
|
||
Guidance for AI agents working on this repository.
|
||
|
||
## Project overview
|
||
|
||
`@kredits/contracts` — Solidity smart contracts and a JavaScript (ethers v5)
|
||
wrapper for [Kosmos Kredits](https://wiki.kosmos.org/Kredits), a contribution
|
||
tracking DAO running on EVM chains (primarily RSK). Contributors earn kredits
|
||
for contributions; kredits are withdrawable as ERC20 tokens. All contracts are
|
||
upgradeable via OpenZeppelin hardhat-upgrades proxies.
|
||
|
||
## Tech stack
|
||
|
||
- Solidity ^0.8.0 (compiler 0.8.2), OpenZeppelin upgradeable contracts
|
||
- Hardhat (with @openzeppelin/hardhat-upgrades, hardhat-deploy, hardhat-waffle)
|
||
- JavaScript (CommonJS), ethers v5, ipfs-http-client
|
||
- Tests: mocha + chai + @nomicfoundation/hardhat-chai-matchers
|
||
- Lint: solhint (contracts), eslint (JS)
|
||
|
||
## Repository layout
|
||
|
||
- `contracts/` — Solidity smart contracts (see "Contracts" below)
|
||
- `lib/` — published JavaScript API wrapper (entry: `lib/kredits.js`)
|
||
- `lib/contracts/` — one wrapper class per contract, extending `Base`/`Record`
|
||
- `lib/serializers/` — IPFS JSON serializers (contributor, contribution)
|
||
- `lib/utils/` — ipfs, pagination, validator, preflight, deprecate, format-kredits
|
||
- `lib/abis/` — committed ABI JSON (regenerated by `npm run build:json`)
|
||
- `lib/addresses.json` — chainId → deployed contract addresses
|
||
- `scripts/` — hardhat CLI helpers (create-proxy, seeds, add-/list-*, build-json,
|
||
upgrade-example, import/, export/)
|
||
- `test/contracts/` — mocha tests (Contributor.js, Contribution.js)
|
||
- `config/seeds.js` — demo seed data
|
||
- `hardhat.config.js` — networks: hardhat (1337), rinkeby, rsk (RSK testnet);
|
||
injects `hre.kredits` (an initialized `Kredits` instance)
|
||
|
||
## Contracts
|
||
|
||
All in `contracts/`, all `Initializable` (OpenZeppelin upgradeable):
|
||
|
||
- `Contributor.sol` — contributor registry (account + IPFS profile hash).
|
||
Core team = contributor IDs 1–6 (hardcoded). `withdraw()` mints tokens for
|
||
confirmed, not-yet-withdrawn kredits.
|
||
- `Contribution.sol` — contribution records (ERC721-like ownership). Veto
|
||
period ~40320 blocks (~7 days @ 15s blocks). `add()` → veto window → confirmed.
|
||
- `Reimbursement.sol` — expense reimbursements, same veto pattern.
|
||
- `Token.sol` — ERC20 "Kredits" (symbol KS, 0 decimals). `mintFor` callable only
|
||
by the Contributor contract.
|
||
|
||
Contracts are independent and reference each other by address (set via
|
||
`setContributorContract`, `setContributionContract`, `setTokenContract`).
|
||
Wiring happens in `scripts/create-proxy.js`.
|
||
|
||
## Common commands
|
||
|
||
Bootstrap a local dev environment:
|
||
```
|
||
npm install
|
||
npm run devchain # hardhat node --network hardhat (separate terminal)
|
||
npm run bootstrap # build + deploy proxies + seeds (uses localhost)
|
||
```
|
||
|
||
Other:
|
||
```
|
||
npm run build # compile contracts + regenerate lib/abis
|
||
npm run deploy:dao # deploy upgradeable proxies (scripts/create-proxy.js)
|
||
npm run seeds # seed demo data
|
||
npm run fund # send devchain ETH to an address
|
||
npm test # hardhat test (requires devchain running)
|
||
npm run lint:contracts # solhint
|
||
npm run lint:wrapper # eslint lib/
|
||
```
|
||
|
||
Run a hardhat script: `hardhat run scripts/<name>.js --network localhost`
|
||
(or `--network rsk` for RSK testnet). Use `DEPLOY_KEY=<hex>` to override the
|
||
deploy account.
|
||
|
||
## Conventions
|
||
|
||
### JavaScript (eslint: `lib/`, scripts/, test/)
|
||
- CommonJS (`require`/`module.exports`)
|
||
- 2-space indentation; semicolons required
|
||
- Trailing commas in multiline arrays/objects (not in imports/exports)
|
||
- Space before named function parens: `function foo () {}`, `async () => {}`
|
||
- Async wrappers use `.then()` chains in older code; new code may use async/await
|
||
|
||
### Solidity (solhint: default + recommended)
|
||
- `pragma solidity ^0.8.0;`
|
||
- Upgradeable pattern: `import Initializable`, use `initialize()` (and
|
||
`reinitializer(n)` for upgrades) — never use constructors for state init
|
||
- Interfaces declared inline (e.g. `ContributorInterface`) for cross-contract calls
|
||
- Core-only / deployer-only / contributors-only modifiers guard privileged calls
|
||
|
||
### Upgradeable contract changes
|
||
- Do not use constructors to initialize state (use `initialize`/`reinitializer`)
|
||
- Do not change the order/types of existing storage variables (storage layout!)
|
||
- New storage vars go at the end of the contract
|
||
- See `scripts/upgrade-example.js` and `scripts/create-proxy.js`
|
||
|
||
## Tests
|
||
|
||
Mocha + hardhat-waffle + chai-matchers. `test/contracts/` only covers
|
||
Contributor and Contribution today. When changing contract code, add/adapt
|
||
tests there. Requires a running devchain (`npm run devchain`) for `npm test`.
|
||
|
||
## Networks & deployment
|
||
|
||
- `hardhat` (chainId 1337) — local devchain
|
||
- `rsk` (RSK testnet, https://rsk-testnet.kosmos.org) — primary test deployment
|
||
- `rinkeby` — legacy, configured but deprecated
|
||
- Deployed addresses are tracked per chainId in `lib/addresses.json` and must be
|
||
committed when deployment changes (see `npm run version` script)
|