Time-Weighted Commitment Protocol

A Solana primitive that rewards conviction through time-weighted, burn-to-participate positions.

Overview • How It Works • Use Cases • Getting Started • Architecture

---

Ackee Blockchain Security — Solana Bootcamp Final Project

This protocol was developed as a capstone project for the Ackee Blockchain Security Solana Bootcamp. It is not production-ready — use at your own risk. The codebase includes 34 test scenarios covering core functionality, with Trident fuzz testing coming soon.

Demo App	Test Suite

---

Overview

In crypto, participants increasingly prioritize short-term speculation over sustained commitment. TWCP flips the incentive: the longer you hold before committing, the greater your share of rewards.

This is not staking. It's not LP shares. It's closer to:

"Aging tickets that accumulate weight over time. When you burn them to commit, your weight determines your allocation—patience and belief are rewarded."

Each deployment creates a distinct market with its own token, resolution logic, and reward policy. Whether you're building a lottery, a game, a contest, or a fundraising mechanism—TWCP provides the base layer.

---

How It Works

┌─────────────────────────────────────────────────────────────────────────────┐
│                              EPOCH LIFECYCLE                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│   1. MINT              2. HOLD & AGE           3. COMMIT           4. WIN   │
│   ──────────           ─────────────           ────────            ───────  │
│   Pay tokens to        Weight grows            Burn position       Winners  │
│   mint positions       over time               into a pool         claim    │
│                                                                    rewards  │
│   [Position]  ───────► [Weight: 5.2] ────────► [Pool #2] ────────► [Claim]  │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

1. Positions

Users pay tokens to mint positions—irreversible, time-amplified commitment tickets:

• Non-refundable: Cannot be redeemed back
• Non-transferable: No secondary market by default
• Time-weighted: Weight grows with age
• Consumable: Burned on commitment (one use only)

Weight Formula (TimeBased model):

weight = (age_seconds × numerator × 10,000) / denominator

Example: 10 weight per 5 minutes
- After 300s: weight = 10.0
- After 150s: weight = 5.0
- Minimum: always 1.0 (prevents gaming)

2. Pools & Epochs

Pools are commitment targets inside each epoch—they can represent lottery entries, game teams, contest submissions, or any discrete bucket.

• Epochs run for a configurable duration (60 seconds to days)
• Users commit positions to pools before the deadline
• One pool is selected as winner via resolution
• Winners claim rewards proportional to their weight

3. Resolution

Resolution determines how winners are selected:

Type	Description	Best For
Admin	Designated resolver picks the winner	Curated contests, early-stage testing
Oracle (VRF)	Cryptographic randomness via Magic Block	Lotteries, provably fair games

---

Use Cases

TWCP is a primitive—plug it into different mechanisms:

Application	How It Works
Lotteries	Longer holders get more tickets, VRF picks winner
Games / Competitions	Teams accumulate time-weighted support, winner takes pool
Conviction ICOs	Early believers get larger allocations (planned)
Fundraising	Time-weighted participation in token sales (planned)

---

Getting Started

Prerequisites

• Rust
• Solana CLI
• Anchor 0.31.1
• Node.js 18+

Quick Start

# Clone and install
git clone https://github.com/your-repo/twcp.git
cd twcp
yarn install

# Build
anchor build

# Test (34 tests)
anchor test

# Deploy to localnet
yarn faucet:deploy:localnet
yarn deploy:localnet --mint=<MINT> --resolver=<RESOLVER>

Running the Demo App

cd app
yarn install
yarn dev

Visit http://localhost:3000 to interact with the protocol.

---

Architecture

twcp/
├── programs/
│   ├── twcp-protocol/     # Main protocol
│   └── faucet/            # Testnet token faucet
├── app/                   # Next.js demo frontend
├── tests/                 # 34 test cases
├── scripts/               # Deployment & admin tools
└── deployments/           # Network-specific configs

Core Accounts

Account	Purpose
Config	Protocol settings, current epoch, mint
Position	User's time-weighted ticket
Pool	Commitment target per epoch
Commitment	User's burned position in a pool
EpochResult	Resolution outcome, winning pool
Treasury	Accumulated position payments

Configuration

Parameter	Description
weight_model	TimeBased (weight grows) or Constant
resolution_type	Admin or Oracle (VRF)
epoch_duration	Seconds per round
position_price	Cost to mint one position
weight_rate	How fast weight accumulates

---

Security

• Epoch Deadline Enforcement: No commits after resolution
• Minimum Weight: Always ≥ 1.0 to prevent gaming
• Resolver Authorization: Only designated address can resolve
• VRF Verification: Oracle randomness is cryptographically verified
• Checked Arithmetic: Prevents overflow via u128 intermediates

---

Documentation

• DEPLOYMENT.md — Deployment guide
• ARCHITECTURE.md — Technical deep-dive
• scripts/README.md — Operational commands

---

License

MIT — see LICENSE