# 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)