Halal (HLC)

Halal is a DAO-governed, CPI-indexed stablecoin protocol. HLC minted through its Peg Stability Module (PSM) is redeemable against a reserve ERC-20, chosen per deployment, at a CPI-adjusted rate; the goal is for HLC's purchasing power, not just its nominal reserve-asset price, to stay roughly stable. The separate fixed genesis allocation (6,000,000 HLC to the team and 4,000,000 HLC to the treasury, both time-vested) is not reserve-backed. PSM issuance, protocol parameters, and treasury spending are controlled by an on-chain DAO (OpenZeppelin Governor + TimelockController) once the system is fully deployed and handed off — there is no unilateral admin key in that final state.

This is a genuine, from-scratch implementation, not a fork or a wrapper: five immutable core contracts (HalalToken, HalalVesting, HalalPSM, HalalDAO, HalalTimelock), an optional signed CPI adapter, a Foundry test suite, and a Next.js frontend, all in this monorepo.

The fastest way to see the complete system is ./scripts/local-demo.sh: it starts a disposable Anvil chain, deploys the wired contracts, seeds a fresh local CPI report, and opens the frontend with a faucet-backed local reserve. No external RPC key or real funds are needed for the demo.

If the protocol idea or the engineering work is useful to you, consider starring the repository and forking it to experiment or contribute.

Contribute

Start with the good first issues:

• Run ./scripts/local-demo.sh to see the contracts and dApp together.
• Follow the local development walkthrough from a clean checkout.
• Use the local-demo troubleshooting guide if a prerequisite, port, or stale local configuration blocks the demo.
• Review the proposed CPI source-policy record (based on the template) documenting the reporting trust boundary: source series, publisher identity, cadence, freshness, fallback, updater custody, and incident response. This record is a proposal under review, not production approval.
• Run make verify before opening a pull request.
• Pick an unclaimed task from the live good first issues filter. These are deliberately bounded and need no wallet, private key, RPC credential, deployment, or real funds. The contributor map describes the current ones in more detail.
• Comment on the issue with your intended approach before opening a pull request, so two people do not build the same thing.
• Help coordinate the first carefully gated Arbitrum Sepolia deployment.
• Review the bounded security challenge or production CPI adapter design.
• Use Discussions for design questions.
• Report security vulnerabilities through SECURITY.md, not a public issue.

Why this project is interesting

Most stablecoins target a nominal unit of a reserve asset. Halal explores a different target: keeping HLC's reserve-asset redemption rate moving with consumer-price inflation, so one HLC is intended to represent roughly stable purchasing power over time. That idea is paired with a conservative accounting model:

• Only reserve deposited through the PSM creates a redeemable HLC claim; the fixed team and treasury allocations are explicitly separate and not reserve-backed.
• CPI updates are bounded by absolute limits, per-update movement, cadence, report freshness, and the reserve held for outstanding claims.
• Governance is delayed and observable: protocol roles route through an OpenZeppelin Governor and TimelockController, while deployment tooling verifies chain identity and final role wiring.

Proof at a glance

Reviewer question	Evidence in this repository
Does the accounting have stateful coverage?	214 Foundry tests, including 16 PSM invariants, differential arithmetic checks, and fuzzing
Do invariants cover CPI changes?	docs/INVARIANTS.md models governance rate changes and reserve top-ups
Can a deployment be checked without a private key?	scripts/verify-deployment.sh
Can registry readiness be checked offline?	scripts/preflight-deployment.mjs or make deployment-preflight (no RPC, signing, or writes)
Can I inspect the full system locally?	./scripts/local-demo.sh on a disposable Anvil chain
Can I exercise the signed CPI adapter locally?	make adapter-demo, a disposable 31337-only two-of-two report rehearsal; included in make verify and hosted CI
Does the PSM fail closed on missing or stale CPI data?	HalalPSM rejects deposits until isCPIReportFresh() is true; the dApp mirrors the gate
Can an operator audit a deployment without a wallet?	scripts/check-deployment-health.sh combines wiring and PSM health checks
Can I model CPI-driven reserve needs reproducibly?	docs/ECONOMIC-MODEL.md and make economic-model
Can I reproduce an official CPI report payload?	scripts/parse-bls-cpi.mjs and docs/CPI-ADAPTER-SPEC.md
Can I verify a report before submitting it?	scripts/verify-cpi-report.mjs checks live adapter/PSM CPI state, watermarks, and freshness, then recovers each EIP-712 signer without private keys
Does governance decode CPI adapter actions?	The dApp includes the generated CPIReportAdapter ABI for signer, threshold, ownership, and report actions
Can the active CPI signer set be audited?	CPIReportAdapter.getSigners() and check-psm-health.sh expose the current addresses after each rotation
Does the dApp show adapter custody state?	The dashboard and PSM page show the live adapter owner, source ID, quorum, signers, and last submitted report
Does the dApp verify adapter/PSM report alignment?	It compares the adapter's submitted CPI and report watermark with the PSM and flags divergence
Can an operator inspect deployment health without a wallet?	The read-only /health page checks contract wiring, CPI freshness, reserve coverage, and adapter alignment
Does the dApp expose deployment evidence?	The dashboard shows the registry's deployment transaction, verified-source, and deployment-journal links when they are published
Can I inspect the CPI timeline?	The dashboard reads recent CPIUpdated events with block, transaction, source, and rate-change context
Are public deployment addresses reviewable?	docs/DEPLOYMENT-REGISTRY.md and the checked-in registry
Are generated frontend interfaces kept in sync?	ABI regeneration is a required CI check
Does CI exercise a configured dApp?	scripts/local-app-smoke.sh deploys disposable Anvil state, builds with live addresses, and checks the main routes
Is the CI supply chain independently scored?	The pinned-action Scorecard workflow publishes OpenSSF SARIF results
What static-analysis scope has been checked?	docs/STATIC-ANALYSIS.md records the pinned Slither command, source scope, and interpretation
Can a permit-capable wallet approve and act in one transaction?	HalalPSM exposes bounded EIP-2612 paths for deposits, withdrawals, redeemable-credit transfers, and claim retirement
Does the dApp expose permit transfers?	The redeemable-credit form offers “Sign & transfer in one transaction” with approval fallback
Does the dApp expose permit claim retirement?	The same form offers selector-gated “Sign & retire claim” while preserving the approval fallback
Does the dApp expose permit withdrawals?	The swap form detects the deployed PSM selector and offers signed HLC withdrawal with approval fallback
Are release sources checksummed and attestable?	Release artifacts publishes a reproducible source bundle, SHA-256 checksum, and build-provenance attestation
Is the security posture stated plainly?	SECURITY.md and docs/THREAT-MODEL.md
Is the production CPI integration boundary defined?	docs/CPI-ADAPTER-SPEC.md and issue #17
Is CPI source policy recorded separately from on-chain checks?	docs/CPI-SOURCE-POLICY-TEMPLATE.md
Can a reviewer trace a CPI report from source publication to PSM acceptance?	docs/CPI-ADAPTER-SPEC.md includes the submission sequence and evidence map

The project is still unaudited and not production-ready. The table is evidence of engineering discipline, not a safety guarantee.

Status & risk

This protocol has not undergone a professional security audit, and there is no bug bounty program yet. The contracts pass their own test suite (214/214 at the time of writing — 198 unit and configuration tests plus 16 stateful invariants; see contracts/test/), but a passing test suite is not a substitute for an audit, and this repo should not be treated as safe to use with real, meaningful funds. If you deploy or interact with any instance of these contracts, you do so at your own risk. See SECURITY.md for the responsible-disclosure process if you find a vulnerability, and please don't treat anything in this README, or in docs/, as a claim that the software is production-ready — it's an active, unaudited, open-source project, and honesty about that is a design goal in its own right.

What happens next

Two things gate everything else, and neither is waiting on more code:

1. An independent security review (issue #126). The contracts are immutable by design, so review has to precede any deployment that matters.
2. The first Arbitrum Sepolia reference deployment (issue #40), which needs a documented reserve token, multisig beneficiaries, and a named CPI updater operator before it can proceed.

docs/NEXT-STEPS.md has the full current-state view: what is blocked on what, the highest-value bounded tasks, and the known CI failure modes that are not caused by your change.

Architecture, briefly

• HalalToken (HLC) — ERC20Votes + ERC20Permit + AccessControl. Genesis 6M/4M team/treasury allocation minted once via initialMint; all further minting requires MINTER_ROLE, while accounting-aware burns require BURNER_ROLE; the DAO grants those roles narrowly (initially to the PSM, and to future modules only by case-by-case vote).
• HalalVesting — one instance per beneficiary (team, treasury), linear vesting with an optional cliff; the team schedule is DAO-revocable, the treasury schedule is not.
• HalalPSM — mints/burns HLC against a reserve asset at a CPI-adjusted rate; CPI is submitted by a rate-limited UPDATER_ROLE (intended to be a Chainlink Functions consumer or similar in production) with a DAO-gated manual override for emergencies.
• CPIReportAdapter — optional EIP-712 quorum module that authenticates signed reports before forwarding them to the PSM; it is unaudited and does not authenticate the underlying statistics agency by itself.
• HalalDAO — an OpenZeppelin Governor (settings + simple counting + votes + quorum fraction + timelock control) wired to HLC's vote-weight and to HalalTimelock.
• HalalTimelock — a standard TimelockController enforcing an execution delay between a passed proposal and its effects taking place.

For the full picture — diagrams, the access-control matrix, a worked governance-proposal walkthrough, and the exact API surface — see:

• docs/ — the documentation index, grouped by what you are trying to do: understand the protocol, run it locally, contribute, review its security, choose a reserve asset, govern it, or operate a deployment.
• docs/WHITEPAPER.md — the protocol whitepaper: the problem, the CPI-peg mechanism and its settlement arithmetic, the bounds and guards that constrain it, tokenomics, governance, the security model and what it does not cover, prior art, and an honest risks section. Start here to understand why the system is shaped the way it is.
• docs/Architecture.md — system diagrams and contract call flow.
• docs/TECHNICAL-DOCS.md — the fullest spec: deployment steps, governance parameters, API reference, security notes.
• docs/DAO-Guide.md — governance walkthrough (proposal lifecycle, .env setup, troubleshooting).
• docs/Treasury.md — how vesting/treasury flows work in practice.
• docs/AddingFeature.md — the pattern for adding new functionality to the already-deployed, non-upgradeable system (new contract + DAO-granted role, not a patch to existing contracts).
• docs/DESIGN-DECISIONS.md — where the actual implementation deliberately deviates from those planning docs, and why. Worth reading before assuming a number or behavior described in the docs above is exactly what the code does.
• docs/THREAT-MODEL.md — assets, trust boundaries, attack scenarios, mitigations, and unresolved risks for reviewers and deployment operators.
• docs/SECURITY-REVIEW-QUICKSTART.md — reproducible security-review commands, bounded review questions, evidence expectations, and safe reporting.
• docs/OPERATOR-RUNBOOK.md — launch acceptance, monitoring, CPI updater operations, governance review, and incident response.
• scripts/verify-governance-payload.mjs — offline, fail-closed preflight for exact governance targets, values, selectors, and calldata.
• docs/INVARIANTS.md — the stateful PSM properties exercised by Foundry and the exact scope of those guarantees.
• docs/ECONOMIC-MODEL.md — a dependency-free CPI and reserve-adequacy scenario model with machine-readable output.
• docs/DEPLOYMENT-REGISTRY.md — how operators publish verified deployment addresses without copying unverified values into a frontend environment.
• docs/DEPLOYMENT-JOURNAL-TEMPLATE.md — a copyable evidence record joining deployment, reserve, CPI, health, monitoring, and final decision review.
• docs/INCIDENT-TABLETOP-WORKSHEET.md — a safe rehearsal worksheet for operational failures and recovery evidence.
• docs/CONTRIBUTOR-MAP.md — concrete contribution paths for security, oracle integrations, monitoring, economics, governance, dApp UX, and documentation.
• docs/GLOSSARY.md — concise definitions of the protocol terms used by the contracts, documentation, and contributor issues.
• docs/LOCAL-CPI-REPORT-WALKTHROUGH.md — copy-paste local CPI report preparation and verification lifecycle.
• Security review challenge #16 — a bounded starting point for independent PSM and CPI review.
• docs/ROADMAP.md — the risk-ordered path from unaudited reference implementation to independently reviewed testnet and production readiness.

Those docs describe design intent and were written to guide the implementation; a few figures in them are approximate/aspirational rather than exact. contracts/src/ is the ground truth for anything you need to be precise about (role names, parameter bounds, function signatures) — read the NatSpec comments there, they're kept accurate and up to date.

Repository layout

contracts/   Foundry Solidity project — five core contracts plus CPIReportAdapter,
             tests, deploy/example scripts.
app/         Next.js frontend dApp.
docs/        Design and governance documentation (see above).

Quickstart

From the repository root, make verify runs the full contract and frontend verification suite, including a configured production dApp smoke test on disposable Anvil state. The individual commands below are useful when working on one subtree.

Contracts

cd contracts
forge install     # fetch git-submodule dependencies (forge-std, OpenZeppelin Contracts)
forge test        # run the full test suite

To run the complete dApp locally against Anvil with one command:

./scripts/local-demo.sh

The wrapper starts a disposable Anvil chain, deploys the system, writes app/.env.local, and starts the frontend. The local deployment uses a faucet reserve token intentionally named mDAI; it must never be used as a real reserve asset on a public network. For manual deployment or a custom local beneficiary, see contracts/script/DeployLocal.s.sol.

See contracts/script/Deploy.s.sol for the deployment script, contracts/script/Examples.s.sol for example governance proposals, and contracts/script/PrepareCPIAdapterHandoff.s.sol for reviewed CPI adapter handoff calldata. For a read-only proposal preflight, run node scripts/verify-governance-payload.mjs --bundle <bundle.json> --policy <policy.json>. Read docs/DAO-Guide.md and docs/TECHNICAL-DOCS.md for the full deployment walkthrough and required environment variables.

Frontend

cd app
pnpm install
pnpm dev          # local dev server

Run pnpm build to produce a production build.

When a deployment is configured, the dApp supports wallet-free read-only browsing. Set NEXT_PUBLIC_READ_CHAIN_ID if several deployments are configured; connect a wallet only when you want to approve transactions, swap, vote, or use another signing action.

Contributing

Contributions are welcome — bug fixes, tests, documentation, and (after a discussion in an issue first) new features. See CONTRIBUTING.md for the fork/branch/PR workflow, how to run each subtree's tests, code style, and commit conventions. Changes to contracts/src/ get extra scrutiny given this is a live financial protocol — see the note in CONTRIBUTING.md about that specifically. Please also read CODE_OF_CONDUCT.md.

Security

Found a vulnerability, especially one that could put funds at risk? Please do not open a public issue — see SECURITY.md for the private responsible-disclosure process, scope, and what response times to expect.

License

MIT — see LICENSE.

If this project contributes to research or another open-source project, see CITATION.cff for citation metadata.