@libid/contracts 0.17.0 → 0.18.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +108 -47
- package/dist/abis/bindErrors.d.ts +714 -0
- package/dist/abis/bindErrors.d.ts.map +1 -0
- package/dist/abis/bindErrors.js +955 -0
- package/dist/abis/bindErrors.js.map +1 -0
- package/dist/abis/ceremonyPayloads.d.ts +118 -0
- package/dist/abis/ceremonyPayloads.d.ts.map +1 -0
- package/dist/abis/ceremonyPayloads.js +154 -0
- package/dist/abis/ceremonyPayloads.js.map +1 -0
- package/dist/abis/ceremonyProofVerifier.d.ts +6 -6
- package/dist/abis/ceremonyProofVerifier.js +6 -6
- package/dist/abis/ceremonyProofVerifier.js.map +1 -1
- package/dist/abis/handleEscrow.d.ts +56 -16
- package/dist/abis/handleEscrow.d.ts.map +1 -1
- package/dist/abis/handleEscrow.js +71 -19
- package/dist/abis/handleEscrow.js.map +1 -1
- package/dist/abis/honkVerifierErrors.d.ts +54 -0
- package/dist/abis/honkVerifierErrors.d.ts.map +1 -0
- package/dist/abis/honkVerifierErrors.js +71 -0
- package/dist/abis/honkVerifierErrors.js.map +1 -0
- package/dist/abis/identityRegistry.d.ts +123 -157
- package/dist/abis/identityRegistry.d.ts.map +1 -1
- package/dist/abis/identityRegistry.js +150 -194
- package/dist/abis/identityRegistry.js.map +1 -1
- package/dist/abis/index.d.ts +3 -0
- package/dist/abis/index.d.ts.map +1 -1
- package/dist/abis/index.js +3 -0
- package/dist/abis/index.js.map +1 -1
- package/dist/calls/handleEscrow.d.ts +1 -0
- package/dist/calls/handleEscrow.d.ts.map +1 -1
- package/dist/calls/handleEscrow.js +7 -0
- package/dist/calls/handleEscrow.js.map +1 -1
- package/dist/calls/identityRegistry.d.ts +2 -1
- package/dist/calls/identityRegistry.d.ts.map +1 -1
- package/dist/calls/identityRegistry.js +9 -2
- package/dist/calls/identityRegistry.js.map +1 -1
- package/dist/ceremony/profiles.d.ts +38 -48
- package/dist/ceremony/profiles.d.ts.map +1 -1
- package/dist/ceremony/profiles.js +31 -36
- package/dist/ceremony/profiles.js.map +1 -1
- package/dist/identity/index.d.ts +1 -3
- package/dist/identity/index.d.ts.map +1 -1
- package/dist/identity/index.js +5 -11
- package/dist/identity/index.js.map +1 -1
- package/dist/identity/resolve.d.ts +6 -8
- package/dist/identity/resolve.d.ts.map +1 -1
- package/dist/identity/resolve.js +53 -86
- package/dist/identity/resolve.js.map +1 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -4
- package/dist/index.js.map +1 -1
- package/dist/payloads.d.ts +124 -0
- package/dist/payloads.d.ts.map +1 -0
- package/dist/payloads.js +59 -0
- package/dist/payloads.js.map +1 -0
- package/dist/platforms/handle.d.ts +11 -0
- package/dist/platforms/handle.d.ts.map +1 -0
- package/dist/platforms/handle.js +29 -0
- package/dist/platforms/handle.js.map +1 -0
- package/dist/platforms/id.d.ts +8 -0
- package/dist/platforms/id.d.ts.map +1 -0
- package/dist/platforms/id.js +21 -0
- package/dist/platforms/id.js.map +1 -0
- package/dist/platforms/index.d.ts +5 -0
- package/dist/platforms/index.d.ts.map +1 -0
- package/dist/platforms/index.js +8 -0
- package/dist/platforms/index.js.map +1 -0
- package/dist/platforms/node.d.ts +4 -0
- package/dist/platforms/node.d.ts.map +1 -0
- package/dist/platforms/node.js +36 -0
- package/dist/platforms/node.js.map +1 -0
- package/dist/platforms/platforms.d.ts +39 -0
- package/dist/platforms/platforms.d.ts.map +1 -0
- package/dist/platforms/platforms.js +90 -0
- package/dist/platforms/platforms.js.map +1 -0
- package/package.json +11 -3
- package/src/abis/bindErrors.ts +957 -0
- package/src/abis/ceremonyPayloads.ts +156 -0
- package/src/abis/ceremonyProofVerifier.ts +6 -6
- package/src/abis/handleEscrow.ts +71 -19
- package/src/abis/honkVerifierErrors.ts +73 -0
- package/src/abis/identityRegistry.ts +150 -194
- package/src/abis/index.ts +3 -0
- package/src/calls/handleEscrow.ts +12 -0
- package/src/calls/identityRegistry.ts +14 -2
- package/src/ceremony/profiles.ts +53 -65
- package/src/identity/index.ts +5 -11
- package/src/identity/resolve.ts +71 -118
- package/src/index.ts +3 -4
- package/src/payloads.ts +90 -0
- package/src/platforms/handle.ts +36 -0
- package/src/platforms/id.ts +26 -0
- package/src/platforms/index.ts +8 -0
- package/src/platforms/node.ts +41 -0
- package/src/platforms/platforms.ts +114 -0
- package/dist/identity/handle.d.ts +0 -22
- package/dist/identity/handle.d.ts.map +0 -1
- package/dist/identity/handle.js +0 -140
- package/dist/identity/handle.js.map +0 -1
- package/dist/identity/handleVectors.d.ts +0 -50
- package/dist/identity/handleVectors.d.ts.map +0 -1
- package/dist/identity/handleVectors.js +0 -89
- package/dist/identity/handleVectors.js.map +0 -1
- package/dist/identity/node.d.ts +0 -5
- package/dist/identity/node.d.ts.map +0 -1
- package/dist/identity/node.js +0 -19
- package/dist/identity/node.js.map +0 -1
- package/src/identity/handle.ts +0 -176
- package/src/identity/handleVectors.ts +0 -104
- package/src/identity/node.ts +0 -28
package/README.md
CHANGED
|
@@ -1,42 +1,47 @@
|
|
|
1
1
|
# @libid/contracts
|
|
2
2
|
|
|
3
3
|
Typed, viem-ready ABIs for the libid identity stack (NotaryService,
|
|
4
|
-
CeremonyProofVerifier, GoogleJwtRoots, IdentityRegistry,
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
`as const satisfies Abi`, so viem infers argument and return types
|
|
12
|
-
each call builder
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
`
|
|
4
|
+
CeremonyProofVerifier, GoogleJwtRoots, IdentityRegistry, HandleEscrow,
|
|
5
|
+
HandleResolver, LibidFactory, WTIA9), the errors a bind can revert with, a call
|
|
6
|
+
builder for every state-changing function, and the identity helper layer:
|
|
7
|
+
handle normalization, node derivation and resolution.
|
|
8
|
+
|
|
9
|
+
`src/abis/` and `src/calls/` are generated from the forge artifacts
|
|
10
|
+
(`solidity/out`) by `scripts/codegen.mjs` and are not committed. Each ABI is
|
|
11
|
+
exported `as const satisfies Abi`, so viem infers argument and return types,
|
|
12
|
+
and each call builder takes its arguments from that ABI.
|
|
13
|
+
`scripts/regen-identity-handles.py` generates the platform table
|
|
14
|
+
(`src/platforms/platforms.ts`) and the test vectors (`src/platforms/vectors.ts`,
|
|
15
|
+
not published) from the pinned libID-circuits release's `platforms.json` and
|
|
16
|
+
`handles.json`, vendored into `solidity/contracts/circuits/`.
|
|
17
17
|
|
|
18
18
|
```sh
|
|
19
19
|
pnpm add @libid/contracts viem
|
|
20
20
|
```
|
|
21
21
|
|
|
22
|
-
`viem` is an optional peer. The root export, `calls` and `identity` import it
|
|
23
|
-
|
|
24
|
-
can leave it out.
|
|
22
|
+
`viem` is an optional peer. The root export, `calls` and `identity` import it.
|
|
23
|
+
`ceremony` and `platforms` load without it.
|
|
25
24
|
|
|
26
25
|
## Reading a contract with viem
|
|
27
26
|
|
|
28
27
|
```ts
|
|
29
28
|
import { createPublicClient, http } from 'viem'
|
|
30
29
|
import { googleJwtRootsAbi, identityRegistryAbi } from '@libid/contracts/abis'
|
|
30
|
+
import { handleNode, idNode, PLATFORM_X_KEY, platformId } from '@libid/contracts/identity'
|
|
31
31
|
|
|
32
32
|
const client = createPublicClient({ transport: http(RPC_URL) })
|
|
33
33
|
|
|
34
|
-
// Fully typed: viem infers the argument and return types from the ABI.
|
|
35
|
-
|
|
34
|
+
// Fully typed: viem infers the argument and return types from the ABI. The
|
|
35
|
+
// handle and the id are hashed here, so only their nodes reach the RPC.
|
|
36
|
+
const [holder, idAgrees] = await client.readContract({
|
|
36
37
|
address: IDENTITY_REGISTRY,
|
|
37
38
|
abi: identityRegistryAbi,
|
|
38
|
-
functionName: '
|
|
39
|
-
args: [
|
|
39
|
+
functionName: 'resolveHandleNodeAndId',
|
|
40
|
+
args: [
|
|
41
|
+
platformId(PLATFORM_X_KEY),
|
|
42
|
+
handleNode(PLATFORM_X_KEY, 'alice'),
|
|
43
|
+
idNode(PLATFORM_X_KEY, '42'),
|
|
44
|
+
],
|
|
40
45
|
})
|
|
41
46
|
|
|
42
47
|
// The two generations of Google's key set the list holds.
|
|
@@ -49,10 +54,9 @@ const [current, previous] = await client.readContract({
|
|
|
49
54
|
|
|
50
55
|
## Building a call
|
|
51
56
|
|
|
52
|
-
One builder per state-changing function, namespaced by contract
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
directly, batched, or through a smart wallet's `execute`.
|
|
57
|
+
One builder per state-changing function, namespaced by contract since names
|
|
58
|
+
like `initialize` repeat. A builder returns the call as data, to send directly,
|
|
59
|
+
batch, or wrap in a smart wallet's `execute`.
|
|
56
60
|
|
|
57
61
|
```ts
|
|
58
62
|
import { calls } from '@libid/contracts/calls'
|
|
@@ -79,6 +83,7 @@ const rotate = calls.googleJwtRoots.rotate(roots, fee, attestedData, proof)
|
|
|
79
83
|
import {
|
|
80
84
|
identitiesOf,
|
|
81
85
|
identityCount,
|
|
86
|
+
idNode,
|
|
82
87
|
platformId,
|
|
83
88
|
publishedHandleOf,
|
|
84
89
|
resolveHandle,
|
|
@@ -89,63 +94,119 @@ import {
|
|
|
89
94
|
const reader = { client, address: IDENTITY_REGISTRY }
|
|
90
95
|
const x = platformId(PLATFORM_X_KEY)
|
|
91
96
|
|
|
92
|
-
// The holder that last proved a handle, or null. Pass
|
|
93
|
-
//
|
|
94
|
-
const holder = await resolveHandle(reader, x, '
|
|
97
|
+
// The holder that last proved a handle, or null. Pass the text as typed: it is
|
|
98
|
+
// folded and hashed locally. Text nobody proved, such as `@alice`, answers null.
|
|
99
|
+
const holder = await resolveHandle(reader, x, 'Alice')
|
|
95
100
|
|
|
96
|
-
// Before sending funds:
|
|
97
|
-
const { idAgrees } = await resolveHandleAndId(reader, x, 'alice', '42')
|
|
101
|
+
// Before sending funds: is this id still the account that proved the handle?
|
|
102
|
+
const { idAgrees } = await resolveHandleAndId(reader, x, 'alice', idNode(PLATFORM_X_KEY, '42'))
|
|
98
103
|
|
|
99
104
|
// The handle a holder displays, forward-checked on chain.
|
|
100
105
|
const handle = await publishedHandleOf(reader, holder!, x)
|
|
101
106
|
|
|
102
107
|
// Every identity the holder proved, on every platform, a page at a time.
|
|
103
|
-
// Order is arbitrary
|
|
104
|
-
// read the count and the pages against one block when every identity matters.
|
|
108
|
+
// Order is arbitrary and shifts on removal: read the count and pages at one block.
|
|
105
109
|
const total = await identityCount(reader, holder!)
|
|
106
110
|
const identities = await identitiesOf(reader, holder!, 0n, 50n)
|
|
107
|
-
// [{ platformId: x,
|
|
111
|
+
// [{ platformId: x, idNode: '0x…', handleNode: '0x…', handleCurrent: true }, …]
|
|
112
|
+
// Nodes only; the handle text is on chain only when published.
|
|
108
113
|
```
|
|
109
114
|
|
|
110
115
|
## Binding an identity
|
|
111
116
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
An EOA sends
|
|
117
|
+
`bind` takes the platform, this chain's verifier version for it, the payload
|
|
118
|
+
the ceremony produced, and the handle to publish. The registry checks a
|
|
119
|
+
published handle against the node the proof bound. The value is what
|
|
120
|
+
`quoteBind` returns for the same pair. An EOA sends the call directly, a smart
|
|
121
|
+
wallet wraps it in its own execute:
|
|
116
122
|
|
|
117
123
|
```ts
|
|
118
124
|
import { calls } from '@libid/contracts/calls'
|
|
119
125
|
|
|
126
|
+
const github = platformId(PLATFORM_GITHUB_KEY)
|
|
120
127
|
const fee = await client.readContract({
|
|
121
128
|
address: IDENTITY_REGISTRY,
|
|
122
129
|
abi: identityRegistryAbi,
|
|
123
130
|
functionName: 'quoteBind',
|
|
124
|
-
args: [
|
|
131
|
+
args: [github, 1],
|
|
125
132
|
})
|
|
126
|
-
const call = calls.identityRegistry.bind(IDENTITY_REGISTRY, fee,
|
|
133
|
+
const call = calls.identityRegistry.bind(IDENTITY_REGISTRY, fee, github, 1, payload, '')
|
|
127
134
|
// call = { to, value, data } — sign and send from the address the payload names.
|
|
135
|
+
// The last argument is the handle to publish, or '' to keep the bind private;
|
|
136
|
+
// calls.identityRegistry.bindPrivately(IDENTITY_REGISTRY, fee, github, 1, payload) is the same with no handle.
|
|
128
137
|
```
|
|
129
138
|
|
|
139
|
+
The payload is one `abi.encode`d struct in the shape its Platform Verifier
|
|
140
|
+
decodes. `encodeTlsNotaryProof` builds the X and GitHub payload,
|
|
141
|
+
`encodeGoogleProof` the Google one:
|
|
142
|
+
|
|
143
|
+
```ts
|
|
144
|
+
import { encodeTlsNotaryProof } from '@libid/contracts'
|
|
145
|
+
|
|
146
|
+
const payload = encodeTlsNotaryProof({
|
|
147
|
+
ceremonyVersion: 1,
|
|
148
|
+
operationDomain, authorizationNonce, transactionData,
|
|
149
|
+
tokenSession, identitySession, // { attestedData, proof } each
|
|
150
|
+
idNode, handleNode,
|
|
151
|
+
proof,
|
|
152
|
+
})
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
A refused bind reverts with the error of whichever contract on its route
|
|
156
|
+
refused it: the registry, the Proof Verifier, a Platform Verifier, the Notary
|
|
157
|
+
Service or a Honk verifier. `bindErrorsAbi` carries all of them:
|
|
158
|
+
|
|
159
|
+
```ts
|
|
160
|
+
import { decodeErrorResult } from 'viem'
|
|
161
|
+
import { bindErrorsAbi } from '@libid/contracts/abis'
|
|
162
|
+
|
|
163
|
+
const { errorName, args } = decodeErrorResult({ abi: bindErrorsAbi, data: revertData })
|
|
164
|
+
// 'HandleNotProved', [disclosed, proved]: the handle bind disclosed is not the proved one.
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
The Honk verifiers raise errors such as `SumcheckFailed()` that their own ABI
|
|
168
|
+
omits. `honkVerifierErrorsAbi` declares them under bb's names, and
|
|
169
|
+
`bindErrorsAbi` includes it.
|
|
170
|
+
|
|
130
171
|
## Normalizing a handle locally
|
|
131
172
|
|
|
173
|
+
`@libid/contracts/platforms` holds the platform table, the checks the
|
|
174
|
+
circuits apply to handles and ids, and node derivation, and loads without viem.
|
|
175
|
+
`@libid/contracts/identity` re-exports it and adds the registry reads, which
|
|
176
|
+
need viem.
|
|
177
|
+
|
|
178
|
+
Only A–Z fold to a–z. Text no circuit hashes throws
|
|
179
|
+
`HandleError`: empty text, a byte outside printable ASCII, a quote, a
|
|
180
|
+
backslash, or more bytes than the circuit's buffer.
|
|
181
|
+
|
|
132
182
|
```ts
|
|
133
|
-
import { normalize, RULES_X, HandleError } from '@libid/contracts/
|
|
183
|
+
import { checkId, normalize, PLATFORM_X_KEY, RULES_X, HandleError } from '@libid/contracts/platforms'
|
|
134
184
|
|
|
135
|
-
normalize('
|
|
136
|
-
|
|
185
|
+
normalize('Alice_1', RULES_X) // 'alice_1'
|
|
186
|
+
normalize(' @Alice_1 ', RULES_X) // ' @alice_1 ': nothing is trimmed or stripped
|
|
187
|
+
normalize('Ali"ce', RULES_X) // throws HandleError: a quote is refused
|
|
188
|
+
checkId(PLATFORM_X_KEY, '2244994945') // passes; checkId(PLATFORM_X_KEY, 'x1') throws IdError
|
|
137
189
|
```
|
|
138
190
|
|
|
191
|
+
On chain only the fold runs; text the circuits refuse has no binding, so it
|
|
192
|
+
resolves to nobody.
|
|
193
|
+
|
|
139
194
|
## Deriving a handle node
|
|
140
195
|
|
|
141
|
-
|
|
196
|
+
A node is `SHA256(tag || value)`, as the platform's circuit outputs it: the
|
|
197
|
+
normalized handle under the handle tag, the id as the platform sent it under
|
|
198
|
+
the user-id tag. Nodes are unsalted, so anyone can test a guess against one.
|
|
199
|
+
Both functions take the platform key, not its id:
|
|
142
200
|
|
|
143
201
|
```ts
|
|
144
|
-
import {
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
const
|
|
148
|
-
|
|
202
|
+
import { checkId, handleNode, idNode, PLATFORM_GOOGLE_KEY } from '@libid/contracts/platforms'
|
|
203
|
+
|
|
204
|
+
// HandleEscrow.deposit, handleBinding, escrowed, claim, refund
|
|
205
|
+
const node = handleNode(PLATFORM_GOOGLE_KEY, 'Alice@Gmail.com')
|
|
206
|
+
// idBinding, resolveId, resolveHandleAndId
|
|
207
|
+
const id = idNode(PLATFORM_GOOGLE_KEY, '100000000000000000001')
|
|
208
|
+
// Throws IdError for an id no circuit would hash; ids are never normalized.
|
|
209
|
+
checkId(PLATFORM_GOOGLE_KEY, '100000000000000000001')
|
|
149
210
|
```
|
|
150
211
|
|
|
151
212
|
## Development
|