Skip to content

build_implementation.md

Latest commit

 

History

History
69 lines (58 loc) · 5.42 KB

build_implementation.md

File metadata and controls

69 lines (58 loc) · 5.42 KB
Raw

Green Receipts — Build Implementation

Goal: ship a demo-ready slice that offsets a sample order and shows a minted receipt (mock mode and live Bitgreen call if cred/funds available). Prioritize end-to-end “click → retire → receipt link/QR” with polished UX, minimal moving parts, and fallback paths.

Architecture (lean)

  • Browser app first: React/TS web app to exercise flows (estimation → offset → receipt view) without extension friction; later swapped into extension UI.
  • Browser extension (Manifest v3) comes after the web app is stable; injects CTA on confirmation pages.
  • FastAPI service exposes /estimate, /offset, /receipt/:id; persists lightweight state in SQLite for demo.
  • Rust XCM runner (bin) invoked by FastAPI to call Bitgreen retire() and then mint a receipt (either via ink! NFT on a dev parachain or via a mock if live chain unavailable).
  • Assets: five badge images pre-pinned to IPFS (CID map baked into service); receipt metadata JSON follows common NFT schema.
  • Demo mode: Zombienet/local mock for zero-cost runs; Live mode: ws endpoint + funded accounts.

Milestone 1 — Bootstrap & Dependencies

  • python -m venv .venv && source .venv/bin/activate && pip install fastapi uvicorn[standard] pydantic
  • npm create vite@latest green-web -- --template react-ts for the web UI; add react-query (or TanStack Query) for API calls.
  • rustup toolchain install stable (if missing) and cargo new green-xcm --bin.
  • Pull/pin 5 badge PNGs to IPFS (or use existing pinned CIDs) and record the CID map.

Milestone 2 — Web App (UI-first harness)

  • Build pages: Order mock form → Estimate view → Confirm offset → Result (burn hash + receipt link/QR).
  • Use fetch/TanStack Query to call FastAPI; handle states: idle, estimating, confirming, processing, success/fail.
  • Include wallet-less path: user can just proceed; after success, show copyable link/QR to receipt.
  • Keep styling minimal but polished (system font, accessible contrast, spinner, toasts).

Milestone 3 — FastAPI + Estimation

  • Models: OrderEstimateRequest, EstimateResponse, OffsetRequest, OffsetResult.
  • /estimate: heuristic based on weight keywords and destination; cap ranges; return kg CO2 and badge tier.
  • /offset: writes row to SQLite (id, order_meta, kg, tier, status, tx_hash, receipt_uri), invokes Rust runner (blocking for demo), updates status.
  • /receipt/{id}: returns JSON for frontend link/QR.
  • Security: CORS allow web app origin; strip PII; naive rate-limit (per-IP memory counter).
  • Run: uvicorn app.main:app --reload --port 8000.

Milestone 4 — Rust XCM Runner

  • Inputs: kg, badge tier, order id; config via env (BITGREEN_WS, RECEIPT_WS, SEED, FEE_MULTIPLIER, MOCK).
  • Default MOCK=1: simulate tx hashes and return success fast for demos.
  • Live path: use subxt (latest supports metadata v15) to call Bitgreen retire extrinsic; then call receipt mint extrinsic on receipt chain/pallet.
  • Receipt path options:
    • Preferred Polkadot-native: minimal pallet on a Polkadot Cloud devnet (if available) for NFT-like receipt with IPFS metadata.
    • Backup: EVM-compatible chain (e.g., Moonbase) with pre-deployed ERC-721; mint metadata pointing to badge CID and burn tx.
  • Return {burn_tx, receipt_uri} to FastAPI.

Milestone 5 — Receipt Assets & Metadata

  • Badge tiers (e.g., leaf/sprout/tree/earth/planet) → pinned PNG CIDs.
  • Metadata JSON: order id/timestamp, kg neutralized, burn tx hash, badge image CID. Follow common NFT fields (name, description, image, attributes).
  • Store CID map in FastAPI config; ensure runner writes metadata to IPFS (or uses pre-pinned templates).

Milestone 6 — Testing & Demo Flow

  • End-to-end in MOCK mode via web app: submit mock order → estimate → offset → see fake burn hash + receipt link/QR.
  • If funds/endpoint ready: one live Bitgreen retire to capture a real hash and receipt.
  • Capture screenshots of the web app states and explorer view of receipt/burn tx.
  • Document commands/runbook in README; note contingencies and mock mode.

Milestone 7 — Browser Extension (after web app is stable)

  • Scaffold: npm create vite@latest green-extension -- --template react-ts; add Manifest v3 with activeTab, scripting.
  • Content script: detect confirmation pages via URL patterns and DOM keywords (“order”, “thank you”, “confirmation”); debounce detections.
  • Inject a small CTA button; open an overlay that reuses the web app components (shared UI pkg or embedded build).
  • Calls the same FastAPI endpoints; reuse states and copy-to-clipboard/QR logic.
  • Respect privacy: minimal permissions, no unnecessary data stored; clear messaging about what is sent.

Up-to-date tech notes (Nov 2025)

  • Polkadot SDK (Substrate) FRAME v3 and metadata v15 supported by subxt latest release.
  • XCM v3 live; reserve/teleport patterns standard; account for execution fees per destination.
  • Bitgreen: Polkadot parachain offering carbon credit retire extrinsic; confirm current public WS endpoint before live runs.
  • Frontend TS: polkadot-api (typed JS SDK) exists, but backend-driven chain calls via Rust subxt keep the frontend simple.

Suggested commands to start

  • python -m venv .venv && source .venv/bin/activate && pip install fastapi uvicorn[standard] pydantic
  • npm create vite@latest green-web -- --template react-ts && cd green-web && npm install @tanstack/react-query
  • cargo new green-xcm --bin && cd green-xcm && cargo add subxt tokio anyhow clap serde