Predictive Liquidity Markets Operational Specification

1. Executive Summary

This document resolves six open operational questions that remained after the Predictive Liquidity Markets implementation specification was finalized. The PLM implementation spec defined the core architecture - predictive models, liquidity pool management, tax-aware optimization, and calendar-driven obligation forecasting - but intentionally deferred several policy-level decisions requiring cross-team alignment.

The six questions addressed here are: (1) minimum transaction history required for accurate predictions, (2) handling prediction failures and graceful degradation, (3) multi-jurisdiction tax rule conflicts, (4) privacy implications of on-chain trade attribution, (5) PLM versus AATM authority hierarchy, and (6) calendar integration privacy constraints.

These decisions collectively ensure that PLM delivers reliable predictions (minimum history thresholds with graceful fallbacks), handles failures without user harm (emergency buffers and degradation chains), respects global tax obligations (8-jurisdiction support), preserves user privacy (ZK-shielded attribution), maintains clear authority boundaries with AATM (liquidity-first hierarchy), and protects calendar data (client-side processing only).

2. Minimum Transaction History

Prediction accuracy depends directly on the depth and breadth of available transaction history. The PLM subsystem enforces a hard minimum of 90 days and 20 transactions before any predictive model activates. Below this threshold, the system operates in conservative mode using category-based defaults.

History Depth and Confidence Bands

New User Defaults

Users below the 90-day / 20-transaction minimum receive category-based defaults derived from anonymized aggregate data across the PLM user base. These defaults provide a reasonable baseline without requiring any personal history.

• Default emergency buffer set at 25% instead of the standard 15% - the wider margin compensates for zero personalization
• Category defaults cover common obligation types: rent/mortgage, subscriptions, payroll, and tax installments
• As transaction history accumulates, the model progressively blends personal data with aggregate defaults until the 90-day threshold is reached

Service Configuration

The liquidity-predictor service (port 8710) manages model selection based on history depth. It evaluates available data on each prediction cycle and selects the appropriate model tier automatically. Model tier transitions are logged for audit purposes.

3. Prediction Failure Handling

No predictive model achieves perfect accuracy. The PLM subsystem defines explicit failure handling procedures to ensure that prediction errors never result in forced liquidation or loss of user funds. The core principle is simple - always err on the side of protecting user assets.

Emergency Buffer Policy

• Standard buffer: 15% of predicted 30-day liquidity needs held in reserve at all times
• Low-confidence buffer: 25% applied when history depth is below 180 days or confidence band exceeds +/- 20%
• Buffer is denominated in the user's primary stablecoin holding (USDC default, user-configurable)

Graceful Degradation Chain

When a prediction fails and liquidity is insufficient to meet an upcoming obligation, the system executes the following degradation chain in strict order:

1. TWAP liquidation - gradual sell over a 4-hour window to minimize slippage. Positions are unwound starting from the most liquid assets first.
2. Borrow attempt - borrow-integration (port 9000) checks 5 lending protocols for available credit lines. If a viable rate is found (below 8% APR), a short-term borrow is executed automatically.
3. User alert - push notification and email sent with a 24-hour action window. The notification includes the predicted shortfall amount, affected obligations, and suggested actions.
4. Never force-liquidate - under no circumstances does the system force-liquidate without explicit user consent. This is a non-negotiable design principle.

Model Disable Policy

Three consecutive prediction misses (each exceeding 30% error from actual) trigger an automatic model disable for that specific user. The system reverts to conservative defaults with the 25% emergency buffer. Manual re-enable is required - the user must acknowledge the reset and opt back in through the wallet settings interface.

4. Multi-Jurisdiction Tax Rules

PLM operates across multiple tax jurisdictions, each with distinct rules for cryptocurrency taxation. The system resolves conflicts by applying a clear hierarchy: the user's declared tax residency governs all calculations. The tax-rules-engine (port 8520) applies the appropriate rule set.

Residency Governance

• Single residency: straightforward application of that jurisdiction's rules with no ambiguity
• Multi-residency: parallel calculations run for each declared jurisdiction, results presented side-by-side in the tax reporting dashboard
• Conflict resolution: when jurisdictions conflict on a specific treatment, the stricter rule is applied by default to avoid under-reporting. Users may override this with documented tax advisor approval.

Supported Jurisdictions

Cost Basis Methods

Users may select their preferred cost basis calculation method. The default is FIFO, which is accepted by the broadest range of jurisdictions. Available methods:

• FIFO (First In, First Out) - default for all jurisdictions
• LIFO (Last In, First Out) - available where jurisdiction permits
• HIFO (Highest In, First Out) - tax-optimized selection, requires explicit opt-in

Wash sale detection is automatically enabled for US and UK residency declarations. The detection window is 30 days (US) and 30 days for bed-and-breakfasting rules (UK).

5. Trade Attribution Privacy

PLM system trades must be privacy-preserving by default. On-chain observers should not be able to link automated liquidity operations to specific user accounts. The system achieves this through ZK-shielded trade attribution.

ZK-Shielded Attribution

• PLM system trades appear as PLM_SYSTEM on the block explorer - not linked to any user address
• On-chain, only aggregate pool movement is visible. Individual positions remain private behind ZK proofs.
• No cross-account linkability - PLM trades originating from different users cannot be correlated by external observers

Selective Disclosure

The selective-disclosure service (port 8490) enables users to reveal their trade history to specific parties when needed. This is a user-initiated action - the system never discloses without explicit consent.

• Users generate time-limited disclosure proofs for auditors, tax advisors, or counterparties
• Each disclosure proof is scoped to a specific date range and asset set
• Disclosure proofs are cryptographically verifiable without contacting the PLM system

Regulator Access

Authorized regulators can request disclosure through the regulator-portal (port 8500) with proper legal basis. Requests must include jurisdiction, legal authority citation, and scope. The user is notified of all regulator requests unless a valid gag order is presented. Regulator access is logged immutably and included in the user's transparency report.

6. PLM vs AATM Authority Hierarchy

PLM (Predictive Liquidity Markets) and AATM (Autonomous AI Token Managers) are complementary subsystems that must cooperate within a single vault. When their objectives conflict, a clear authority hierarchy prevents deadlocks and protects user liquidity.

Core Principle

PLM overrides AATM for liquidity management. AATM governs investment strategy exclusively - PLM cannot dictate what to buy or sell, only whether sufficient liquidity exists to execute safely.

Override Rules

• PLM can withdraw up to 10% of vault value without AATM consent for immediate liquidity needs
• PLM can block any AATM trade that would reduce reserves below the minimum threshold - defined as 15% of predicted 30-day needs
• PLM liquidity check runs before every AATM trade execution. If the trade would breach the reserve threshold, PLM veto applies with a 4-hour cooldown before AATM can retry.

Veto Mechanism and Escalation

7. Calendar Integration Privacy

PLM can ingest calendar data to improve obligation prediction accuracy. Calendar events often contain highly sensitive information - meeting attendees, locations, personal notes. The system enforces strict privacy boundaries to ensure calendar data is never exposed.

Client-Side Processing Only

Raw calendar events never leave the user's device. All parsing, extraction, and categorization happens locally in the browser or mobile app. The server receives only structured metadata.

Metadata Extraction

Only the following fields are extracted and transmitted to the server:

• Amount - estimated obligation value (extracted from event text patterns)
• Date - when the obligation occurs
• Frequency - weekly, monthly, quarterly, or annual recurrence
• Category - one of: rent, salary, subscription, tax, loan, utility, or other

The following are explicitly never transmitted: event titles, descriptions, locations, attendees, attachments, or any free-text content.

Consent and Disconnect Policy

• Opt-in only - user must explicitly connect each calendar source. No implicit access.
• Granular control - users can connect work calendar but exclude personal, or vice versa
• Instant disconnect - removing calendar integration immediately stops all metadata extraction. All server-side metadata is purged within 1 hour of disconnection.

Service Architecture

The calendar-integration service (port 8995) processes metadata only. It feeds structured obligation data into the recurring-obligation-detector (port 8590), which merges calendar-derived obligations with transaction-history-derived obligations to build the complete prediction model.

8. Cross-Reference Matrix

The following matrix maps each operational decision to its implementing service, port, and relevant configuration parameters.