{"id":50758588,"url":"https://github.com/flammafex/scarcity","last_synced_at":"2026-06-11T07:33:16.312Z","repository":{"id":346473586,"uuid":"1126971902","full_name":"flammafex/scarcity","owner":"flammafex","description":"Serverless digital cash inspired by Gesellian economics. Gossip-based double-spend prevention, cryptographic privacy, and anti-accumulation demurrage—no mining, no staking, no fees.","archived":false,"fork":false,"pushed_at":"2026-03-24T02:21:49.000Z","size":408,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-25T02:08:32.287Z","etag":null,"topics":["anonymous-payments","cryptocurrency","decentralized","digital-cash","gossip-protocol","p2p","privacy","typescript","webrtc","zero-fees"],"latest_commit_sha":null,"homepage":"https://scarbucks.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flammafex.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-02T23:11:01.000Z","updated_at":"2026-03-24T02:21:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/flammafex/scarcity","commit_stats":null,"previous_names":["flammafex/scarcity"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/flammafex/scarcity","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flammafex%2Fscarcity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flammafex%2Fscarcity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flammafex%2Fscarcity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flammafex%2Fscarcity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flammafex","download_url":"https://codeload.github.com/flammafex/scarcity/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flammafex%2Fscarcity/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34188272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anonymous-payments","cryptocurrency","decentralized","digital-cash","gossip-protocol","p2p","privacy","typescript","webrtc","zero-fees"],"created_at":"2026-06-11T07:33:15.629Z","updated_at":"2026-06-11T07:33:16.300Z","avatar_url":"https://github.com/flammafex.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🩸 Scarcity\n\n**Scarcity** is a Chaumian e-cash protocol. It provides private, bearer-instrument digital tokens with double-spend prevention — without blockchains, mining, or global ledgers.\n\nFreebird issuers act as mints (controlling who can issue tokens and under what policy), Witness federations provide ordering and auditability, and gossip networks propagate spent-token nullifiers for fast double-spend detection.\n\n## Quick Start (Docker)\n\n```bash\ngit clone https://git.carpocratian.org/sibyl/scarcity.git\ncd scarcity\ndocker compose up --build --abort-on-container-exit\n```\n\nThis runs the full stack (Freebird, Witness, HyperToken) and integration tests. You should see \"All tests passed!\" at the end.\n\n## Features\n\n- **Chaumian privacy** — Freebird VOPRF blind signatures make issuance and spending unlinkable\n- **No blockchain** — Nullifier gossip replaces global ledger consensus\n- **No fees** — No gas, mining rewards, or staking\n- **No addresses** — Bearer tokens with no on-chain identity\n- **Issuer-as-mint** — Freebird issuers control token policy; vendors choose which issuers to trust\n- **Token operations** — Split, merge, multi-party transfers, HTLCs, cross-federation bridging\n- **Auditability** — Witness attestations can be anchored to Ethereum for tamper-proof history\n- **Lazy demurrage** — Tokens expire after ~1.5 years if not transferred (configurable)\n\n## Design Philosophy\n\nScarcity separates three orthogonal concerns:\n\n| Concern | Primitive | Role in e-cash |\n|---------|-----------|----------------|\n| **Identity** | Freebird (VOPRF) | Mint authority — issues blind-signed tokens, controls policy |\n| **Time** | Witness (threshold sigs) | Ordering — timestamps transfers, anchors to external systems |\n| **State** | HyperToken (gossip) | Propagation — broadcasts nullifiers for double-spend detection |\n\nThe software provides cryptographic guarantees (privacy, unlinkability, double-spend detection). The Freebird issuer operator establishes economic policy (who can mint, how much, backed by what). The Witness federation makes that policy auditable.\n\nThis follows the Chaumian model: the protocol doesn't enforce supply limits — the mint does. Vendors choose which mints they trust, just as merchants choose which banks' cards they accept.\n\n## Architecture\n\n| Component | Purpose | Link |\n|-----------|---------|------|\n| **Freebird** | Anonymous authorization via P-256 VOPRF blind signatures | [git.carpocratian.org/sibyl/freebird](https://git.carpocratian.org/sibyl/freebird) |\n| **Witness** | Threshold timestamping (Ed25519/BLS12-381) with external anchoring | [git.carpocratian.org/sibyl/witness](https://git.carpocratian.org/sibyl/witness) |\n| **HyperToken** | P2P networking with WebSocket/WebRTC | [git.carpocratian.org/sibyl/hypertoken](https://git.carpocratian.org/sibyl/hypertoken) |\n\n```\n┌─────────────────────────────────────────────────────┐\n│  Token Layer                                        │\n│  • Mint, transfer, split, merge, HTLC, bridge       │\n│  • Freebird VOPRF authorization + ownership proofs  │\n└─────────────────────────────────────────────────────┘\n                         ↓\n┌─────────────────────────────────────────────────────┐\n│  Gossip Layer                                       │\n│  • Nullifier broadcast with Witness proof validation │\n│  • Adaptive routing (Naive → Supernode → Kademlia)  │\n│  • E2E encryption between peers                     │\n└─────────────────────────────────────────────────────┘\n                         ↓\n┌─────────────────────────────────────────────────────┐\n│  Validation Layer                                   │\n│  • Freebird auth token verification (single-use V3) │\n│  • Gossip check: probabilistic (~10-50ms)           │\n│  • Witness check: deterministic (threshold signed)  │\n│  • Confidence scoring: peer count + witness + time  │\n└─────────────────────────────────────────────────────┘\n```\n\n## How It Works\n\n### Token Lifecycle\n\n1. **Mint**: Issuer operator creates tokens (policy-dependent — could require deposit, proof of work, etc.)\n2. **Transfer**: Sender blinds a commitment via Freebird, obtains a VOPRF auth token, timestamps via Witness, broadcasts nullifier to gossip\n3. **Validate**: Recipient verifies the auth token (single-use V3), checks gossip for double-spend, verifies Witness attestation, computes confidence score\n4. **Receive**: If validation passes, recipient accepts the bearer token with a unique derived secret\n\n### Double-Spend Prevention\n\n1. **Nullifier generation**: Sender computes `SHA-256(secret || tokenId)` — a unique, deterministic spend marker\n2. **Witness timestamping**: Transfer package hash is threshold-signed by the Witness federation\n3. **Gossip broadcast**: Nullifier + Witness proof propagate to all peers (proof is validated before storage)\n4. **Validation**: Recipient checks gossip (fast, probabilistic) then Witness (slow, deterministic)\n\nNo global ledger required. Nullifiers are single-use markers that prove a token was spent.\n\n### VOPRF Flow (Freebird)\n\n```\nSender                    Freebird Issuer              Freebird Verifier\n  │                            │                             │\n  │── blind(publicKey) ───────→│                             │\n  │                            │── evaluate(blinded) ──→     │\n  │←── token + DLEQ proof ────│                             │\n  │                            │                             │\n  │── unblind (local) ────→    │                             │\n  │── build V3 redemption ──→  │                             │\n  │                            │                             │\n  │                    (later, at recipient)                  │\n  │                            │                             │\n  │── verifyToken(V3) ────────────────────────────────────→ │\n  │←── ok (token consumed) ──────────────────────────────── │\n```\n\nV3 tokens are self-contained and single-use — consumed on first verification. The token embeds the issuer ID, so vendors know which mint issued it.\n\n## Privacy Model\n\n| Property | Mechanism |\n|----------|-----------|\n| **Anonymous issuance** | VOPRF blinds the commitment — issuer can't link issuance to spending |\n| **Unlinkable transfers** | Nullifiers derived from secret + tokenId, not sender identity |\n| **Issuer-aware, not issuer-tracked** | V3 tokens identify the mint but not the user |\n| **No addresses** | Tokens are bearer instruments (possession = ownership) |\n| **Per-token secrets** | Each received token derives a unique secret from the wallet master key |\n| **Network privacy** | Optional Tor integration for .onion services |\n| **E2E encryption** | All peer communication encrypted (ECDH + AES-256-GCM) |\n\n## Installation\n\n### Requirements\n\n- Node.js 20+\n- Docker (for running infrastructure)\n\n### Local Development\n\n```bash\ngit clone https://git.carpocratian.org/sibyl/scarcity.git\ncd scarcity\nnpm install\nnpm run build\n\n# Start infrastructure\ndocker compose up -d freebird-issuer freebird-verifier witness-gateway hypertoken-relay\n\n# Run tests\nnpm test\n\n# Run tests against live services (no fallback)\nnpm run test:live\n```\n\n### Available Scripts\n\n```bash\nnpm run build          # Compile TypeScript\nnpm run clean          # Remove dist directory\nnpm run dev            # Watch mode compilation\nnpm test               # Integration tests (fallback mode for unavailable services)\nnpm run test:live      # Live service tests (requires all services running)\nnpm run web            # Start web wallet (localhost:3000)\nnpm run explorer       # Start Nullscape Explorer (localhost:3001)\n```\n\n## Web Wallet\n\nA browser-based wallet for managing tokens.\n\n```bash\nnpm run web\n# Open http://localhost:3000\n```\n\nFeatures:\n- Create/import wallets with PIN-protected secret export\n- Mint, send, receive, split, merge tokens\n- Token expiration visibility with warning banners\n- Step-by-step transaction progress feedback\n- Privacy explainer modal\n- PWA support (installable, works offline)\n\n## Nullscape Explorer\n\nReal-time nullifier feed for network transparency.\n\n```bash\nnpm run explorer\n# Open http://localhost:3001\n```\n\nFeatures:\n- Live WebSocket feed of nullifier propagation\n- Historical search and activity charts\n- Federation statistics\n- SQLite persistence\n\n## CLI\n\n```bash\n# Install globally\nnpm install -g .\n\n# Or run directly\n./dist/src/cli/index.js \u003ccommand\u003e\n```\n\n### Wallet Commands\n\n```bash\nscar wallet create \u003cname\u003e     # Create wallet\nscar wallet list              # List wallets\nscar wallet show \u003cname\u003e       # Show public key\nscar wallet export \u003cname\u003e     # Export secret (requires PIN in web wallet)\n```\n\n### Token Commands\n\n```bash\nscar token list \u003cwallet\u003e      # List tokens\nscar token mint \u003cwallet\u003e \u003camount\u003e\nscar token show \u003ctoken-id\u003e\n```\n\n### Advanced Operations\n\n```bash\n# Split token into parts\nscar split \u003ctoken-id\u003e --amounts 30,40,30 --recipients \u003ckey1\u003e,\u003ckey2\u003e,\u003ckey3\u003e\n\n# Merge tokens\nscar merge \u003ctoken-id-1\u003e,\u003ctoken-id-2\u003e --recipient \u003ckey\u003e --wallet \u003cname\u003e\n\n# Multi-party transfer\nscar multiparty \u003ctoken-id\u003e alice:30 bob:40 carol:30\n\n# Hash-locked transfer (atomic swaps)\nscar htlc create \u003ctoken-id\u003e \u003crecipient\u003e --hash-lock \u003chash\u003e\nscar htlc claim \u003cpackage\u003e --wallet \u003cname\u003e --preimage \u003cpreimage\u003e\n\n# Time-locked transfer\nscar htlc create \u003ctoken-id\u003e \u003crecipient\u003e --time-lock \u003ctimestamp\u003e --refund-key \u003ckey\u003e\nscar htlc refund \u003cpackage\u003e --wallet \u003cname\u003e  # After expiry\n\n# Cross-federation bridge\nscar bridge transfer \u003ctoken-id\u003e \u003crecipient\u003e --target-gateway \u003curl\u003e --target-network \u003cid\u003e\nscar bridge claim \u003cpackage\u003e --wallet \u003cname\u003e\n```\n\n### Configuration\n\n```bash\nscar config list\nscar config set witness.gatewayUrl http://localhost:8083\nscar config set freebird.issuerEndpoints http://localhost:8081\nscar config set freebird.verifierUrl http://localhost:8082\nscar config set hypertoken.relayUrl ws://localhost:5001\n```\n\n## API Usage\n\n```typescript\nimport {\n  ScarbuckToken,\n  NullifierGossip,\n  TransferValidator,\n  FreebirdAdapter,\n  WitnessAdapter,\n  HyperTokenAdapter\n} from 'scarcity';\n\n// Initialize infrastructure\nconst freebird = new FreebirdAdapter({\n  issuerEndpoints: ['http://localhost:8081'],\n  verifierUrl: 'http://localhost:8082'\n});\n\nconst witness = new WitnessAdapter({\n  gatewayUrl: 'http://localhost:8083'\n});\n\nconst hypertoken = new HyperTokenAdapter({\n  relayUrl: 'ws://localhost:5001'\n});\n\nawait hypertoken.connect();\n\n// Create gossip network\nconst gossip = new NullifierGossip({ witness });\nhypertoken.getPeers().forEach(peer =\u003e gossip.addPeer(peer));\n\n// Create validator (requires freebird for V3 token verification)\nconst validator = new TransferValidator({\n  freebird,\n  gossip,\n  witness,\n  waitTime: 5000,\n  minConfidence: 0.7\n});\n\n// Mint and transfer\nconst token = ScarbuckToken.mint(100, freebird, witness, gossip);\nconst pkg = await token.transfer(recipientPublicKey);\n\n// Validate and receive\nconst result = await validator.validateTransfer(pkg);\nif (result.valid) {\n  const received = await ScarbuckToken.receive(pkg, recipientSecret, freebird, witness, gossip);\n}\n```\n\n## HyperToken Integration\n\nScarcity uses HyperToken for P2P networking with:\n\n- **Hybrid transport**: WebSocket for signaling, auto-upgrade to WebRTC for lower latency\n- **Adaptive routing**: Automatically switches strategy based on network size\n  - \u003c50 peers: Naive broadcast\n  - 50-99 peers: Supernode hierarchical routing\n  - 100+ peers: Kademlia DHT\n- **E2E encryption**: ECDH P-256 key exchange + AES-256-GCM (mandatory, not optional)\n- **State sync**: Delta-based catch-up for reconnecting peers\n- **Auto-reconnection**: Exponential backoff with message buffering\n- **Binary encoding**: MessagePack with compression for efficiency\n\n## Security\n\n### Protected Against\n\n- **Double-spending**: Nullifier sets + Witness timestamps + gossip proof validation\n- **Forgery**: Freebird's unforgeable VOPRF tokens with DLEQ proof verification (scalar range validated)\n- **Replay attacks**: Single-use nullifiers with timestamp binding; bridge replay protection via target-federation nullifier check\n- **Token swapping**: Auth tokens are included in the package hash covered by Witness proof\n- **Rogue key attacks**: BLS key aggregation checks Proof-of-Possession when available\n- **Eclipse attacks**: Outbound peers weighted 3x higher in confidence scoring\n- **Spam/flooding**: Peer reputation scoring, rate limiting, optional PoW\n- **HTLC griefing**: Two-phase nullifier publication (at claim/refund, not at lock)\n- **Network partitions**: Gossip heals on reconnect, Witness provides ordering\n\n### Not Protected Against\n\n- **Token theft**: Secure your secrets. Use TLS for transmission.\n- **Network correlation**: Timing analysis by observers. Use Tor.\n- **Quantum adversaries**: ECDLP-based cryptography (P-256)\n- **Legal seizure**: Bearer instruments have no account freeze mechanism\n- **Issuer misbehavior**: A trusted issuer can over-issue. Ethereum anchoring via Witness makes this auditable but not preventable at the protocol level.\n\n### Trust Assumptions\n\n- Freebird issuer enforces honest monetary policy\n- Gossip network has at least some honest peers\n- Witness federation threshold holds (\u003c T collude)\n- Freebird issuer/verifier deployed on separate infrastructure (prevents timing attacks)\n\nSee [SECURITY.md](SECURITY.md) for threat models and configuration examples.\n\n## Limitations\n\n- **Latency**: Validation takes seconds (5s default wait), not milliseconds\n- **Bandwidth**: Gossip overhead scales with peer count (O(peers) per transfer)\n- **Not instant finality**: Probabilistic confidence, not deterministic\n- **Token expiry**: Lazy demurrage means tokens must be refreshed periodically\n- **No fixed denominations**: Arbitrary amounts allow amount-based fingerprinting (a known trade-off vs. classic Chaumian fixed denominations)\n\n## Economics\n\nScarcity implements zero-cost transfers with lazy demurrage (tokens expire after ~576 days if not transferred). This anti-accumulation design is inspired by Gesellian economics. See [ECONOMICS.md](ECONOMICS.md) for the full rationale.\n\n## Environment\n\nScarcity uses significantly less energy than proof-of-work systems. No mining, no global state synchronization. See [ENVIRONMENT.md](ENVIRONMENT.md) for analysis.\n\n## Development\n\n```bash\nnpm run build          # Build\nnpm run clean          # Clean dist\nnpm run dev            # Watch mode\nnpm test               # Integration tests (with fallback)\nnpm run test:live      # Live service tests (no fallback)\nnpm run test:basic     # Single test suite\n```\n\n### Test Suites\n\n```bash\nnpm run test:basic         # Basic transfers\nnpm run test:double-spend  # Double-spend detection\nnpm run test:degradation   # Graceful degradation\nnpm run test:phase3        # Advanced features\nnpm run test:live          # All services, no fallback\n```\n\n## Project Status\n\nThis is a research prototype. Core protocol, advanced features, and tooling are implemented and tested. Production deployment requires security audits and operational hardening.\n\n| Phase | Status |\n|-------|--------|\n| Core Protocol | Complete |\n| Hardening (BLS, WebRTC, VOPRF, Tor) | Complete |\n| Advanced Features (split, merge, HTLC, bridge) | Complete |\n| Tooling (web wallet, CLI, explorer) | Complete |\n| Mobile SDK | Planned |\n\n## License\n\nApache License 2.0\n\n## Related Projects\n\n- [Freebird](https://git.carpocratian.org/sibyl/freebird) - Anonymous authorization (VOPRF mint)\n- [HyperToken](https://git.carpocratian.org/sibyl/hypertoken) - P2P networking\n- [Witness](https://git.carpocratian.org/sibyl/witness) - Threshold timestamping with external anchoring\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflammafex%2Fscarcity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflammafex%2Fscarcity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflammafex%2Fscarcity/lists"}