Green Receipts

One-click “offset and mint” demo: a browser UI estimates a checkout’s footprint, submits a signed on-chain action to a local Substrate dev chain, and produces a verifiable receipt (metadata + badge image) served locally.

Project Overview

• Goal: show a smooth UX for “offset any order” without requiring store changes. Users get a hash on-chain plus a receipt with metadata and badge.
• Architecture:
  • React frontend: estimate → offset → render receipt (metadata fetched from API).
  • FastAPI backend: heuristic estimator; calls a Rust runner; stores offsets in SQLite; builds metadata with a local CID and serves badge images.
  • Rust runner: mock by default; live mode submits a System.remark to a local Substrate dev chain (stand-in ledger).
  • Assets: badge PNGs hashed and served via /static; metadata stored under metadata_store/<cid>.json and exposed via /metadata/<cid>.

Setup (no payments, fully local)

1. Start the bundled dev chain (new terminal):

cd "/Users/skill4ace/Green Receipts"
./scripts/run-dev-node.sh

2. Start the API (live mode):

source .venv/bin/activate  # create if missing: python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt
export MOCK=0
uvicorn app.main:app --reload --port 8000

3. Start the web app:

cd "/Users/skill4ace/Green Receipts/green-web"
npm run dev

Open http://localhost:5173/, fill miles + category, click Estimate → Offset. You’ll see a tx hash (from the local chain) and a receipt with badge and attributes. The receipt URI is ipfs://<cid>; view metadata at http://127.0.0.1:8000/metadata/<cid>.

Modes:

• Mock: omit export MOCK=0 to skip chain calls; still get receipt metadata and badge.
• Live-standin: default BITGREEN_WS=ws://127.0.0.1:9944 hits the local chain; SEED=//Alice by default. You can point BITGREEN_WS to another Substrate node if desired.

Usage Notes

• On-chain action is a System.remark stand-in (no real retire pallet). It provides a verifiable hash on the local chain.
• Receipts are local (not pinned to public IPFS); badges come from /static/<badge>.png.
• Metadata endpoint: GET /metadata/<cid>, badges: GET /badges, GET /badges/<name>.

Dependencies

• Node 20+ (Vite dev server)
• Python 3.11+ (FastAPI, uvicorn, pydantic)
• Rust stable (for runner)
• Bundled substrate-contracts-node binary (v0.42.0) in scripts/; used by run-dev-node.sh.