ShopKeep

A Polygon ID–gated promotions platform for e-commerce: shoppers prove promotion eligibility with zero-knowledge proofs from a browser-extension wallet, and stores apply discounts without ever seeing the underlying personal data.

Full system design: docs/ARCHITECTURE.md · diagram: docs/architecture.png

Repo layout (monorepo)

.
├── packages/
│   ├── extension/              # ShopConnect browser extension (React CRA + @0xpolygonid/js-sdk)
│   │                           #   holds proofs of purchase, generates ZK proofs for promotions
│   ├── api/                    # ShopConnect API (Express) — issue/verify VCs, promotions
│   ├── store/                  # Demo storefront (Next.js + Tailwind) + ShopConnect plugin
│   └── connectors/             # ShopConnectors PHP library (multi-platform order integration)
├── docs/                       # architecture diagram + ARCHITECTURE.md
├── reference/                  # SDK source zips (gitignored)

Run the full demo (one command)

make install    # first time
make demo       # API :3001 + store :3000, DEMO_MODE — no infra needed

Or the two services by hand:

cd packages/api   && npm install && npm start                                   # :3001
cd packages/store && npm install && SHOPCONNECT_API_URL=http://localhost:3001 npm run dev  # :3000

Open http://localhost:3000, click Connect ShopConnect wallet, apply a promotion (a demo ZK proof is verified and the discount applied), then checkout to have a ShopPurchase proof-of-purchase credential issued. This runs standalone in DEMO_MODE — no extension or Issuer Node required.

Add the real browser extension

cd packages/extension && npm install && npm run build

Chrome → chrome://extensions/ → Developer mode → Load unpacked → packages/extension/build/. The extension then drives the store's ShopConnect panel via the content-script bridge and generates real Polygon ID proofs.

RPC/network is preconfigured for Polygon Amoy (packages/extension/src/constants/common.constants.js). The extension-demo variant (OIDC, etc.) is preserved on branch extension-demo-generic.

Going real (no demo mode)

The demo simulates issuance/verification; the extension always makes real proofs. To make the server real too, one command orchestrates it:

export SHOPCONNECT_DID=did:polygonid:polygon:amoy:...   # from your issuer node
make real     # publishes schema to IPFS -> checks issuer node -> writes api/.env -> launches

make real (→ scripts/setup-real.sh) requires:

1. IPFS — a Kubo endpoint (ipfs daemon, or set IPFS_API_URL) so the ShopPurchase schema/context/display are pinned and their CIDs wired into the API automatically.
2. Issuer Node — an Iden3 issuer on Amoy reachable at ISSUER_NODE_URL: see infra/issuer-node/ (Amoy env + compose + steps). Needs Docker + a funded Amoy key.

It then runs packages/api with DEMO_MODE=false, so:

• /verify cryptographically checks proofs via @iden3/js-iden3-auth against Amoy on-chain state (circuit keys in packages/api/circuits/).
• /issue mints real ShopPurchase credentials (with display method) on the node and returns an iden3comm offer the extension fetches into the wallet.

The script fails fast with actionable guidance if IPFS / the issuer node / the DID aren't ready.

Feature branches

main is the combined build. The remaining feature/PoC work lives on branches, each a clean diff off the baseline-main tag:

git branch                                   # list all features
git diff baseline-main <branch>              # review what a feature changes

Already integrated into main: fix-sig-input-v3, poc-oidc.

Standalone flow variants — each reimplements the extension's core request-handling (approveMethod) with a different Polygon ID flow, so they are mutually exclusive (pick one; they cannot be combined into a single build without a message-type router refactor): poc-jws, poc-invitation, feature-payment-demo / -demo-2, feature-onchain-revocation.

Config-level PoCs (network/identity tweaks): poc-proposal-req, poc-auth-v1.1.

See docs/ARCHITECTURE.md for the full table and rationale.

Note: branches predate the monorepo move, so they carry the extension at the repo root. To build one: git checkout <branch> then npm install && npm run build from the repo root.

Backend connector (packages/connectors/)

The ShopConnectors PHP library (rutgerkirkels/shopconnectors) retrieves orders from many webshop platforms and maps them to a single unified model — the integration surface for the ShopConnect backend plugin.

cd packages/connectors && composer install