Skip to content

Commit 132da06

Browse files
stackdumpclaude
stackdump
and
claude
committed
Rewrite README for ZK voting focus
Lead with anonymous voting, add poll API docs, sealed results explanation, wallet auth section, deploy bundle, and CI badge. Keep ERC templates and .btw DSL as secondary sections. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent a2ab83d commit 132da06

1 file changed

Lines changed: 107 additions & 90 deletions

File tree

‎README.md‎

Lines changed: 107 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -1,106 +1,102 @@
11
# bitwrap
22

3+
[![CI](https://github.com/stackdump/bitwrap-io/actions/workflows/ci.yml/badge.svg)](https://github.com/stackdump/bitwrap-io/actions/workflows/ci.yml)
34
[![jsDelivr](https://data.jsdelivr.com/v1/package/gh/stackdump/bitwrap-io/badge)](https://www.jsdelivr.com/package/gh/stackdump/bitwrap-io)
45

5-
**Petri nets as ZK containers.**
6+
**Anonymous on-chain voting with ZK proofs.**
67

7-
bitwrap is a tool for modeling state machines as Petri nets and compiling them into ZK proofs and Solidity smart contracts. One model produces the editor view, the circuit constraints, and the contract code.
8+
Create polls where every vote is backed by a Groth16 proof. No one sees how you voted. Everyone can verify the result is correct. Deploy to any EVM chain.
89

9-
**[bitwrap.io](https://bitwrap.io)** | **[Editor](https://app.bitwrap.io)** | **[Remix Plugin](https://solver.bitwrap.io)**
10+
**[bitwrap.io](https://bitwrap.io)** | **[Polls](https://bitwrap.io/poll)** | **[Editor](https://app.bitwrap.io)** | **[Docs](https://book.pflow.xyz)**
1011

11-
## Why Petri nets?
12+
## Quick start
1213

13-
A Petri net is a directed bipartite graph: places hold tokens, transitions move them, arcs define the rules. This structure is simple enough to draw on a napkin but formal enough to prove properties about.
14+
```bash
15+
git clone https://github.com/stackdump/bitwrap-io.git
16+
cd bitwrap-io
17+
make run # serves on :8088
18+
```
1419

15-
Every token standard is a Petri net. ERC-20 has three places (balances, allowances, totalSupply) and five transitions (transfer, approve, transferFrom, mint, burn). The arcs encode which maps get decremented and incremented. Guards express the `require` statements. Invariants express conservation laws.
20+
Three API calls to create a poll, cast a vote, and read results:
1621

17-
The same model that a human reads in the editor is the same model that generates the Solidity contract and the same model that compiles to ZK circuit constraints. There's no translation layer, no impedance mismatch, no spec-to-implementation gap.
22+
```bash
23+
# Create a poll (requires wallet signature)
24+
curl -X POST https://api.bitwrap.io/api/polls \
25+
-H "Content-Type: application/json" \
26+
-d '{"title":"Board Vote","choices":["Approve","Reject","Abstain"],...}'
27+
28+
# Cast a ZK-proven vote
29+
curl -X POST https://api.bitwrap.io/api/polls/{id}/vote \
30+
-H "Content-Type: application/json" \
31+
-d '{"nullifier":"0x...","voteCommitment":"0x...","proof":"..."}'
32+
33+
# Get results (sealed while active, visible when closed)
34+
curl https://api.bitwrap.io/api/polls/{id}/results
35+
```
1836

19-
## Two angles
37+
## How it works
2038

21-
**Model to proof.** Petri net structure maps directly to ZK circuit constraints. Guards become arithmetic checks (`balance >= amount` becomes a range proof). Arc weights become balance equations. Invariants become circuit assertions. The topology of the net *is* the specification of the circuit.
39+
**Vote.** Voters register with a commitment hash. When they cast a ballot, a nullifier (derived from `mimcHash(voterSecret, pollId)`) prevents double-voting without revealing identity.
2240

23-
**Verifiable execution.** Run a Petri net state machine where each transition firing produces a Groth16 proof. The proof attests that the state change was valid without revealing the full state. Token movements are private but provably correct. The model becomes its own audit trail.
41+
**Prove.** Each vote generates a Groth16 proof attesting the voter is registered and the ballot is valid — without revealing the choice. The circuit verifies Merkle inclusion in the voter registry, nullifier binding, and vote range.
2442

25-
## What it does
43+
**Tally.** Results stay sealed until the poll closes. Once closed, the final tally is publicly verifiable — anyone can audit the proofs without accessing individual ballots.
2644

27-
- **Visual editor** — draw places, transitions, and arcs in the browser. Models are stored as content-addressed JSON-LD (CID = hash of canonicalized RDF).
28-
- **ERC templates** — start from ERC-20, ERC-721, ERC-1155, or ERC-4626. Each template is a complete Petri net with guards, arcs, and events already wired.
29-
- **Solidity generation** — produce a deployable `.sol` contract from any template. Guards become `require` statements, arcs become storage operations, events are emitted automatically.
30-
- **ZK circuits** — Groth16 circuits for each transition type (transfer, mint, burn, approve). Merkle proofs verify state inclusion without revealing balances.
31-
- **Remix IDE plugin** — generate and deploy contracts directly inside the Remix editor at [solver.bitwrap.io](https://solver.bitwrap.io).
32-
- **`.btw` DSL** — a compact schema language for defining Petri net models with registers, events, guards, and arc syntax.
45+
### Sealed results
3346

34-
## .btw schema language
47+
While a poll is active, the results endpoint only returns the vote count. Tallies, nullifiers, and commitments are hidden to prevent observers from diffing the tally after each vote and correlating timing to de-anonymize voters. Full results are exposed only after the poll is closed.
3548

36-
```
37-
schema ERC20 {
38-
version "1.0.0"
39-
40-
register ASSETS.AVAILABLE map[address]uint256 observable
41-
register ASSETS.TOTAL_SUPPLY uint256 observable
42-
43-
event TransferBalanceChange {
44-
from: address indexed
45-
to: address indexed
46-
amount: uint256
47-
}
49+
### Wallet-native auth
4850

49-
fn(transfer) {
50-
var from address
51-
var to address
52-
var amount amount
51+
Poll creation requires an EIP-191 `personal_sign` signature from MetaMask or any Ethereum wallet. Voting secrets can be derived from wallet signatures, making the nullifier deterministic per voter per poll — no accounts, no passwords.
5352

54-
require(ASSETS.AVAILABLE[from] >= amount && amount > 0)
55-
@event TransferBalanceChange
53+
## What it does
5654

57-
ASSETS.AVAILABLE[from] -|amount|> transfer
58-
transfer -|amount|> ASSETS.AVAILABLE[to]
59-
}
55+
- **ZK voting** — anonymous polls with nullifier-based double-vote prevention and on-chain proof verification. Sealed results prevent vote-timing correlation.
56+
- **Visual editor** — draw places, transitions, and arcs in the browser. Models are stored as content-addressed JSON-LD.
57+
- **Solidity generation** — produce deployable contracts and Foundry test suites from any template.
58+
- **ZK circuits** — Groth16 circuits for transfer, mint, burn, approve, transferFrom, vestClaim, and voteCast. Merkle proofs verify state inclusion.
59+
- **Deploy bundle** — download a complete Foundry project (`BitwrapZKPoll.sol` + `Verifier.sol` + tests + deploy script) from `GET /api/bundle/vote`.
60+
- **ERC templates** — start from ERC-20, ERC-721, ERC-1155, or a Vote template. Each is a complete Petri net with guards, arcs, and events.
61+
- **`.btw` DSL** — a compact schema language for defining Petri net models.
62+
- **Remix IDE plugin** — generate and deploy contracts inside Remix at [solver.bitwrap.io](https://solver.bitwrap.io).
6063

61-
fn(mint) {
62-
var to address
63-
var amount amount
64+
## API
6465

65-
require(amount > 0)
66+
### Polls
6667

67-
mint -|amount|> ASSETS.AVAILABLE[to]
68-
mint -|amount|> ASSETS.TOTAL_SUPPLY
69-
}
70-
}
68+
```
69+
POST /api/polls Create poll (wallet signature required)
70+
GET /api/polls List polls
71+
GET /api/polls/{id} Get poll details
72+
POST /api/polls/{id}/vote Cast ZK-proven vote
73+
POST /api/polls/{id}/close Close poll (creator signature required)
74+
POST /api/polls/{id}/reveal Reveal vote choice (post-close)
75+
GET /api/polls/{id}/results Poll results (sealed while active)
7176
```
7277

73-
Compile to JSON schema: `bitwrap -compile token.btw`
74-
75-
## Quick start
78+
### Models & templates
7679

77-
```bash
78-
git clone https://github.com/stackdump/bitwrap-io.git
79-
cd bitwrap-io
80-
make run # serves on :8088
80+
```
81+
POST /api/save Save JSON-LD model, returns {"cid": "..."}
82+
GET /o/{cid} Load model by CID
83+
GET /img/{cid}.svg Render model as SVG
84+
POST /api/svg Generate SVG from posted JSON-LD
85+
GET /api/templates List ERC templates
86+
GET /api/templates/{id} Get full template model
87+
POST /api/solgen Generate Solidity from template
88+
POST /api/testgen Generate Foundry tests from template
89+
POST /api/compile Compile .btw DSL to schema JSON
90+
GET /api/bundle/{template} Download Foundry project (ZIP)
8191
```
8292

83-
Open [localhost:8088](http://localhost:8088) for the landing page, [localhost:8088/editor](http://localhost:8088/editor) for the visual editor.
84-
85-
## API
93+
### ZK prover
8694

8795
```
88-
GET / Landing page
89-
GET /editor Visual Petri net editor
90-
GET /remix Remix IDE plugin
91-
92-
POST /api/save Save JSON-LD model, returns {"cid": "..."}
93-
GET /o/{cid} Load model by CID
94-
GET /img/{cid}.svg Render model as SVG
95-
POST /api/svg Generate SVG from posted JSON-LD
96-
97-
GET /api/templates List ERC templates
98-
GET /api/templates/{id} Get full template model (states, actions, arcs)
99-
POST /api/solgen Generate Solidity from template ID
100-
POST /api/compile Compile .btw DSL source to schema JSON
101-
102-
GET /api/circuits List available ZK circuits
103-
POST /api/prove Submit witness for ZK proof generation
96+
GET /api/circuits List available circuits
97+
POST /api/prove Submit witness for proof generation
98+
GET /api/vk/{circuit} Download verifying key (binary)
99+
GET /api/vk/{circuit}/solidity Download Solidity verifier contract
104100
```
105101

106102
## CDN
@@ -111,15 +107,15 @@ Client-side modules are available via jsDelivr:
111107
<script type="module">
112108
import { mimcHash } from 'https://cdn.jsdelivr.net/gh/stackdump/bitwrap-io@latest/public/mimc.js';
113109
import { MerkleTree } from 'https://cdn.jsdelivr.net/gh/stackdump/bitwrap-io@latest/public/merkle.js';
114-
import { buildTransferWitness } from 'https://cdn.jsdelivr.net/gh/stackdump/bitwrap-io@latest/public/witness-builder.js';
110+
import { buildVoteCastWitness } from 'https://cdn.jsdelivr.net/gh/stackdump/bitwrap-io@latest/public/witness-builder.js';
115111
</script>
116112
```
117113

118114
| Module | Description |
119115
|--------|-------------|
120116
| `mimc.js` | MiMC-BN254 hash (pure BigInt, zero deps) |
121-
| `merkle.js` | Fixed-depth binary Merkle tree |
122-
| `witness-builder.js` | Witness builders for all 6 ZK circuits |
117+
| `merkle.js` | Fixed-depth binary Merkle tree with proof generation |
118+
| `witness-builder.js` | Witness builders for all 7 ZK circuits |
123119
| `petri-view.js` | `<petri-view>` web component for Petri net editing |
124120

125121
## Architecture
@@ -129,29 +125,50 @@ Single Go binary. Vanilla JS frontend. No npm, no React, no build step.
129125
```
130126
cmd/bitwrap/ Entry point with -port, -data, -compile flags
131127
dsl/ .btw lexer, parser, AST, builder
132-
erc/ ERC token standard templates (020, 721, 1155, 4626)
128+
erc/ ERC token standard templates (020, 721, 1155, vote)
133129
prover/ ZK circuits (Groth16 via gnark)
134-
solidity/ Solidity contract generation
130+
solidity/ Solidity contract + test generation
131+
arc/ Arc-level execution (MiMC Merkle state trees, firing)
135132
internal/
136-
server/ HTTP handlers
133+
server/ HTTP handlers + poll lifecycle + wallet auth
137134
petri/ Petri net model types + execution engine
138135
metamodel/ Schema types (states, actions, arcs, events, constraints)
139136
seal/ CID computation (JSON-LD canonicalization via URDNA2015)
140-
store/ Filesystem storage
137+
store/ Filesystem storage (polls, votes, events)
141138
svg/ SVG rendering
142-
arc/ Arc-level execution (Merkle state, firing)
143-
static/ Embedded public files (go:embed)
139+
public/ Frontend JS/CSS/HTML (go:embed)
144140
```
145141

146-
## Subdomains
142+
## .btw schema language
143+
144+
```
145+
schema ERC20 {
146+
version "1.0.0"
147+
148+
register ASSETS.AVAILABLE map[address]uint256 observable
149+
register ASSETS.TOTAL_SUPPLY uint256 observable
150+
151+
event TransferBalanceChange {
152+
from: address indexed
153+
to: address indexed
154+
amount: uint256
155+
}
156+
157+
fn(transfer) {
158+
var from address
159+
var to address
160+
var amount amount
161+
162+
require(ASSETS.AVAILABLE[from] >= amount && amount > 0)
163+
@event TransferBalanceChange
164+
165+
ASSETS.AVAILABLE[from] -|amount|> transfer
166+
transfer -|amount|> ASSETS.AVAILABLE[to]
167+
}
168+
}
169+
```
147170

148-
| URL | Purpose |
149-
|-----|---------|
150-
| [bitwrap.io](https://bitwrap.io) | Landing page |
151-
| [app.bitwrap.io](https://app.bitwrap.io) | Visual editor |
152-
| [api.bitwrap.io](https://api.bitwrap.io) | API |
153-
| [solver.bitwrap.io](https://solver.bitwrap.io) | Remix IDE plugin |
154-
| [prover.bitwrap.io](https://prover.bitwrap.io) | ZK prover |
171+
Compile to JSON: `bitwrap -compile token.btw`
155172

156173
## License
157174

0 commit comments

Comments
 (0)