Proof-of-Commitment Monorepo

Conviction-weighted staking, governance, and analytics for DAOs that want provable commitment and revenue-backed deflation in one stack.

---

Table of Contents

1. Overview
2. Repository Layout
3. Core Features
4. Architecture
5. Smart Contracts
6. Frontend dApp
7. SDK
8. Getting Started
9. Useful Commands
10. Deployment Snapshot
11. Testing & Security
12. Roadmap
13. Resources

---

Overview

• Problem: Inflationary staking, flash-loan votes, and transferable governance tokens make DAO treasuries fragile.
• Approach: Combine time-locked staking, non-transferable NFTs, and fee-funded burns to reward conviction instead of capital churn.
• Outcome: A reproducible toolkit (contracts + Next.js dApp + SDK) that ships conviction-weighted governance and deflationary tokenomics.

---

Repository Layout

Package	Description	Key Tech
contracts/	Hardhat project with staking, NFT, and governance contracts plus deployment + verification scripts.	Solidity, Hardhat, OpenZeppelin 5.0
client/	Next.js 14 dApp covering staking, governance, portfolio, and admin flows.	Next.js App Router, Tailwind, viem/ethers v5
sdk/	Published npm package for integrating Proof-of-Commitment mechanics in other dApps.	TypeScript, viem

Supporting deep dives live in PROBLEM_IT_SOLVES.md, CHALLENGES.md, and FRONTEND_SDK_GUIDE.md.

---

Core Features

• Conviction-weighted governance: Voting power = stake × tier multiplier (Bronze 1.0x → Diamond 2.0x) with proposal snapshots and vote locks.
• Revenue-funded deflation: 0.5% stake, 1% unstake, 1% claim fees flow to a DAO-controlled treasury for buyback-and-burn.
• Proof-of-Commitment NFTs: Soulbound ERC721s store lock terms, tier data, and on-chain SVG progress arcs.
• SDK-first distribution: @proof-of-commitment/sdk exposes staking, governance, analytics, and NFT helpers for external builders.

---

Architecture

Wallets ↔ Next.js frontend ↔ Proof-of-Commitment SDK ↔ Lisk Sepolia smart contracts
                                                      ↘ On-chain data → analytics consumers

Contracts, frontend, and SDK stay decoupled but share JSON deployment artifacts and TypeScript typings for a single source of truth.

---

Smart Contracts

• StakingProtocol.sol: Handles deposits, fee accounting, penalty curves, treasury counters, and voting power math; emits analytics events.
• StakingNFT.sol: Mints non-transferable NFTs per stake, records immutable lock metadata, and renders tier-specific SVGs entirely on-chain.
• DAOGovernance.sol: Snapshot-based Governor with quorum/threshold tuning, active vote locks, and a 2-day timelock for executions.
• MockStakingToken.sol: Faucet ERC20 used on Lisk Sepolia; interchangeable with production tokens via IStakingProtocol boundaries.

Deployment flow: token → NFT → protocol(token, NFT) → governance(protocol) → transfer ownership + wire DAO permissions. Scripts inside contracts/scripts/ automate the sequence and persist JSON under contracts/deployments/ for the frontend and SDK.

---

Frontend dApp

• Built with Next.js App Router + Tailwind; routes live under client/app/.
• Key pages:
  • /stake: lock slider (7–365 days) with live tier + voting power preview and fee breakdowns.
  • /portfolio: stake inventory, emergency exit, tier upgrades, and treasury metrics.
  • /governance: proposal board, vote casting, vote-lock messaging, and execution queue.
  • /admin: owner-only console for treasury stats, fee knobs, and buyback/burn actions.
• Hooks in client/lib/hooks wrap wallet state, staking flows, and governance interactions using the SDK contracts + viem clients.

---

SDK

Install with:

npm install @proof-of-commitment/sdk viem

• staking: allowance helpers, stake/unstake flows, treasury stats, tier math utilities.
• governance: proposal CRUD, vote casting, quorum + threshold lookups, execution helpers.
• analytics: per-user and protocol aggregations for dashboards.
• nft: metadata decoding, tier lifecycle helpers, SVG utilities.

Published package docs live on npm and mirror the repository source under sdk/src/.

---

Getting Started

Prerequisites

• Node.js 18+
• pnpm or npm (project scripts assume npm, but pnpm works with minor adjustments)
• Foundry/Hardhat toolchain dependencies (solc, git, etc.)
• Optional: LISK_API_KEY for explorer verification

Setup

1. Clone: git clone https://github.com/<org>/proof-of-commitment.git && cd proof-of-commitment
2. Install dependencies:
   • cd contracts && npm install
   • cd ../client && npm install
   • cd ../sdk && npm install
3. Environment variables: copy contracts/.env.example → contracts/.env and set PRIVATE_KEY (plus optional LISK_API_KEY). Frontend uses the deployment JSON inside client/lib/contracts/.
4. Run dev workflows:
   • Contracts: npm run test or npx hardhat test
   • Frontend: npm run dev
   • SDK: npm run build

---

Useful Commands

Context	Command	Notes
Contracts	npx hardhat test	Runs all 155 specs + revenue-model suites.
Contracts	npx hardhat run scripts/deploy.ts --network liskSepolia	Deploys token → NFT → protocol → governance.
Contracts	npx hardhat run scripts/verify-contracts.ts --network liskSepolia	Verifies via Blockscout (needs LISK_API_KEY).
Frontend	npm run dev	Next.js dev server on http://localhost:3000.
SDK	npm run build	Bundles via tsup before publishing.

For publishing the SDK: cd sdk && npm publish --access public once tests/builds pass.

---

Deployment Snapshot

Network:        Lisk Sepolia (Chain ID 4202)
RPC:            https://rpc.sepolia-api.lisk.com
Explorer:       https://sepolia-blockscout.lisk.com
Date:           2026-01-09

Staking Token:    0x02C067e213c686E4A6423ED3D42b07569F0BA498
Staking Protocol: 0x4f0a02b3A21DDb5e8F90E973c472eB7542c59567
Staking NFT:      0x260f59feCe5356946ef1BDe9e94c2d1Fa8E31847
DAO Governance:   0x16237118dBBb2cB4A3C9f4a970C571467bc1def1
Owner/Deployer:   0xF93E7518F79C2E1978D6862Dbf161270040e623E

All deployments are mirrored under contracts/deployments/ with constructor args for reproducibility.

---

Testing & Security

• 155/155 Hardhat tests (including 20 revenue-model specs) plus live-network smoke tests.
• OpenZeppelin 5.0 primitives, ReentrancyGuard on all state changes, SafeERC20 transfers.
• DAO-controlled knobs gated by setDAOGovernance, with fee caps (stake ≤2%, unstake/claim ≤3%) and penalty floors in storage.
• Frontend guardrails: owner-only admin route, allowance + fee sanity checks, automatic Lisk Sepolia prompts.

---

Roadmap

1. Analytics dashboards: Ship SDK-powered treasury, burn, and voting visualizations directly inside the dApp.
2. Governance kit: Typed proposal builders + execution recipes in the SDK.
3. Lisk mainnet launch: Harden deployment scripts, complete audits, and wire multi-sig control.
4. Starter template: Publish a Next.js + SDK boilerplate for DAOs to fork.
5. Treasury safety nets: Integrate MPC/multi-sig tooling and policy change watchers.

---

Resources

• Docs: PROBLEM_IT_SOLVES.md · CHALLENGES.md · FRONTEND_SDK_GUIDE.md
• npm: https://www.npmjs.com/package/@proof-of-commitment/sdk
• Explorer: https://sepolia-blockscout.lisk.com
• Questions: open a GitHub discussion or issue in this repo.

Built for the Lisk Hackathon — time-weighted conviction, deflationary economics, and community-led governance in one stack.