Commit Protocol
Optimistic Agentic Settlement for On-Chain Work Commitments with Discord Integration
Complete Technical Specification v2.0
Overview
What is Commit Protocol?
Commit Protocol is a trustless escrow system for work commitments that combines:
Problem Statement
Solution
Discord Integration
Registration Flow
Balance Management
Each Discord server has a prepaid MNEE balance tracked on-chain:
| Field | Description |
|---|---|
| totalDeposited | Lifetime MNEE deposited (never decreases) |
| totalSpent | Lifetime MNEE spent on commitments |
| availableBalance | Current spendable balance |
Invariant: availableBalance = totalDeposited - totalSpent
Role-Based Access Control
The protocol uses Discord roles verified off-chain by the bot:
Registered during server registration. Can deposit/withdraw MNEE balance.
Configured in Discord server settings. Can create commitments using server balance. Bot verifies role before contract call.
Any Discord user with linked wallet. Can submit work and receive payments.
Core Concepts
The protocol is built on four foundational principles:
Prepaid Escrow
Servers fund a balance upfront. Commitments deduct from this pool, eliminating per-transaction approvals.
Optimistic Settlement
Work is assumed valid unless disputed. Auto-settles after deadline + dispute window.
Relayer Pattern
Bot wallet is the sole caller. Verifies Discord permissions off-chain, executes on-chain.
Dynamic Stakes
Dispute costs scale with task value and participant reputation. Fair for all sizes.
Smart Contract Specification
Data Structures
ServerData
uint256 guildId
uint256 adminDiscordId
bool isActive
uint256 registeredAt
uint256 totalDeposited
uint256 totalSpent
uint256 availableBalance
CommitmentData
address creator // relayer
address contributor
address token
uint256 amount
uint256 deadline
uint256 disputeWindow
string specCid
string evidenceCid
State state
uint256 createdAt
uint256 submittedAt
Core Interface
SERVER MANAGEMENT
registerServer(uint256 _guildId, uint256 _adminDiscordId)
depositToServer(uint256 _guildId, uint256 _amount)
withdrawFromServer(uint256 _guildId, address _to, uint256 _amount)
COMMITMENT LIFECYCLE
createCommitment(guildId, contributor, token, amount, deadline, disputeWindow, specCid)
submitWork(uint256 _guildId, uint256 _commitId, string _evidenceCid)
openDispute(uint256 _guildId, uint256 _commitId)
SETTLEMENT (RELAYER ONLY)
settle(uint256 _commitId)
batchSettle(uint256[] _commitIds)
ARBITRATION
resolveDispute(uint256 _commitId, bool _favorContributor)
Key Events
ServerRegistered(guildId, adminDiscordId)ServerDeposited(guildId, amount, newBalance)ServerWithdrew(guildId, to, amount)CommitmentCreated(commitId, creator, contributor, ...)WorkSubmitted(commitId, evidenceCid, timestamp)CommitmentSettled(commitId, recipient, amount)Commitment Lifecycle
State Machine
[*] → FUNDED createCommitment()
FUNDED → SUBMITTED submitWork()
SUBMITTED → DISPUTED openDispute() [within window]
SUBMITTED → SETTLED batchSettle() [after window]
DISPUTED → SETTLED resolveDispute(CONTRIBUTOR)
DISPUTED → REFUNDED resolveDispute(CREATOR)
State Definitions
| State | Description | Trigger |
|---|---|---|
| FUNDED | MNEE deducted from server balance, commitment created | Relayer (via bot) |
| SUBMITTED | Contributor submitted work + evidence CID | Relayer (via bot) |
| DISPUTED | Creator opened dispute with required stake | Relayer (via bot) |
| SETTLED | Funds released to contributor | Cron job |
| REFUNDED | Funds returned to server balance | Arbitrator |
Note: CREATED state is unused — commitments are FUNDED immediately upon creation.
Economic Model
Fee Structure
*Deducted from pre-funded server balance
Dispute Stakes
Loser forfeits stake to winning party
Security Model
Data Flow
User → /command → Bot
Bot → Check Role → Discord API
Discord → Role OK → Bot
Bot → Sign TX → Relayer Wallet
Relayer → Call → Smart Contract
Trust Assumptions
Bot private key is secure
The relayer wallet key is the root of trust. It's the only way to call contract.
Discord API correctly reports roles
We trust Discord to accurately report user identities and role memberships.
Contract trusts relayer
All calls from the relayer address are treated as pre-verified for permissions.
Security Guarantees
Deployment Guide
Prerequisites
Local Deployment (Anvil Fork)
# Start Anvil with mainnet fork
./scripts/start-anvil.sh
# Fund test wallet with MNEE
./scripts/fund-test-wallet.sh 10000 0xf39F...266
# Deploy contract
forge script script/DeployLocal.s.sol:DeployLocal \
--rpc-url http://localhost:8545 --broadcast
# Set relayer (bot wallet)
cast send $CONTRACT "setRelayer(address)" $BOT_WALLET \
--rpc-url http://localhost:8545 --private-key $KEY
Mainnet Deployment
# Configure .env
ETH_MAINNET_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/KEY
PRIVATE_KEY=0x...
ARBITRATOR_ADDRESS=0x...
# Deploy and verify
forge script script/Deploy.s.sol:DeployMainnet \
--rpc-url $ETH_MAINNET_RPC_URL \
--broadcast --verify \
--etherscan-api-key $ETHERSCAN_API_KEY
Testing
# Run all tests
forge test -vv
# Specific test
forge test --match-test testRegisterServer -vvvv
# Gas report
forge test --gas-report
Test Coverage
Built With