Developer overview
This is the starting point for developers who read, test, extend or integrate with COLLAB: what the repository holds, the tools it needs, how to keep builds within a small machine's memory, where to begin for each kind of work, and under which licences everything ships. COLLAB 2.2 is an alpha: its contracts and server kit had AI-assisted internal reviews and no external audit, so treat them as such when you build on them.
What COLLAB is made of
- Contracts in Solidity on GenesisL1 (EVM chain 29, coin L1): a factory that creates each DAO as six clones, shared protocol contracts, the DeSciFi exchange and two read-only lenses. Owner-less and not upgradeable.
- A static web app: HTML, CSS and ES modules served as files, reading the chain in the browser and writing through the visitor's wallet. No bundler, no framework.
- A server kit for Debian and Ubuntu: an installer for nginx with HTTPS, an admin service in Python's standard library, and a prerender job that writes static pages and cache files.
- Tooling in Python: a local chain, sandboxes, a dev server, exporters, the prerender, the docs build, the release build and the end-to-end tests.
Architecture shows how they fit together.
The repository
| Path | Holds |
|---|---|
contracts/ | core/ (DAOFactory, DAOGovernor, DAOTreasury, ShareToken, DAOPolicy, DAOProfile, PolicyBuilder), cipnft/ (CipherVault), tokens/ (DAOToken, TokenLauncher, MemberDistributor), descifi/ (DeSciFiFactory, DeSciFiPair, DeSciFiRouter, LockFactory and LockBox), storage/ (TextStore, CollabKeyring), lens/ (DAOLens, MarketLens), interfaces/, utils/ (Utf8, Png, StoredBytes) |
test/ | the Foundry suite: unit and integration tests, invariants/, audit/ (the reviews' proof-of-concept tests), mocks/, utils/ |
script/ | Deploy.s.sol (every network), SeedDemo.s.sol (local demo data), integrations.json (the default GL1F collections and CIPNFT contracts on chain 29), assets/ (the demo DAOs' logos) |
externals/ | pinned copies of the GenesisL1 contracts COLLAB integrates with (CIPNFT, GL1F, GL1F Crypto): src/ and their compiled bin/ |
lib/ | OpenZeppelin Contracts and Contracts Upgradeable 5.1.0, Solady 0.1.26, forge-std 1.9.4 |
abi/ | one ABI file per contract, exported from the build, for integrators |
web/ | the app; The web app is its reference |
server/ | install.sh, admin/collab_admin.py, the nginx/ templates, the systemd/ units, bin/collab (the helper) and tests/ |
deploy/ | nginx and Caddy configurations for hosting without the server kit, sync_csp.py, check_site.py |
tools/ | the Python tooling, with e2e/ (browser tests), seo/ (the prerender's modules) and tests/ |
docs/ | this documentation, as Markdown; the page registry is in tools/build_docs.py |
deployments/ | deployment records, one per chain id (29.json for GenesisL1, once COLLAB is deployed there; 2.2.0 ships none), and, never released, the local chain's files |
At the top: foundry.toml, remappings.txt, README.md, LICENSE and THIRD_PARTY_NOTICES.md.
The toolchain
| Part | Tools |
|---|---|
| Contracts | Foundry (forge, cast, anvil) with solc 0.8.28, via-IR, optimizer 200 runs, EVM istanbul (no PUSH0, MCOPY or transient storage), IPFS metadata hash. remappings.txt is the only remapping source (auto_detect_remappings = false), so the trimmed libraries of the release archive compile to the same bytecode, metadata included |
| Offline builds | forge build --offline --use /path/to/solc-0.8.28; the release build passes FORGE_FLAGS to every forge call |
| Upstream contracts | solc 0.8.20 with their own settings, only when they change (tools/build_externals.py) |
| Tooling | Python 3.10 or later: the standard library, plus Pillow for images and pycryptodome (or OpenSSL 3.2 or later) for keccak-256 in the prerender. The admin service and the config writer use the standard library only. Building a release needs Python 3.11.4 or later (Building a release) |
| Browser tests | Playwright for Python with Chromium |
| Server | bash, apt, nginx, certbot, systemd, OpenSSL |
| Browser libraries | committed files with their version in the name: ethers 6.17.0, markdown-it 14.1.0, libsodium.js 0.8.2, mlkem-wasm 0.0.7 |
There is no Node.js anywhere: no npm, no bundler, no transpiler, no package to install for the site. Local development has the installation commands.
Memory notes
- A first
forge buildof everything compiles with via-IR in one solc run, which can need more than 5 GB of memory. Build the contracts first (forge build --skip test --skip script), then a few test files perforge buildcall; that stays well under 2 GB and gives the same artifacts.tools/build_release.pycompiles in batches of four files (FORGE_BATCH). forge testafter the batched builds needs no further compilation.- The end-to-end runner starts one Chromium and opens a context per browser; on a small machine, run one suite at a time.
- A sandbox is one anvil and one Python dev server; stop yours when you are done (
dev_sandbox.py down).
Where to start
| You want to | Read | Then |
|---|---|---|
| understand the system | Architecture | Contracts guide |
| run it on your machine | Local development | The web app |
| change a contract | Contracts guide, Governance internals | the tests in test/, the Gas reference, then the exporters (tools/export_abis.py, tools/abi_summary.py, tools/export_deploy_artifacts.py) |
| add a proposal builder | The web app | contracts/core/PolicyBuilder.sol, Governance internals |
| change a page or a view | The web app | python3 tools/lint_web.py, the suite of that area in Testing |
| read COLLAB from your own code | Reading COLLAB from the chain | Data formats, abi/, Contract API reference |
| work on the server kit | Admin API reference, Data formats | Installing COLLAB on a server, server/tests/ |
| write or run tests | Testing | Local development |
| cut a release | Building a release | Release notes |
| write documentation | The web app | python3 tools/build_docs.py --check |
The project's rules
- No Node.js anywhere in what COLLAB builds or ships.
- Every source file starts with the licence line
MIT License. Copyright (c) 2026 Decentralized Science Labs LLC., in the comment form of its language; Solidity files use// SPDX-License-Identifier: MITand a copyright line instead (The web app gives each form). Vendored files keep their own.tools/lint_web.pychecksweb/andtools/. - No new third-party code without a licence check, recorded in
THIRD_PARTY_NOTICES.md. python3 tools/lint_web.pyreports 0 errors, and every generated file is current (its--check).- Releases ship as one
.tar.gzarchive with checksums. - Security statements stay honest: the reviews are AI-assisted and done apart from the implementation, and there has been no external audit.
Licences
COLLAB, its contracts, the web app, the server kit, the tools and this documentation, is open source under the MIT License, copyright 2026 Decentralized Science Labs LLC (LICENSE). The third-party parts keep their own licences:
| Component | Licence |
|---|---|
| OpenZeppelin Contracts 5.1.0 and Contracts Upgradeable 5.1.0, Solady 0.1.26 | MIT |
| forge-std 1.9.4 (tests and scripts only) | MIT or Apache-2.0 |
| ethers.js 6.17.0, markdown-it 14.1.0 (with its bundled libraries; entities is BSD-2-Clause) | MIT |
| libsodium.js 0.8.2 | ISC |
| mlkem-wasm 0.0.7 (mlkem-native: Apache-2.0 OR ISC OR MIT) | MIT |
| Inter, JetBrains Mono, Source Serif 4 | SIL Open Font License 1.1 |
the CIPNFT, GL1F and GL1F Crypto contracts in externals/ | MIT, Decentralized Science Labs |
THIRD_PARTY_NOTICES.md lists each with its version, where it lives and its licence file; Licence and third-party code summarises them.
Related
- Architecture: the system in one page.
- Local development: set up your machine.
- Contracts guide: the Solidity side.
- The web app: the browser side.
- Testing: the suites and checks.