Pythathon - Guards | Risk Leveled Treasury

lazer/cardano/guards/README.md

@@ -0,0 +1,76 @@
+# Team Guards Pythathon Submission
+
+## Details
+
+Team Name: Guards
+Submission Name: Guards One
+Team Members: @f0x1777 @kevan1 @joaco05
+Contact: @f0x1777
+
+## Project Description
+
+Guards is a multichain treasury protection workflow that uses Pyth price feeds to monitor liquid portfolio value, stable-denominated floors, and oracle-aware de-risking conditions. This submission focuses on the Cardano deployment surface.
+
+This is the initial draft submission only. Source code, setup steps, and the full demo flow will be added incrementally in later updates to this draft PR.
+
+## Testing & Verification
+
+### How to Test This Contribution
+
+The current implementation can be verified in three layers:
+
+1. Static checks: typecheck and unit/integration tests
+2. Local simulation: deterministic breach -> de-risk -> exit -> recovery flow
+3. Live oracle wiring: fetch a real signed Pyth update for Cardano preprod
+
+### Prerequisites
+
+- Node.js `>= 24.0.0`
+- `pnpm`
+- A `.env` file based on `.env.example`
+- A valid `PYTH_API_KEY`
+- Cardano preprod configuration for live verification:
+  - `PYTH_PREPROD_POLICY_ID`
+  - `CARDANO_BLOCKFROST_PROJECT_ID`
+  - `CARDANO_PYTH_STATE_REFERENCE`
+
+### Setup & Run Instructions
+
+```bash
+pnpm install
+cp .env.example .env
+```
+
+Fill the required environment variables, then run:
+
+```bash
+# Static validation
+pnpm typecheck
+pnpm test
+
+# Deterministic treasury simulation
+pnpm simulate
+
+# Fetch a live signed Pyth update for the Cardano preprod flow
+pnpm pyth:fetch-live
+
+# Run the UI locally
+pnpm --dir apps/ui dev
+```
+
+Local UI routes:
+
+- Landing: `http://localhost:3000`
+- Dashboard: `http://localhost:3000/dashboard`
+
+### Deployment Information
+
+Current deployment target for the hackathon is **Cardano preprod**.
+
+Relevant deployment/runtime notes:
+
+- Pyth preprod policy id:
+  `d799d287105dea9377cdf9ea8502a83d2b9eb2d2050a8aea800a21e6`
+- Frontend can be deployed from `apps/ui`
+- Off-chain oracle/keeper services require a Node 24 runtime plus the Cardano/Pyth environment variables listed above
+- The multichain control-plane logic is shared, but this submission's live execution path is centered on Cardano preprod

lazer/cardano/guards/source/.env.example

@@ -0,0 +1,45 @@
+APP_PUBLIC_NAME=guards.one
+APP_INTERNAL_NAME=anaconda
+PORT=4310
+
+PYTH_API_KEY=replace_with_pyth_api_key
+PYTH_PREPROD_POLICY_ID=d799d287105dea9377cdf9ea8502a83d2b9eb2d2050a8aea800a21e6
+PYTH_API_BASE_URL=https://api.pyth.network
+PYTH_METADATA_SERVICE_URL=
+PYTH_PRICE_SERVICE_URL=
+PYTH_STREAM_CHANNEL=fixed_rate@200ms
+PYTH_PRIMARY_FEED_ID=pyth-ada-usd
+PYTH_PRIMARY_SYMBOL_QUERY=ADA/USD
+PYTH_PRIMARY_ASSET_TYPE=crypto
+PYTH_PRIMARY_PRICE_FEED_ID=
+CARDANO_PYTH_STATE_REFERENCE=replace_with_pyth_state_reference_utxo
+
+CARDANO_NETWORK=preprod
+CARDANO_TESTNET_MAGIC=1
+CARDANO_PROVIDER=blockfrost
+CARDANO_PROVIDER_URL=https://cardano-preprod.blockfrost.io/api/v0
+CARDANO_BLOCKFROST_PROJECT_ID=replace_with_blockfrost_project_id
+POLICY_VAULT_SCRIPT_FILE=./apps/blockchain/cardano/contracts/aiken/artifacts/policy_vault.plutus
+POLICY_VAULT_ADDRESS_FILE=./apps/blockchain/cardano/contracts/aiken/artifacts/policy_vault.addr
+CARDANO_SWAP_PROVIDER=dexhunter
+CARDANO_PROTOCOL_FEE_BPS=30
+CARDANO_MAX_TOTAL_FEE_BPS=100
+CARDANO_PROTOCOL_FEE_MODE=explicit_output
+CARDANO_EXECUTION_ROUTE_ID=cardano-minswap-ada-usdm
+DEXHUNTER_BASE_URL=https://api-us.dexhunterv3.app
+DEXHUNTER_PARTNER_ID=replace_with_dexhunter_partner_id
+DEXHUNTER_PARTNER_FEE_PERCENT=0.3
+MINSWAP_AGGREGATOR_URL=https://agg-api.minswap.org/aggregator
+MINSWAP_PARTNER_CODE=replace_with_minswap_partner_code
+CARDANO_EXECUTION_HOT_WALLET_ADDRESS=replace_with_execution_hot_wallet
+CARDANO_EXECUTION_HOT_WALLET_SKEY_PATH=./secrets/execution-hot.skey
+CARDANO_GOVERNANCE_WALLET_ADDRESS=replace_with_governance_wallet
+CARDANO_GOVERNANCE_SKEY_PATH=./secrets/governance.skey
+
+AUDIT_DB_PATH=./data/guards-one.sqlite
+
+# Image generation (Nano Banana 2 / Gemini)
+GEMINI_API_KEY=replace_with_gemini_api_key
+
+# Replicate API
+REPLICATE_API_TOKEN=replace_with_replicate_api_token

lazer/cardano/guards/source/.github/copilot-instructions.md

@@ -0,0 +1,12 @@
+# Copilot Review Instructions
+
+Review this repository as a treasury automation system where oracle correctness and bounded execution matter more than stylistic preferences.
+
+Focus on:
+- risk-ladder invariants across `Normal -> Watch -> Partial DeRisk -> Full Stable Exit -> Frozen`, plus the `Auto Re-entry` recovery path
+- oracle guardrails: stale data rejection, confidence thresholds, cooldown handling, and deterministic use of snapshots
+- execution safety: approved routes only, bounded sell amounts, min-buy enforcement, reason hashes, and reproducible audit trails
+- multichain discipline: shared core logic must remain chain-agnostic and adapters must not leak Cardano-specific assumptions back into `packages/core`
+- tests: missing edge cases, regressions in partial de-risk sizing, full exit behavior, or re-entry hysteresis
+
+Prioritize bugs, broken invariants, security gaps, and missing tests. De-prioritize cosmetic refactors unless they affect correctness or maintainability.

lazer/cardano/guards/source/.gitignore

@@ -0,0 +1,10 @@
+node_modules/
+.DS_Store
+.pnpm-store/
+*.log
+.env
+.env.*
+!.env.example
+secrets/
+*.sqlite
+apps/blockchain/cardano/contracts/aiken/build/

lazer/cardano/guards/source/INTERNAL_NOTES.md

@@ -0,0 +1,137 @@
+# Internal Notes
+
+> This document captures internal context, architectural decisions, and development history that are useful for the team but not relevant to the public-facing README. Keep it updated as the project evolves.
+
+---
+
+## Origin
+
+Guards was originally built for the **Buenos Aires Pythathon** (Pyth Network hackathon). The challenge was to demonstrate meaningful use of Pyth oracle data beyond simple price feeds. We chose treasury risk management because it requires multiple oracle signals (price, EMA, confidence, freshness) and turns them into real execution decisions — not just charts.
+
+The public branding is `guards.one`. The internal package namespace is `anaconda` (the original project codename).
+
+## Why Treasury Risk Management
+
+We evaluated several directions before settling on treasury policy enforcement:
+
+- **Price alerts** — too simple, no execution surface
+- **DEX aggregation** — competitive space, oracle usage is shallow
+- **Lending protocol** — requires deep on-chain infra, too much scope for a hackathon
+- **Treasury autopilot** — needs multiple oracle signals, has a clear execution model, and solves a real problem for DAOs
+
+The insight was that DAOs define risk in percentages but fail when absolute fiat floors are breached. Most treasury tooling is passive. Guards makes it active.
+
+## Key Architectural Decisions
+
+### Chain-agnostic core from day one
+
+Even though Cardano was the only live target, we built `packages/core` with zero chain imports. This was intentional: if the core engine depends on Cardano types, adding Solana or EVM later requires a refactor. By isolating the business logic early, each chain adapter only needs to implement `TreasuryConnector`.
+
+**Trade-off:** More upfront abstraction work. Worth it for multichain credibility.
+
+### Split custody model
+
+We deliberately avoided the pattern where automated bots spend from the governance multisig. Instead, governance pre-approves a bounded execution bucket. The keeper can only swap within policy limits from the hot wallet. This is safer and more realistic for production DAOs.
+
+### Risk ladder over binary modes
+
+Early versions had a simple "safe/risky" toggle. We replaced it with a 6-stage risk ladder (Normal → Watch → Partial De-Risk → Full Exit → Frozen → Re-Entry) because:
+- Gradual escalation reduces unnecessary trading
+- Frozen state handles oracle quality degradation
+- Re-entry with hysteresis prevents oscillation
+- Each stage is explainable to auditors and governance
+
+### DexHunter as primary venue
+
+Chosen over Minswap because DexHunter offers:
+- Partner fee infrastructure (revenue capture)
+- Aggregated routing across Cardano DEXs
+- API-first design suitable for automated execution
+
+Minswap is kept as fallback. The venue layer is abstracted so adding new venues is straightforward.
+
+### Static UI → Next.js migration plan
+
+The repository currently serves the operator demo through the static preview flow. A richer Next.js UI exists as a parallel feature branch and is intended to replace the static shell once it lands.
+
+Why that migration still matters:
+- component-based architecture
+- stricter type safety around the operator surface
+- better developer experience for larger UI changes
+- a cleaner path to a production-ready build pipeline
+
+Design direction: premium dark theme inspired by [squads.xyz](https://squads.xyz), with electric blue (#3b82f6) accents on deep black (#08090c). The goal is to feel like institutional-grade treasury tooling, not a hackathon project.
+
+## Development Workflow
+
+### Worktree-based feature branches
+
+We use `git worktree` for parallel feature development. Each feature gets its own directory:
+
+```bash
+git worktree add ../anaconda-<feature> feature/<branch-name>
+```
+
+This allows working on multiple features simultaneously without branch switching.
+
+### PR review flow
+
+- Every feature branch gets a PR against `main`
+- Copilot review is requested on each PR
+- Review comments are tracked in `NEXT_STEPS.md`
+
+### Monorepo scripts
+
+| Script | Purpose |
+|--------|---------|
+| `pnpm test` | Run vitest across all packages |
+| `pnpm typecheck` | TypeScript strict mode check |
+| `pnpm simulate` | End-to-end backend simulation |
+| `pnpm export:ui-data` | Generate demo state JSON for UI |
+| `pnpm preview` | Backend server + operator demo at :4310 |
+
+## PR History & Review Tracker
+
+| PR | Scope | Status |
+|----|-------|--------|
+| #1 | Documentation bootstrap | Merged |
+| #2 | Core policy engine | Merged |
+| #3 | SVM + EVM scaffolds | Merged |
+| #4 | Cardano PolicyVault simulator | Merged |
+| #5 | Backend orchestration + legacy UI | Merged |
+| #7 | Cardano swap venue strategy | Merged |
+| #8 | Protocol fee model | Merged |
+| #9 | Premium UI overhaul (Next.js) | Open |
+| #10 | Cardano custody model | Merged |
+| #12 | DexHunter live adapter | Merged |
+
+Detailed review items and their resolution are tracked in [NEXT_STEPS.md](./NEXT_STEPS.md).
+
+## Tooling & AI-Assisted Development
+
+### Skills & MCP integrations
+
+| Tool | Purpose | Config |
+|------|---------|--------|
+| Nano Banana 2 | Logo/image generation via Gemini 3.1 Flash | `~/tools/nano-banana-2`, key in `~/.nano-banana/.env` |
+| 21st.dev Magic | AI-powered UI component generation | MCP in `~/.claude.json` |
+| Replicate | Additional AI model access | API token in `.env` |
+
+### Generated assets
+
+- `apps/ui/public/guards-logo.png` — Shield + "GUARDS" wordmark, white on transparent background. Used across navbar, sidebar, footer, and README. Favicon is configured separately as `/guards-icon.svg`.
+
+## Pending Work
+
+See [NEXT_STEPS.md](./NEXT_STEPS.md) for the full backlog. Key priorities:
+
+1. **Wire real Cardano wallet** into DexHunter execution path
+2. **Port PolicyVault to Aiken** (on-chain validator)
+3. **Integrate real Pyth signed updates** on preprod
+4. **Surface fee breakdown** in operator UI
+5. **Add CI** for tests and typecheck
+6. **Deploy storage** — replace SQLite with production-grade persistence
+
+## Team & Contact
+
+This project is maintained by the SOLx-AR team. For questions or collaboration, reach out through the GitHub organization.