1. Introduction

1.1 Purpose & Scope

This document defines the functional specifications for Exonomy, a decentralized peer-to-peer platform enabling users ("Exonomists") to mint, manage, and exchange vouchers tied to real-world currencies. The platform leverages NextGraph as its core communication infrastructure, ensuring offline-first operations, selective data replication, and decentralized governance. Key components include:

NextGraph-based peer-to-peer architecture for resilient, serverless communication.
Voucher lifecycle management, including creation, exchange, and redemption.
Exocracy integration for community-driven project management.
Trust metrics and decentralized governance mechanisms.

1.2 Key Objectives

Decentralized Infrastructure: Utilize NextGraph’s CRDT-driven synchronization and selective replication to eliminate dependency on central servers.
Local-First Resilience: Ensure uninterrupted voucher transactions and community governance workflows, even in offline or low-connectivity environments.
Trust-Driven Interactions: Implement reputation systems and unanimous consent mechanisms for secure, community-auditable transactions.
Scalable Replication: Restrict data sharing to transaction-relevant parties or followed users, minimizing resource overhead.
Fiat Integration: Bridge traditional payment processors with decentralized voucher exchanges via NextGraph’s event-driven workflows.

1.3 Definitions & Acronyms

NextGraph: Decentralized communication infrastructure for CRDT synchronization, selective replication, and peer-to-peer data exchange.
Exonomist: A user participating in voucher issuance, trading, or governance.
CRDTs: Conflict-free replicated data types enabling seamless offline/online state merging.
Exocracy: Community governance module for collaborative project management.
Capability Token: Cryptographic token granting permission to access or replicate specific data.
Voucher: A digital token representing a real-world currency value or service obligation.

2. System Architecture

2.1 Core Components & Principles

The platform’s architecture is built on NextGraph, a decentralized communication framework enabling offline-first operations, peer-to-peer data synchronization, and selective replication. Key components include:

Decentralized Communication Layer:
- NextGraph brokers direct peer-to-peer interactions, eliminating reliance on central servers.
- Supports offline operations via CRDT-based conflict resolution and eventual consistency.
Local-First Repositories:
- Each Exonomist maintains a personal repository synchronized across devices via NextGraph’s CRDT engine.
- Data modifications (e.g., voucher creation) are stored locally and propagated to relevant peers.
Selective Replication:
- Data is shared only when explicitly required (e.g., during transactions, follows, or governance votes).
- Replication rules are enforced cryptographically through capability tokens.
Decentralized Governance:
- Critical actions (e.g., transaction approvals, dispute resolutions) require consensus via NextGraph-hosted WASM smart contracts.

2.2 Data Structures & Semantic Modeling

Voucher Metadata:
- Vouchers are modeled as semantic entities with machine-readable attributes (currency, amount, issuer, expiry).
- NextGraph ensures metadata integrity through cryptographically signed provenance logs.
Decentralized Indexing:
- Public voucher feeds are indexed using NextGraph’s lightweight querying capabilities, enabling efficient discovery without full replication.
- Search and filtering operate over minimal metadata subsets, preserving privacy.
Provenance Tracking:
- All voucher state transitions (e.g., pending → completed) are immutably logged and synchronized via NextGraph.

2.3 Replication Controls & Selective Sharing

Capability Tokens:
- Generated during transaction initiation to grant time-bound, permissioned access to voucher details.
- Tokens are cryptographically bound to specific peers and actions (e.g., read, approve).
Replication Triggers:
- Follows: NextGraph replicates public voucher feeds from followed users to the follower’s repository.
- Transactions: Voucher data is shared only with transaction participants, minimizing network overhead.
- Governance Votes: Data required for consensus (e.g., dispute evidence) is replicated to voting members.
Encryption & Privacy:
- Sensitive data (e.g., voucher terms) is encrypted end-to-end, with keys managed via NextGraph’s secure channel protocols.

2.4 WASM-Based Smart Contracts

Functionality:
- Hosted and executed within NextGraph’s decentralized environment.
- Govern voucher lifecycle transitions (e.g., escrow, redemption) and community governance workflows.
Consensus Enforcement:
- Unanimous consent or threshold-based approvals are enforced via smart contract logic.
- Contract execution outcomes are immutably recorded and synchronized across repositories.
Upgradability:
- Contracts are versioned and updated via community governance proposals, with changes propagated through NextGraph.

3. Voucher Management

Vouchers are the core economic and social unit of Exonomy, functioning as both tradable value tokens and interactive social media artifacts. This section defines their lifecycle, social features, and transactional mechanics.

3.1 Core Features

Voucher Creation:
- Exonomists mint vouchers with defined attributes: currency, amount, expiry, and optional multimedia descriptions.
- Creators retain ownership until explicit transfer.
Social Feed Integration:
- Vouchers are published to the creator’s External Feed, visible to followers or the broader network.
- Feed entries include metadata (currency, amount, expiry) and social interactions (likes, comments, shares).
Ownership Transfer:
- Vouchers transition between users via peer-to-peer transactions, with state changes (e.g., listed → pending → completed) enforced by smart contracts.

3.2 Lifecycle Management

States:
- Draft: Privately editable by the creator.
- Listed: Published to feeds, available for exchange.
- Pending: Locked in escrow during negotiation or payment.
- Completed: Ownership transferred and value redeemed.
- Expired: No longer redeemable.
Redemption:
- Redeemers validate fulfillment of the voucher’s value (goods/services) through cryptographic confirmation.
- Partial redemptions are supported, with proportional value adjustments.

3.3 Social Interaction & Moderation

Chat-Based Negotiation:
- Each voucher hosts a dedicated chat room for offers, counteroffers, and terms negotiation.
- Partial Payments: Buyers propose composite offers (e.g., 60% cash, 40% barter), which creators accept or reject.
- Dynamic Pricing: Creators adjust voucher prices in response to demand or offers.
Moderation Controls:
- The voucher owner acts as Master of Ceremonies (MC), moderating chat access, delegating moderation rights, and configuring features:
  - Enable/disable invitations, partial payments, or price adjustments.
  - Restrict chat visibility using one-way mirrors (e.g., hiding selected participants).

3.4 Transaction Mechanics

Barter & Hybrid Exchanges:
- Vouchers can be traded for other vouchers, cash, or mixed-value offers.
- Composite transactions split ownership proportionally among contributors.
Discount Mechanisms:
- When a creator accepts a discounted price, the system auto-generates a supplementary voucher for the difference (e.g., a $100 voucher sold for $80 creates a $20 “discount voucher”).

3.5 Decentralized Moderation

Fraud Mitigation:
- Disputed vouchers enter escrow, with evidence replicated to arbitrators via NextGraph.
- Resolutions require unanimous consent from arbitrators or pre-defined consensus thresholds.
Reputation Impact:
- Failed redemptions or disputes negatively affect issuer/buyer reputation scores.

3.6 Payment Processor Integration

Fiat Transactions:
- Cash payments via Stripe, PayPal, or similar processors trigger voucher state transitions (e.g., pending → completed).
- Funds are held in escrow until redemption is confirmed.
Selective Replication:
- Payment metadata (e.g., transaction IDs) is stored only in the repositories of involved parties.

4. Exocracy Module Specifications

Exocracy enables decentralized communities to collaboratively manage projects funded by vouchers. It introduces governance structures, task hierarchies, and collective decision-making while leveraging NextGraph for replication and consensus.

4.1 Core Components

Project Creation:
- Projects are initiated by defining a goal (e.g., “Build a community garden”) and binding it to vouchers representing funding or resources.
- Projects exist as standalone entities but inherit voucher attributes (currency, amount, expiry).
Task Hierarchies:
- Projects are decomposed into parent/child tasks (e.g., “Source materials” → “Purchase lumber”).
- Each task is assigned a voucher value, automatically aggregated upward to parent tasks.
Selective Replication:
- Project data (tasks, votes, progress) is replicated only to participating members via NextGraph, minimizing overhead.

4.2 Task Management

Crowdfunding & Exocrat Selection

Conditional Credit Attachment:
- Exonomists attach vouchers to any task in the hierarchy as conditional credit, which is claimable only if the task is completed satisfactorily.
- Vouchers remain in their owners’ repositories but are cryptographically “locked” to the task via smart contracts.
Exocrat Discovery & Compensation:
- Search Filters: Exocrats query tasks using criteria:
  - Task/voucher descriptions (semantic keyword matching).
  - Task value, crowdfunding progress (%), currency.
  - GPS proximity (for location-bound tasks).
  - Owner/exocrat reputation scores.
  - Deadline urgency (time-to-expiry of linked vouchers).
- Compensation Bundling:
  - Exocrats propose combinations of attached vouchers that meet their compensation requirements (e.g., “$500 USD = 20 x 1h vouchers for carpentry work @$20/h + 10 x 1 Pizza vouchers @$10 each”).
  - They may attach a voucher wish list (e.g., a tip request in the form of a list of additional vouchers”) for optional fulfillment.
Approval & Consensus:
- The Project Manager (PM) reviews the Exocrat’s offer, approving/declining based on the best interest of the community and the feasibility of the Exocrat's offer.
- Approved offers trigger a community smart contract that:
  - Freezes the selected vouchers.
  - Requires unanimous consensus from voucher owners to finalize the allocation.
  - Releases funds only upon task completion (via redemption proofs).
Overfunding & Voucher Release:
- Tasks can be overfunded (e.g., 150% of target value) to signal community priority.
- Exocrats claim compensation only up to the task’s declared value; excess vouchers are automatically released to owners upon completion.
- Overfunded tasks allow Exocrats to request “tips” from the surplus via wish lists, subject to owner approval.
Task Nomination & Acceptance:
- Exocrats can self-nominate or be invited via sharing personalized nomination invitations.
- Acceptance enrolls the Exocrat in the task’s community, granting them governance rights and replication access.

4.3 Community Governance

Decision-Making:
- Unanimous Consent: Critical actions (e.g., finalizing task completion) require approval from all stakeholders.
- Threshold Voting: Non-critical decisions (e.g., task prioritization) use majority or supermajority thresholds.
Reputation Systems:
- Contributors: Earn reputation by funding tasks or providing resources.
- Exocrats: Earn reputation by delivering tasks on time/budget.
- Reputation scores influence voting weight and task eligibility.
Dispute Resolution:
- Disputed task outcomes trigger evidence replication to arbitrators via NextGraph.
- Resolutions are enforced by smart contract-mediated voucher redistributions.

4.4 Integration with Voucher Management

Voucher Binding:
- Existing vouchers can be linked to tasks as funding sources or deliverables.
- New vouchers are auto-generated to represent task-specific obligations (e.g., “Deliver 50kg cement by 10/31”).
Lifecycle Synchronization:
- Task progress (e.g., 50% completion) triggers proportional updates to linked vouchers (e.g., partial redemption).
- Voucher expiries enforce task deadlines, with auto-escalation to governance if breached.

4.5 Scalable Governance Structures

Delegated Roles

Facilitator:
- Mediates consensus-building for contentious decisions (e.g., disputed task completion).
- Manages replication of evidence and voting workflows via NextGraph.
Liaison:
- Coordinates cross-community collaboration (e.g., shared resources between projects).
- Maintains replication rules for nested communities.
Compliance Officer:
- Ensures task/voucher terms align with jurisdictional regulations (e.g., labor laws).
- Audits smart contracts for legal adherence.

Modular Expansion

Hierarchical Relationships:
- 2D Nesting: Communities, projects, and tasks exist in a recursive hierarchy:
  - Communities → Projects → Tasks → Subtasks.
  - Tasks can belong to multiple parent projects (e.g., a “soil testing” task shared across “Community Garden” and “Park Renovation”).
- Iterative Definition:
  - Tasks define parents through replication rules (e.g., a subtask inherits governance structures from its parent project).
  - Communities are dynamically defined by their constituent projects’ replication groups.
Cross-Community Collaboration:
- Shared tasks replicate data selectively across communities via capability tokens.
- Governance decisions (e.g., budget approvals) propagate upward/downward based on smart contract rules.

Key Mechanics

Unselected Voucher Release: Vouchers not chosen by Exocrats remain attached to tasks until completion, after which they are automatically unlocked.
Decentralized Persistence: Task hierarchies and governance roles are replicated only to relevant participants via NextGraph, minimizing storage overhead.

Addenda

Understanding the Escrow Workflow

To ensure secure, decentralized escrow management for fiat transactions (e.g., Stripe, PayPal), the following approach is proposed, leveraging NextGraph’s infrastructure and smart contracts, replacing reliance with leverage, with respect to centralized intermediaries. Exonomy's serverless, trust-minimized design design both complies with and embraces financial regulations:

Transaction Initiation:
- When a buyer initiates a cash payment (e.g., via Stripe), the payment processor’s API places funds into a preconfigured escrow account (managed by the processor, not Exonomy).
- A smart contract is instantiated on NextGraph, binding the voucher’s unique ID, buyer/seller identities, payment amount, and redemption criteria.
Voucher State Transition:
- The voucher enters a pending state, cryptographically locked to prevent double-spending.
- The smart contract records the escrow trigger event and replicates this state to all relevant parties via NextGraph.
Redemption Confirmation:
- Upon voucher redemption, the seller submits cryptographic proof (e.g., a signed confirmation from the buyer or IoT device verification of service completion).
- The smart contract validates the proof against predefined criteria (e.g., buyer’s digital signature, expiration timestamp).
Funds Release:
- If validation succeeds:
  - The smart contract triggers a release instruction to the payment processor’s API, transferring funds from escrow to the seller.
  - The voucher transitions to completed, with its ownership history updated and replicated.
- If validation fails (or disputes arise):
  - The smart contract initiates a dispute resolution workflow, freezing funds until community arbitrators reach consensus (see Section 5: Governance).

Key Design Principles

No Custodial Risk:
- Exonomy never holds funds directly. Escrow accounts are managed by licensed third-party processors (Stripe, PayPal), ensuring regulatory compliance.
- Smart contracts only enforce rules for fund release, not custody.
Decentralized Enforcement:
- Escrow logic is codified in WASM-based smart contracts, executed across NextGraph nodes for tamper-proof governance.
- All escrow events (triggers, releases, disputes) are immutably logged and replicated.
Redemption Proof Flexibility:
- Proof mechanisms are configurable:
  - Manual Confirmation: Buyer/seller digitally sign redemption approval.
  - Automated Verification: IoT sensors or API calls confirm service delivery (e.g., GPS tracking for physical goods).
Partial Redemptions:
- For partially redeemed vouchers, the escrow releases funds proportionally (e.g., 50% payment for 50% redemption).

Dispute Resolution

Escalation: Disputed transactions trigger replication of evidence (chat logs, voucher terms) to pre-selected arbitrators via NextGraph.
Arbitrator Selection: Reputation-weighted community members are assigned dynamically, minimizing collusion risk.
Binding Outcomes: Arbitrators vote via smart contract, with outcomes enforced by payment processor APIs.

Integration with Payment Processors

APIs: Exonomy interfaces with processor-specific escrow APIs (e.g., Stripe’s Payment Intents) to:
- Initiate holds on funds.
- Release/refund based on smart contract directives.
Compliance: Processors handle KYC/AML, while Exonomy’s contracts enforce transactional logic.

Not all payment processors support escrow accounts

— Escrow support varies by processor.

Processor	Native Escrow Support?	Workaround
Stripe	Yes (Payment Intents)	Use Stripe’s `capture: false` to authorize funds, releasing them only after smart contract validation.
PayPal	Yes (Adaptive Payments)	Use PayPal’s `PAYMENT.SALE` API with `pending` status, completing the sale post-redemption.
Wise	No	Use third-party escrow services (e.g., Escrow.com) or smart contract-managed wallets (e.g., stablecoin reserves) to hold funds.
Venmo	No	Rely on manual buyer/seller agreements or integrate third-party escrow APIs.
Google Pay/Apple Pay	No	Use Stripe/PayPal escrow behind the scenes (e.g., process Google Pay through Stripe’s Payment Intents).
AliPay	Limited	Use AliPay’s trade assurance program (for cross-border transactions) or third-party escrow.
Revolut	No	Smart contracts hold funds in Revolut sub-accounts, releasing via API only after redemption confirmation.
MetaMask/Crypto	Yes (via smart contracts)	Funds held in smart contract wallets (e.g., conditional multi-sig), released programmatically.

Key Insight:

Processors with escrow APIs (Stripe, PayPal, crypto) integrate natively.
Others require third-party escrow services or smart contract-managed wallets.

Linking Smart Contracts to Payment Processor Status IDs

Mechanism:

Transaction ID Binding:
- When initiating a payment (e.g., Stripe), the processor returns a unique transaction ID (e.g., Stripe payment_intent_id).
- This ID is embedded in the smart contract’s metadata and replicated via NextGraph.
Event Listening:
- Smart contracts subscribe to payment processor webhooks (e.g., Stripe’s payment_intent.succeeded).
- Webhook payloads include the transaction ID, allowing the contract to match events to voucher states.
State Synchronization:
- Example workflow:
  - Contract A (voucher ID 123) references Stripe ID pi_XYZ.
  - When Stripe sends a webhook for pi_XYZ, the contract validates it against its stored ID and updates the voucher state.

Technical Implementation:

Smart Contract Metadata:
{
  voucher_id: "123",
  payment_processor: "stripe",
  transaction_id: "pi_XYZ",
  escrow_status: "pending"
}

Partial Redemptions & Proportional Escrow

Workflow:

Voucher Splitting:
- A $100 voucher can be split into sub-vouchers (e.g., $40 + $60) via smart contract logic.
Escrow Allocation:
- If a buyer pays $40 for a partial redemption:
  - The $40 is held in escrow (via processor APIs).
  - A sub-voucher for $60 remains in the seller’s repository.
Redemption Triggers:
- For the $40 portion:
  - Upon redemption proof (e.g., partial delivery), the smart contract instructs the processor to release $40.
  - The sub-voucher is marked partially_redeemed.
Audit Trails:
- All partial transactions are logged in the voucher’s ownership history, ensuring transparency.

Example:

A $100 plumbing service voucher is sold for $80 (buyer pays $60 cash, $20 in barter).
- $60 cash → held in Stripe escrow.
- $20 barter → held as a separate voucher.
- After partial service (e.g., 50% completion), $30 is released, and the barter voucher is split proportionally.

Key Considerations

Regulatory Compliance:
- Third-party escrow services (e.g., Escrow.com) handle compliance for non-native processors like Wise/Venmo.
User Experience:
- Automate proportional splits via smart contracts to avoid manual calculations.
Dispute Handling:
- Partial disputes (e.g., 30% of a voucher) require granular arbitration workflows (see Section 5).

exonomyapp/Functional Specification for the Exonomy App - Updated.md