Skip to content

About

Live auction where every bid is a PayPal AUTHORIZE hold: only the winning price is captured, the rest are voided. Crash-safe settlement saga and hash-chained audit trail. PayPal sandbox only.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

767 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

GAVEL

Every bid is a hold. The hammer is the payment.

GAVEL logo animation: the Mallet G draws round, the mallet strikes and a round shockwave leaves the G, the wordmark GAVEL glides in, then the tagline: every bid is a PayPal hold, only the winner pays.

CI License: MIT Live app Watch the film PageSpeed landing 100/100/100/100 PayPal sandbox only Open data on Hugging Face

Watch it  |  Try it, no login  |  Live app  |  Docs  |  API reference  |  Evidence  |  Limits

PayPal sandbox only: no real money moves.


GAVEL is a live auction where every bid is a PayPal authorization hold, and at the hammer only the winning price is captured. Bidders approve a ceiling up front, a deterministic engine checks every bid against it, the winner pays the hammer price, every other hold is voided, and a hash-chained ledger lets anyone verify the result. Bids can be spoken, and a spoken bid never counts until the bidder confirms it.

Built for the PayPal Hackathon 2026 by Harsh Bhanushali and Dhairya Patel.

Watch it

Title card of the GAVEL film, 2 minutes 56 seconds, captions on: the GAVEL logo and the line every bid is a PayPal hold, only the winner pays. Select it to watch on YouTube.
The film, 2:56, captions on: one lot from hold to receipt on the PayPal sandbox. Watch on YouTube.

Why GAVEL

Online auctions usually make a bidder pay first or trust the bidder to pay later. GAVEL uses a third way: a PayPal authorization hold. The bidder approves a ceiling, PayPal holds that amount without charging it, and when the hammer falls GAVEL captures only the winning price and releases every other hold. Nobody is charged for a lot they lost, and nobody can bid more than they have put on hold.

At a glance

Feature What it does
Hold, not charge Every bid is backed by a PayPal authorization hold. Only the winner pays, and only the hammer price.
Crash-safe settlement A real server process killed mid-capture: one capture, two losers voided, 0 differences between the journal and PayPal (evidence).
Verifiable result A hash-chained ledger and a public export: anyone can re-hash the chain and spot an edited entry.
Voice bidding, with a confirm Deepgram and Groq speech-to-text with failover; a spoken bid never counts until the bidder confirms it. 24 of 24 clips answered on the live socket; Deepgram parsed 11 of 11 scripted bids and Groq 9 of 11.
Fast landing page PageSpeed Insights on /: 100 Performance, 100 Accessibility, 100 Best Practices, 100 SEO on mobile and desktop (Lighthouse 13.6.0, lab data, measured by hand on 10 Nov 2026; the landing page only, not the whole app). Details and screenshots.
Built in the open 727 merged pull requests as of 11 Nov 2026, each through CI, in one MIT-licensed repository. More than 4,500 test cases run on every pull request.
Open and documented A docs site with a guided tour, an OpenAPI spec, five open datasets on Hugging Face and an honest limits page.
The flow of one lot in four words: Hold, a PayPal hold sets the ceiling and is held, not charged; Bid, every bid is checked against that hold; Hammer, the highest valid bid wins; Receipt, the winner pays and every other hold is released. A simulated lot, PayPal sandbox only.

Contents

Watch it | Why GAVEL | Live links | Try it | What is proven | How it works | See it run | Tech stack and sponsors | Evidence and gates | Run it locally | Call the API | Limits | Security | Documentation | Team | License

Live links

What Where
Web app gavel.dualmindlab.tech (also gavel-web.creharsh.workers.dev)
Judge panel gavel.dualmindlab.tech/try: a live sandbox room, no operator key. It is not linked from the public landing page
Docs docs.gavel.dualmindlab.tech, with a guided tour and a glossary
API api.gavel.dualmindlab.tech on Render; API reference and the OpenAPI spec
Open data Hugging Face collection: five datasets and an Evidence Explorer Space
Source github.com/harshbhx/gavel-auction, MIT

Try it in 60 seconds

No login and no PayPal account needed. Do not use a personal PayPal account anywhere. The rooms below are sandbox rooms: the hold in a key-less demo room is a simulated demo hold, and real PayPal sandbox runs are listed under What is proven.

  1. Watch it (1 minute). Open the scripted demo at /demo/scripted. A recorded room plays in your browser, with no server and no PayPal calls.
  2. Run it (3 minutes), no login. Open gavel.dualmindlab.tech/try and press "Start a demo auction". The hub shows a room code and a QR code. Join as a bidder, press and hold to approve the hold, bid from two bidders, then hold the hammer button on the console. The big screen shows the sale and the receipt shows what was captured and released.
  3. Verify it. Open the audit trail of the room, or the ledger lab: every entry is hashed with the one before it, and an edited entry is marked as such.
  4. Call it (judge API path). The same flow runs over plain HTTP with the shared judge key from the Devpost testing instructions (optional; the rooms above need no key): see Call the API.

Sandbox buyer logins are in the Devpost testing instructions, not in this repository (testing instructions). The demo room uses demo holds unless you log in with a sandbox buyer. Whether a judge can start a key-less room depends on the host flag JUDGE_ROOMS (see docs/DEPLOY.md); docs/DEMO.md says what is verified. More paths, a rubric map and the evidence: For judges, Trust and FAQ and the judge walkthrough.

What is proven

Numbers are as recorded in docs/GATES.md, as of 11 Nov 2026. Every run link below opens the Actions run, and redacted evidence is committed under docs/evidence. Each row says what kind of evidence it is: real sandbox (the real PayPal sandbox), simulated (the project's own fake PayPal or a fake clock) or speech clips (tested voice audio).

Claim Result Evidence
Sandbox app, partial capture, wallet and guest card holds, real webhooks Real sandbox. Gates G0, G1, G2, G3 and G4 PASS; six real webhooks verified GATES.md, G0, G1, G2, G4
A server killed mid-capture does not double-charge Real sandbox, run on a CI runner. One kill after the capture request and before the response, restart on the same data folder: one capture of 12500 equal to the hammer price, two losers voided, journal equal to PayPal, ledger of 19 entries verifies run 42558021614, evidence
Spoken bids never skip the confirm Speech clips, fake PayPal in the server. Live /audio socket: both providers answered 24 of 24 clips, 0 spoken bids accepted without a confirm run 42575018866, evidence
The hosted judge flow works end to end Simulated holds. Judge smoke on the live domains, 17 of 17 steps passed, from /try through join, bids, hammer and receipts run 42584326641
The hosted API answers quickly Hosted API. Webhook route p95 112.03 ms (n=50, runner network included); warmup after 16 minutes idle at most 0.66 s (n=2); security headers on the three custom domains run 42558107791, hosted, headers
Settlement speed on the sandbox Real sandbox. Hammer to SETTLED p95 6927.43 ms and hammer to CAPTURED p95 3766.67 ms (50 settlements of 6 holds, 49 completed, run INCOMPLETE: 1 timeout, 3 failed capture calls). An earlier n=20 run read 5591.30 ms and 3010.04 ms run 42563147792, latency
Tested More than 4,500 test cases run in CI; all eight P0 items of the security review PASS (as of 7 Nov 2026) docs/SECURITY-REVIEW.md

Gate G3 closed and the rest still open, stated as of 12 Nov 2026:

  • G3, honor period and reauthorize: PASS. A real sandbox probe started on 7 Nov 2026 at 03:06 UTC and its final checkpoint ran on 12 Nov 2026 (run). The authorization stayed capturable at 3.5, 4 and 5 days (a partial capture of 1.00 was accepted each time, HTTP 201) and reauthorize was accepted at each checkpoint, while an immediate reauthorize was refused with REAUTHORIZATION_TOO_SOON. Scope: sandbox, wallet buyer, partial capture of 1.00 only (not a card order, not a full-amount capture). Early readings on older authorizations at 3.24 and 3.5075 days (evidence) came first. The 30-day auction run is a simulation on a fake clock (SIM-MULTIDAY), not a sandbox result.
  • G5, voice accuracy: tested with voice clips, with a confirm step on every voice bid. The voice clips were generated speech. On two sets of 24 clips, Deepgram nova-3 and Groq whisper-large-v3-turbo score wrong accept 0.000 (tuned on those clips), and on a live run of 20 clips Deepgram parsed 11 of 11 scripted bids and Groq 9 of 11. A held-out noisy set of 120 clips, measured once, read wrong accept 0.058 for Groq and 0.092 for Deepgram (result). No live human test is claimed. A spoken bid never counts until the bidder confirms it.
  • Scope: PayPal sandbox only. The server kill ran on a CI runner, not the deployed host. The live socket run used the fake PayPal, and the web console microphone has been tested with a fake microphone and socket. A final_capture and a void on a guest-card authorization are not run, and the release of the remainder is inferred, not read from a buyer balance.

What is next, with owners and dates where known: Limits and next steps. What changed and when: changelog.

How it works

  1. Approve a ceiling. A bidder approves the most they may bid. PayPal places an authorization hold for that amount: held, not charged.
  2. Bid. A deterministic engine accepts or rejects each bid against the ceilings and writes every event to a hash-chained ledger.
  3. Hammer. The settlement saga captures the winning price with final_capture, voids every other hold, and records each step in a journal so a crash cannot double-charge anyone. If PayPal's answer is unknown, settlement stops for review instead of guessing.
  4. Receipt and verify. The outcome is a receipt, and anyone can replay the audit trail and check the hash chain from the public export.
sequenceDiagram
  autonumber
  actor B as Bidder
  participant G as GAVEL server
  participant P as PayPal sandbox
  B->>G: Join and pick a ceiling of $500
  G->>P: Create order, intent AUTHORIZE
  B->>P: Approve
  P-->>G: Authorization: $500 held, not charged
  B->>G: Bid $350
  G->>G: Engine decides, ledger appends a hash-chained event
  Note over G: Hammer: the $350 bid wins
  G->>P: Capture $350 with final_capture
  G->>P: Void every other hold
  P-->>G: Webhooks confirm each step
  G->>G: Journal closes, audit trail is sealed
Loading
Stage Page
Hold Registration and holds
Bid Bid lifecycle
Hammer Auction states
Settle Settlement saga
Verify Engine and ledger

Auction engine

English ascending auction with ceilings and soft close. A deterministic core (decide, evolve, replay) with no Node built-ins, so the same events always give the same result.

Hash-chained ledger

Every event is linked to the one before it. A redacted public export and a verifier detect an edited chain; a cut tail shows as not closed and is proven only against a head hash published elsewhere.

Settlement saga

Truth check at PayPal, capture of the winning price, bounded concurrent voids, a journal, and resume after a crash.

PayPal holds and webhooks

Holds on PayPal Orders v2 and Payments v2 with the JS SDK v6. Webhooks are signature-verified and de-duplicated.

Voice bidding

Deepgram and Groq speech-to-text with failover, a rule parser, and a confirm prompt for every spoken bid. Typed and QR bids work without it.

Replay and testing

A replay player for recorded auctions, a built-in fake PayPal for offline tests, and a scenario DSL with property tests that print replayable seeds.
The Scoreboard interface, line by line

The web app (packages/web) uses the Scoreboard design: flat panels, hard shadows, big numerals (docs/DESIGN.md). Each line is covered by unit, component or browser tests that run in CI.

  • Hold button. Press and hold for 3 seconds to approve a ceiling, or to hammer a lot on the console; release cancels. Keyboard users hold Space or Enter. Approving a ceiling also has a two-tap alternative; the console hammer does not.
  • Price roll. Prices are integer cents in tabular numerals, and only the changed digits roll. Reduced motion swaps the value at once.
  • Hold card. Hatched means held, solid means charged, hollow means released, always with a text status and a hide-amount toggle.
  • Ceiling slider and join code input. Snapping ticks and full keyboard control; one slot per character with paste that drops a GVL- prefix.
  • Alerts. Outbid, win and sold alerts on the bidder phone and a gavel sound on the projector, with a mute toggle.
  • Hold explainer. A help button opens a sheet that explains the hold. Nothing opens over the page by itself.
  • Fundraiser thermometer. The projector screen shows a goal bar when the auctioneer sets a goal. Only captured money counts as raised.
  • Shareable receipt. A receipt can mint a link with a QR code and a copy button, and has a print layout.
  • Judge rooms. With JUDGE_ROOMS=true, "Start a demo auction" opens a key-less room on the PayPal sandbox (capped, rate limited, switchable off at runtime).

See it run

Still screenshots of the current app at gavel.dualmindlab.tech (cream and ink interface), taken from a sandbox demo room where the hold is a simulated demo hold, not a PayPal login. The app shows its own sandbox banner.

Screenshot of the current hub: a demo room with the six character room code and a QR code, and buttons to open the screen, the console and a bidder.
Start a demo room: the hub shows the room code and the QR to scan.
Screenshot of the current bidder screen on a phone: the bidder holds a ceiling and the screen reads YOU LEAD.
The bidder phone: a hold in place and the screen reads YOU LEAD.
Screenshot of the current auctioneer console desk with the live bids and the hold-to-hammer button.
The console desk: hold the button to hammer.
Screenshot of the current big screen after the hammer: sold, with the join QR code above the latest bids list.
The big screen: sold, with the QR above the latest bids.
Screenshot of the current bidder receipt with the amounts, a current date, a short share link and a QR code.
The receipt, with a short share link and QR.
Screenshot of the current ledger page with the hash chain verified.
The ledger: the hash chain verifies.

Tech stack and sponsors

Layer What is used
Language TypeScript (strict) in an npm-workspaces monorepo on Node 22; a Python reference implementation for differential tests
Web app React and Vite, hosted on a Cloudflare Worker with static assets
API and realtime One Node host with HTTP routes and a room WebSocket gateway, hosted on Render
Payments PayPal Orders v2 and Payments v2, JS SDK v6, signature-verified webhooks; a built-in fake PayPal for offline tests
Auction core Pure decide, evolve and replay functions and a hash-chained ledger
Voice Deepgram and Groq speech-to-text with failover, a rule parser, and a confirm prompt for every spoken bid
Tables AG Grid Community for the ledger, bids and holds
Docs Fumadocs on a Next.js static export, hosted on Cloudflare, with a glossary and a guided tour
Checks GitHub Actions: tests, type checks, lint, scenario and property tests, sandbox gates, docs build
GAVEL architecture. A Cloudflare Worker serves the web app to the browser. The browser sends holds and bids to the Render API. The API holds, captures and voids through PayPal sandbox, which sends signed webhooks back. The API appends every step to a hash-chained ledger, and a receipt is issued that anyone can verify.
Partner How GAVEL uses it
PayPal Orders v2 with intent AUTHORIZE, Payments v2 (authorize, capture, void, reauthorize), webhook signature verification and JS SDK v6, all on the sandbox. Gates G0, G1, G2, G3 and G4 PASS
Cloudflare The web app runs as a Worker (gavel-web) and the docs site is deployed to Cloudflare; both serve the custom domains with security headers (checked on 9 Nov)
Render One Node web service on the starter plan, always on, with a 1 GB persistent disk at /var/data for the ledger, room log, settlement journals and hold records; render.yaml is the blueprint (hosting write-up)
AG Grid Community edition (MIT): the audit ledger, console bid history and the holds tables, with sorting, filters kept in the page link, CSV export of what you see, and a Verify chain button that re-hashes the sealed ledger in the browser (a check of the public export; audit-page rows are not sealed, so they have no chain status); lazy-loaded, so the landing and bidder pages do not carry it (docs/AG-GRID.md). Try it on the /ledger page
APIMatic The OpenAPI 3.1 spec of the host API (openapi/gavel.yaml) is linted with Spectral in CI and checked against the server router; TypeScript, Python and C# SDKs (gavel-sdk 0.0.5, beta) generated from it are in sdks/ and published as the GitHub release sdk-v0.0.5 (docs/API.md)
Hugging Face Five small datasets and a read-only Evidence Explorer Space, each labelled real sandbox, simulated or generated speech (collection)
Package Purpose
packages/shared Money in integer cents, ids, wire types, replay bundle format
packages/engine Pure auction core and hash-chained ledger
packages/payments Hold service, settlement saga, webhook verification, fake PayPal, gate scripts
packages/voice Audio capture, speech-to-text clients, bid parser, decision step
packages/server Single-process host: HTTP routes, room runtime, settlement scheduling, file stores
packages/e2e Scenario DSL, runner and end-to-end specs
packages/web Browser client (React and Vite)

Other folders: docs/ (gates, judge paths, evidence, submission), docsite/ (the docs website), openapi/, hf/ and scripts/hf/ (Hugging Face Space and dataset builds), reference/python/, infra/ and render.yaml, etc/ (API reports). Diagram and details: docs/submission/ARCHITECTURE.md and the system architecture page.

Evidence and gates

A gate is a question answered by a recorded run. G0 to G4 ran against the real PayPal sandbox and G5 is measured on speech clips. Source of truth: docs/GATES.md, with redacted evidence in docs/evidence/. Behaviour no passed gate covers is exercised against the project's own fake PayPal.

Gate Question Result What it shows
G0 Sandbox app and buyer accounts work PASS Token, scopes and an AUTHORIZE order; re-run on 9 Nov (G0)
G1 Partial capture and release of the remainder PASS Authorize 500.00, capture 350.00 with final_capture: the authorization reads CAPTURED for two PayPal-account buyers, and a later void answers 422 PREVIOUSLY_CAPTURED. The release of the remainder is inferred, not read from a balance
G2 Card and guest AUTHORIZE PASS Wallet and guest card both authorized in PayPal JS SDK v6
G3 Honor period, validity and reauthorize PASS A real probe from 7 Nov 03:06 UTC: capture of 1.00 and reauthorize accepted at 3.5, 4 and 5 days (wallet buyer, sandbox; run)
G4 Webhook signature verification on real events PASS 6 real deliveries verified by PayPal; rejection of a tampered event is covered against the fake PayPal
G5 Speech-to-text accuracy on noisy bids TESTED Wrong accept 0.000 on 24 clips in each of two sets (tuned on them); 0.058 (Groq) and 0.092 (Deepgram) on a held-out noisy set of 120 clips. Every spoken bid goes through the confirm prompt

Open data

Five small datasets and a read-only Evidence Explorer Space are on Hugging Face, each labelled for what it is. The speech, simulation and trace sets use generated audio, a fake clock and scripted auctions by design: GAVEL does not collect real people's data.

Dataset Label
gavel-gates real sandbox, speech clips, G3 passed
gavel-latency real sandbox, small n
gavel-sim-30d simulated, fake clock
gavel-stt-bids speech clips
gavel-audit-demo simulated, fake PayPal

Space: gavel-evidence-explorer. How they are built: docs/HF_COLLECTION.md.

Run it locally

Needs Node 22 and npm. No PayPal account is needed for the default run.

npm ci
PUBLIC_URL=http://localhost:8080 TOKEN_SECRET="$(openssl rand -hex 16)" ADMIN_KEY="$(openssl rand -hex 12)" \
  PAYMENTS=fake PAYPAL_ENV=sandbox npm start -w @gavel/server

The generated values are 32 and 24 hex characters, the minimum lengths the server accepts for TOKEN_SECRET and ADMIN_KEY (waived only when NODE_ENV=test). With PAYMENTS=fake the server uses the built-in fake PayPal and needs no network access; production mode refuses fake payments. All settings: packages/server/README.md.

To see the interface without a server, copy the web settings once and start the web dev server:

cp packages/web/.env.example packages/web/.env.local
npm run dev -w @gavel/web

Then open /r/demo/screen?scripted=1. The flag plays a recorded scenario in the browser and makes no PayPal calls; /r/demo/bid?scripted=1&at=3000 and the console and receipt routes work the same way. Only development builds honour scripted=1; the hosted /demo/scripted page plays the recorded room in every build.

Use the real PayPal sandbox

Set PAYMENTS=sandbox and provide PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET and PAYPAL_WEBHOOK_ID. The names are in .env.example; keep the values in your local .env and never commit them. Nothing loads that file by itself: delete the lines you do not fill in (empty values count as unset), then run set -a; source .env; set +a before starting the server, or pass the variables inline. docs/RUNBOOK-GATES.md shows how each sandbox run is recorded.

Tests and quality checks

Every pull request runs tests, type checks, lint and the other quality checks in GitHub Actions (ci.yml). The same commands work locally:

Command What it runs
npm test Unit tests for every package
npm run test:property Property tests; each run prints its seed, GAVEL_PROPERTY_SEED=<n> replays it
npm run typecheck Strict TypeScript across the workspace
npm run lint ESLint with zero warnings allowed

Call the API

With a judge key (gvl_judge_<id>_<secret>) you can open a sandbox room, bid, hammer and read the ledger with plain HTTP. The key opens judge rooms only, never an operator route, and PayPal stays in the sandbox. Each key has its own room cap, hourly cap and expiry. A personal key stops on 30 November 2026 by default; the one shared judging key does not expire, can be revoked, and is the one judges receive in the Devpost testing instructions (added there by hand; it is never in this repository). You do not need a key to try GAVEL: a keyless judge room on /try works without one.

API=https://api.gavel.dualmindlab.tech
curl -s -X POST $API/api/judge/rooms -H "x-judge-key: $JUDGE_KEY" -H 'content-type: application/json' -d '{"title":"My lot"}'
curl -s -X POST $API/api/judge/rooms/$ID/bids -H "authorization: Bearer $SESSION" -H 'content-type: application/json' -d '{"amount":1500}'

The whole path, with a "Try it" panel, is on the docs page Call the API as a judge. The operator makes keys with node scripts/make-judge-key.mjs. The spec is at openapi/gavel.yaml and rendered in the API reference.

Limits and next steps

  • PayPal sandbox only: no live money and no live human test. The server kill ran on a CI runner, not the deployed host.
  • G3 (honor period and reauthorize) passed for a wallet buyer and a 1.00 partial capture only; G5 voice accuracy is tested on voice clips only, which is why every spoken bid needs a confirm.
  • Still open: the settlement latency decision, an independent security review of the judge-room items and a manual accessibility pass. Owners and dates are in docs/LIMITATIONS.md.

Security and data notes

GAVEL talks to the PayPal sandbox only. No live PayPal call is made and no real money moves. Do not put real card numbers, real accounts or personal data into the demo. Secrets are never committed; report vulnerabilities as described in SECURITY.md. The open datasets contain no real people's data, and a privacy and secret scan runs on every dataset build (docs/PRIVACY.md).

Documentation

Read this To learn
Docs site Diagrams, proof pages and the judge paths
Guided tour Ten steps from what GAVEL is to its limits
Judge walkthrough A short path through the code and the evidence
Gate results What each sandbox run proved
Limits and next steps What is measured today and what comes next
Demo guide What you can try today and what to expect
API reference The OpenAPI spec, auth, errors, rate limits
Architecture How the packages fit together
Design system, AG Grid tables The Scoreboard interface and its grids
Decisions, plan Why the design is the way it is
Deploy, gate runbook Hosting the server, running a gate yourself
Changelog What changed, day by day

Package guides: server, voice, engine, web.

Contributing

Read CONTRIBUTING.md and the code of conduct. Work goes through branches and pull requests, and the pull request template lists the checks.

Team

Built by Harsh Bhanushali and Dhairya Patel for the PayPal Hackathon 2026. Product, engine, payments, voice, web app, docs and evidence are all in this repository.

License

MIT

Web app  |  Docs  |  Source  |  Open data
PayPal sandbox only. Bids are held, not charged.

About

Live auction where every bid is a PayPal AUTHORIZE hold: only the winning price is captured, the rest are voided. Crash-safe settlement saga and hash-chained audit trail. PayPal sandbox only.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages