ContractLedger

CONTRACTLEDGER
Player Delivery Contracts | Carrier Reputation | Insured Shipments

Build a complete player-driven logistics economy with delivery contracts, named destinations, carrier progression, custom deadlines, insurance tiers, and staff dispute tools.

What is ContractLedger?

ContractLedger turns Minecraft trading into a freight and delivery system. Players create contracts for items they want transported, carriers accept those jobs, and the plugin manages payments, bonds, deadlines, insurance, history, and reputation.

Core idea:

Requesters create item delivery jobs from anywhere
Carriers register, accept contracts, deliver cargo, and earn money
Vault handles payments automatically
Carrier reputation, levels, stats, achievements, and streaks create long-term progression
Insurance tiers and bonds protect valuable shipments
Admins can resolve disputes when staff review is needed

Why Choose ContractLedger?

Safe Player Trading
Payments are held by the contract flow, carrier bonds discourage abandonment, and insurance can compensate requesters when deliveries fail.

Player-Driven Economy
Players set rewards, choose destinations, accept jobs, build reputation, and compete as trusted carriers.

Advanced Carrier Progression
Carriers progress through Bronze, Silver, Gold, Platinum, and Diamond levels, unlock achievements, build delivery streaks, and track detailed statistics.

Flexible Risk Management
Per-contract deadlines, late penalties, insurance tiers, carrier bonds, cooldowns, and admin dispute resolution give server owners real control.

Highly Configurable
Gameplay settings are in a fully commented config.yml. Player-facing text is separated into messages.yml.

How It Works

1. Register a Destination

Place a sign at a delivery location
Look at the sign and run: /cl destination register spawn
Players can now create contracts to spawn from anywhere

2. Create a Contract

Hold the cargo item in your hand
Create a normal contract: /cl delivery create 500 spawn
Create a custom deadline contract: /cl delivery create 500 spawn 4
Create an insured contract: /cl delivery create 500 spawn 4 premium
Items are stored, money is deducted, and a visual delivery zone appears

3. Carrier Accepts

Carrier registers with /cl carrier register
Carrier browses jobs with /cl delivery list
Carrier accepts with /cl delivery accept <id>
Cargo is given to carrier, bond is charged, and deadline starts

4. Delivery or Dispute

Carrier travels to the marked destination zone
Delivery is completed with /cl delivery deliver <id>
If something goes wrong, requester or carrier can open a dispute

5. Payment and Reputation

On-time delivery pays full reward and returns bond
Late delivery applies a configurable penalty
Failed delivery can trigger insurance payout and carrier cooldown
Carrier stats, rating, levels, streaks, and achievements update automatically

Core Features

Visual Delivery Zones

Named destination registry
Remote contract creation by destination name
Gold block/sign marker and configurable colored floor area
Protected signs and delivery-zone blocks
Automatic zone restoration on completion, cancel, or failure

Contract System

Create contracts with rewards, destinations, optional custom deadlines, and optional insurance tiers
Browse open contracts with item, reward, destination, deadline, and insurance information
Accept, deliver, cancel, track, and inspect contracts
Complete event history for auditing
Statuses include Open, Accepted, In Transit, Completed, Late, Failed, Expired, Cancelled, and Disputed

Deadline and Penalty System

Default deadline configured by server owner
Optional per-contract deadline in hours
Minimum and maximum custom deadline limits
Late reward penalty paid back to requester
Automatic expiration checks for active contracts

Insurance and Bonds

Insurance tiers: none, basic, standard, premium
Each tier has configurable fee percent, payout percent, max payout, and bond percent
Carrier bond can scale with insured value
Automatic insurance payout on failed contracts
Protects requesters while keeping carriers accountable

Dispute Resolution

Players can open disputes with /cl dispute open <id> <reason>
Admins can resolve disputes as requester, carrier, split, cancel, or fail
Disputed contracts are locked from normal completion/cancel flow until resolved
All dispute actions are logged in contract history

Advanced Carrier System

Carrier registration and profiles
5 levels: Bronze, Silver, Gold, Platinum, Diamond
4 specializations: Fast, Valuable, Long Distance, Bulk
14 achievements
Current and best delivery streaks
Failure cooldown system
Detailed stats: success rate, total earned, distance, late/failed counts, average rating
Top carrier leaderboard

Configuration and Messages

Fully commented config.yml for gameplay/system settings
Separate messages.yml for player-facing text
Automatic backup to config.yml.old and messages.yml.old when templates change
Old matching values are preserved during upgrade
/cl reload reloads both settings and messages

Economy Integration

Vault support
Works with compatible economy plugins
Automatic balance checks, withdrawals, deposits, rewards, penalties, bonds, and insurance payouts

Commands

Player Commands

Code:

/cl help - Show commands
/cl delivery create <reward> <destination> [hours] [insuranceTier] - Create a delivery contract
/cl delivery list - Browse open contracts
/cl delivery accept <id> - Accept a contract
/cl delivery deliver <id> - Complete delivery
/cl delivery cancel <id> - Cancel your open contract
/cl dispute open <id> <reason> - Open a contract dispute
/cl destination register <name> - Register a destination sign
/cl destination list - List destinations
/cl carrier register - Register as carrier
/cl carrier profile [player] - View carrier profile
/cl carrier top - View leaderboard
/cl carrier level - View level progress
/cl carrier stats [player] - View detailed stats
/cl carrier achievements - View achievements
/cl carrier specialize [type] - Choose specialization
/cl contract <id> - View contract details
/cl track <id> - Track contract status

Admin Commands

Code:

/cl reload - Reload config.yml and messages.yml
/cl destination unregister <name> - Remove destination
/cl admin info <id> - View full contract details and events
/cl admin cancel <id> - Force cancel contract
/cl admin fail <id> - Force fail contract
/cl admin dispute <id> requester|carrier|split|cancel|fail [note] - Resolve dispute

Permissions

Player Permissions

Code:

contractledger.use - Basic plugin access
contractledger.delivery.create - Create delivery contracts
contractledger.delivery.accept - Accept contracts
contractledger.delivery.cancel - Cancel own contracts
contractledger.dispute.open - Open disputes
contractledger.destination.register - Register destinations
contractledger.carrier.register - Register as carrier
contractledger.carrier.profile - View carrier profiles
contractledger.contract.view - View contract details and tracking

Admin Permissions

Code:

contractledger.admin - Access admin actions
contractledger.destination.unregister - Remove destinations

Example Scenario

Steve wants to send diamonds from his base to spawn with premium protection.

Admin registers spawn: /cl destination register spawn
Steve holds diamonds and creates: /cl delivery create 500 spawn 4 premium
The plugin stores the diamonds, charges reward plus insurance fee, and creates a delivery zone at spawn
Alex registers as carrier: /cl carrier register
Alex accepts the job: /cl delivery accept 1
Alex receives the cargo and pays the required bond
Alex delivers at spawn: /cl delivery deliver 1
If on time, Alex gets reward plus bond back and improves reputation
If something goes wrong, either party can open a dispute for admin resolution

Upgrade Notes

Current version: 0.3.0
Requires Java 21+
Compatible with Spigot/Paper 1.21+
Requires Vault and a compatible economy plugin for economy features
SQLite storage is used in this version
Database migrations run automatically
Old config values are preserved when matching keys still exist

Roadmap

Current Version 0.3.0 - Deadline & Insurance Expansion

Per-contract deadline customization
Advanced insurance tiers
Dispute resolution tools
Separated config.yml and messages.yml

Version 0.4.0 - GUI System

Graphical contract browser
Visual contract creation and management
Better carrier/requester workflows

Version 0.5.0 - Delivery Points and Warehouses

Delivery hubs
Warehouse-style logistics
Expanded destination management

Give your players a safer, deeper, and more competitive logistics economy.

Version: 0.3.0 | Compatibility: Spigot/Paper 1.21+ | Dependencies: Vault + Economy Plugin

ContractLedger v0.3.0

Overview Dependencies Updates (2) History