Documentation Support Contact

Documentation v19

Everything you need to integrate with and operate the AquaDoneRite platform.

Introduction

AquaDoneRite is a blockchain-based digital ledger system for water rights administration under Colorado's Prior Appropriation doctrine. The platform represents water shares as Non-Fungible Tokens (NFTs) on a private Avalanche subnet, providing immutable records, transparent ownership, and unified billing across consecutive water systems.

For Ditch Companies

Digitize share records, automate assessments, and provide shareholders 24/7 access to their holdings.

For Shareholders

View holdings, track subdivisions, verify ownership chain, and manage billing from any device.

For Developers

RESTful API with traditional authentication, no blockchain knowledge required for integrations.

Quick Start Guide

Get up and running with AquaDoneRite in minutes. This guide walks through the essential steps for each user role.

Platform Access

AquaDoneRite uses traditional email/password authentication. No cryptocurrency wallet is required for standard operations—the platform handles all blockchain interactions behind the scenes.

Create Your Account

Visit the AquaDoneRite portal and sign up with your email address. You'll receive a verification email to confirm your account.

Join Your Organization

Enter the invitation code provided by your ditch company administrator, or request access through the portal.

Verify Your Holdings

Once approved, your water shares will appear in your dashboard. Verify that the priority dates, share amounts, and beneficial use types match your records.

Set Up Billing

Link your water shares to a billing account to receive invoices and track payments. You can manage multiple shares from a single account.

Core Concepts

Water Share NFTs

Each water share in AquaDoneRite is represented as a Non-Fungible Token (NFT) on the blockchain. The NFT contains all legally relevant attributes of the water right:

Attribute Description
priorityDate The adjudication date establishing seniority (YYYYMMDD format)
beneficialUse Irrigation, Municipal, Domestic, or Industrial
shareUnits Fractional ownership (e.g., 125 units = 1/8 share of 1000 total)
pointOfDiversion Structure ID, coordinates, and source water body
status ACTIVE, SUSPENDED, SUBDIVIDED, ABANDONED, or IN_ADJUDICATION

Share Subdivision

Water shares can be subdivided into smaller fractional interests. When a share is subdivided:

  • The parent share is marked SUBDIVIDED and becomes non-transferable
  • Child tokens are created with proportional share units
  • The sum of child units must equal the parent's units (conservation enforced)
  • Complete lineage is tracked through unlimited generations
Example: Municipal Subdivision

A town holding a 1/8 share (125 units) can subdivide it into: Parks (31 units), Fire Dept (31 units), Pool (63 units). The parent becomes non-transferable while children operate independently.

Consecutive Water Systems

Many water distributions flow through multiple organizational boundaries. AquaDoneRite tracks these "consecutive" systems, maintaining parent/child relationships and enabling unified billing and reporting across the entire chain.

User Roles

Role Capabilities
ADMIN Full system access, user management, court order execution
DITCH_COMPANY Mint shares, manage company records, authorize shareholders
WATER_COMMISSIONER Record usage, update share status, abandonment determinations
BILLING_OPERATOR Manage accounts, issue invoices, process payments
SHAREHOLDER View holdings, transfer shares, manage billing account

Ditch Company Admin Guide

DITCH_COMPANY This guide covers common tasks for ditch company administrators.

Registering Your Company

Before minting water shares, your ditch company must be registered in the system:

Submit Registration Request

Provide your company's legal name, state registration number, total share units, water division (1-7), and authorized administrator contact.

Verification

AquaDoneRite staff will verify your registration with the Colorado Division of Water Resources.

Authorization

Once verified, you'll receive credentials to access the ditch company dashboard and begin minting shares.

Minting Water Shares

To digitize existing water shares as NFTs:

API Request: Mint Water Share
POST /api/v1/shares/mint

{
  "ditchCompanyId": 1,
  "recipientEmail": "[email protected]",
  "decree": {
    "caseNumber": "W-1234-78",
    "adjudicationDate": "1978-06-15",
    "priorityDate": "1892-04-01",
    "division": 4
  },
  "beneficialUse": "IRRIGATION",
  "shareUnits": 125,
  "pointOfDiversion": {
    "structureId": "NFDC-HG-007",
    "latitude": 38.8697,
    "longitude": -107.5925,
    "sourceWater": "North Fork Gunnison River"
  }
}
Scarcity Enforcement

You cannot mint more share units than your company's registered total. The system tracks mintedUnitsByCompany and will reject requests that exceed capacity.

Publishing Assessment Rates

Annual assessments can be published through the rate schedule system, enabling automated billing calculations for all shareholders.

Shareholder Guide

SHAREHOLDER This guide covers viewing and managing your water share holdings.

Viewing Your Holdings

Your dashboard displays all water shares associated with your account, including:

  • Share amount and units
  • Priority date and seniority ranking
  • Beneficial use type
  • Current status
  • Complete transfer history
  • Usage records (if available)

Transferring Shares

To transfer a water share to another party:

Initiate Transfer

Select the share and enter the recipient's email address. They must have an AquaDoneRite account.

Confirm Details

Review the transfer details including any associated documentation (sale agreement, gift declaration, etc.).

Execute Transfer

The transfer is recorded on the blockchain with a permanent timestamp. Both parties receive confirmation.

Water Court Approval

Some transfers may require water court approval depending on the change of use or location. AquaDoneRite records the transfer but does not replace the legal approval process.

Subdividing Shares

If you need to split a share among multiple recipients or allocations:

API Request: Subdivide Share
POST /api/v1/shares/{tokenId}/subdivide

{
  "children": [
    { "shareUnits": 31, "recipientEmail": "[email protected]" },
    { "shareUnits": 31, "recipientEmail": "[email protected]" },
    { "shareUnits": 63, "recipientEmail": "[email protected]" }
  ]
}

The sum of child units must equal the parent's units exactly.

Meter Operator Guide

SYSTEM_OPERATOR This guide covers recording meter readings and usage data.

Mobile App Access

Meter operators use a streamlined mobile app to record readings in the field. The app works offline and syncs when connectivity is available.

Recording a Meter Reading

Select System

Choose the consecutive water system from your assigned list. You can only submit readings for systems you're authorized to operate.

Enter Reading

Input the meter reading value and optionally attach a photo for verification.

Submit

The reading is validated and recorded on the blockchain. A confirmation with timestamp is displayed.

POST /api/v1/systems/{systemId}/readings 
{
  "readingValue": 12847.5,
  "readingDate": "2026-01-15T10:30:00Z",
  "meterSerial": "WM-2024-0892",
  "notes": "Meter access clear, no issues"
}

Billing Operator Guide

BILLING_OPERATOR This guide covers account management, invoicing, and payment processing.

Creating Billing Accounts

Each shareholder needs a billing account to receive invoices. Accounts can hold multiple water share tokens.

Issuing Invoices

POST /api/v1/billing/invoices 
{
  "accountId": 42,
  "dueDate": "2026-02-15",
  "lineItems": [
    {
      "tokenId": 1001,
      "description": "Annual Assessment - 2026",
      "quantity": 125,
      "unitPrice": 1200,
      "totalAmount": 150000
    }
  ]
}

Processing Payments

Payments can be recorded for various payment types: Cash, Check, ACH, Credit Card, or Credit Applied. Overpayments are automatically applied to the account's credit balance.

Collections Workflow

Accounts with overdue invoices can be flagged for collections. The system tracks overdue amounts across all invoices and supports paginated processing for high-volume operations.

API Overview

The AquaDoneRite API provides RESTful access to all platform functionality. The API layer runs on Cloudflare Workers, handling authentication and translating requests to blockchain operations.

Base URL

https://api.aquadonerite.com/v1

Response Format

All responses are JSON with consistent structure:

{
  "success": true,
  "data": { ... },
  "meta": {
    "timestamp": "2026-01-15T14:30:00Z",
    "requestId": "req_abc123"
  }
}

Error Responses

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN_STATUS",
    "message": "Token is SUBDIVIDED and cannot be transferred",
    "details": { "tokenId": 1001, "status": "SUBDIVIDED" }
  }
}

Rate Limits

Tier Requests/min Burst
Standard 60 100
Enterprise 600 1000

Authentication

AquaDoneRite uses JWT (JSON Web Token) authentication. No cryptocurrency wallet is required.

Obtaining a Token

POST /auth/login 
{
  "email": "[email protected]",
  "password": "your-password"
}

Response:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 3600
  }
}

Using the Token

Include the access token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Refreshing Tokens

POST /auth/refresh

Water Shares API

List Shares

GET /shares

Returns all shares accessible to the authenticated user. Supports pagination.

Get Share Details

GET /shares/{tokenId}

Get Transfer History

GET /shares/{tokenId}/transfers

Query params: page, limit (default 50, max 100)

Transfer Share

POST /shares/{tokenId}/transfer

Subdivide Share

POST /shares/{tokenId}/subdivide

Billing Accounts API

Create Account

POST /billing/accounts

Get Account Summary

GET /billing/accounts/{accountId}/summary

List Invoices

GET /billing/accounts/{accountId}/invoices

Record Payment

POST /billing/invoices/{invoiceId}/payments

Usage & Metering API

Record Meter Reading

POST /systems/{systemId}/readings

Get Usage History

GET /shares/{tokenId}/usage

Record Usage (Water Commissioner)

POST /shares/{tokenId}/usage

WaterShareNFT Contract

The core ERC-721 contract implementing water share tokens with Colorado water law-specific extensions.

Key Functions

Function Role Required Description
mintWaterShare() DITCH_COMPANY Create new water share NFT
subdivideShare() Token Owner Split share into child tokens
recordUsage() WATER_COMMISSIONER Record beneficial use
courtOrderTransfer() ADMIN Force transfer per court order
updateShareStatus() ADMIN Change share status

Events

event WaterShareMinted(uint256 indexed tokenId, uint256 indexed ditchCompanyId, address indexed owner, uint32 priorityDate, BeneficialUseType beneficialUse);
event WaterShareSubdivided(uint256 indexed parentTokenId, uint256[] childTokenIds, address indexed owner);
event ShareStatusChanged(uint256 indexed tokenId, ShareStatus oldStatus, ShareStatus newStatus, string reason);
event CourtOrderExecuted(uint256 indexed tokenId, string orderType, string caseNumber, address executedBy);

DitchCompanyRegistry Contract

Registry of authorized ditch companies that can mint and manage water shares.

Key Functions

Function Role Required Description
registerDitchCompany() REGISTRAR Add new ditch company
authorizeAddress() Company Admin Authorize wallet for minting
verifyAuthorization() Public Check if address can mint for company

ConsecutiveSystemRegistry Contract

Tracks downstream water systems and their relationships to source ditches.

Key Functions

Function Role Required Description
registerSystem() REGISTRAR Register new consecutive system
setParentSystem() ADMIN Establish parent/child relationship
recordMeterReading() SYSTEM_OPERATOR Submit meter reading

BillingAndUsage Contract

Comprehensive billing, invoicing, and payment management.

Key Functions

Function Role Required Description
createAccount() BILLING_OPERATOR Create billing account
issueInvoice() BILLING_OPERATOR Issue new invoice
recordPayment() PAYMENT_PROCESSOR Record payment receipt
applyCredits() BILLING_OPERATOR Apply credit balance to invoice

Invoice Lifecycle

ISSUED → DUE → OVERDUE → COLLECTIONS
   ↓                         ↓
PARTIALLY_PAID ←──────── PAID

Glossary

Abandonment

Loss of a water right through non-use. Colorado law creates a rebuttable presumption of abandonment after 10 years of non-use (C.R.S. 37-92-402).

Adjudication

The water court process establishing the priority date, amount, source, and conditions of a water right decree.

Beneficial Use

The legal requirement that water must be put to a recognized productive purpose—agricultural, municipal, domestic, or industrial.

Consecutive Water System

A downstream water distribution system receiving water from an upstream municipal or ditch system.

Ditch Company Share

An ownership interest in a mutual ditch company representing a portion of water flowing through the system.

Point of Diversion

The physical location (headgate, pump, intake) where water is diverted from its source.

Prior Appropriation

Colorado's water allocation system: "first in time, first in right." Senior water rights holders have priority during shortages.

Priority Date

The date water was first put to beneficial use, establishing seniority among water rights.

Senior/Junior Rights

Water rights ranked by priority date. During shortages, senior (older) rights are fulfilled before junior (newer) rights.

Frequently Asked Questions

Do I need a cryptocurrency wallet to use AquaDoneRite?

No. AquaDoneRite uses traditional email/password authentication. The platform handles all blockchain interactions behind the scenes. Advanced users can optionally connect a wallet for direct blockchain access.

Is my water share ownership legally valid on the blockchain?

AquaDoneRite provides a digital record of ownership that can be used as evidence in legal proceedings, but it does not replace the official records maintained by the Colorado Division of Water Resources or the water court system. Think of it as a highly reliable, tamper-proof ledger that complements existing legal infrastructure.

What happens if I lose access to my account?

Contact your ditch company administrator or AquaDoneRite support. Account recovery follows standard identity verification procedures. Your water shares remain safe on the blockchain regardless of account access issues.

Can I transfer shares to someone outside the system?

The recipient must have an AquaDoneRite account to receive transfers. You can invite them to create an account, which takes only a few minutes.

How are priority dates validated?

Priority dates are entered based on official adjudication documents. The system supports historical dates back to the 1850s when Colorado water rights were first established.

What blockchain does AquaDoneRite use?

AquaDoneRite runs on a private Avalanche Subnet—a dedicated blockchain with controlled validators, low transaction costs, and high throughput. This provides the security and immutability of blockchain technology while keeping water rights data within a permissioned environment appropriate for legal records.