@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.
Files changed (111) hide show
  1. package/README.md +108 -47
  2. package/dist/abis/bindErrors.d.ts +714 -0
  3. package/dist/abis/bindErrors.d.ts.map +1 -0
  4. package/dist/abis/bindErrors.js +955 -0
  5. package/dist/abis/bindErrors.js.map +1 -0
  6. package/dist/abis/ceremonyPayloads.d.ts +118 -0
  7. package/dist/abis/ceremonyPayloads.d.ts.map +1 -0
  8. package/dist/abis/ceremonyPayloads.js +154 -0
  9. package/dist/abis/ceremonyPayloads.js.map +1 -0
  10. package/dist/abis/ceremonyProofVerifier.d.ts +6 -6
  11. package/dist/abis/ceremonyProofVerifier.js +6 -6
  12. package/dist/abis/ceremonyProofVerifier.js.map +1 -1
  13. package/dist/abis/handleEscrow.d.ts +56 -16
  14. package/dist/abis/handleEscrow.d.ts.map +1 -1
  15. package/dist/abis/handleEscrow.js +71 -19
  16. package/dist/abis/handleEscrow.js.map +1 -1
  17. package/dist/abis/honkVerifierErrors.d.ts +54 -0
  18. package/dist/abis/honkVerifierErrors.d.ts.map +1 -0
  19. package/dist/abis/honkVerifierErrors.js +71 -0
  20. package/dist/abis/honkVerifierErrors.js.map +1 -0
  21. package/dist/abis/identityRegistry.d.ts +123 -157
  22. package/dist/abis/identityRegistry.d.ts.map +1 -1
  23. package/dist/abis/identityRegistry.js +150 -194
  24. package/dist/abis/identityRegistry.js.map +1 -1
  25. package/dist/abis/index.d.ts +3 -0
  26. package/dist/abis/index.d.ts.map +1 -1
  27. package/dist/abis/index.js +3 -0
  28. package/dist/abis/index.js.map +1 -1
  29. package/dist/calls/handleEscrow.d.ts +1 -0
  30. package/dist/calls/handleEscrow.d.ts.map +1 -1
  31. package/dist/calls/handleEscrow.js +7 -0
  32. package/dist/calls/handleEscrow.js.map +1 -1
  33. package/dist/calls/identityRegistry.d.ts +2 -1
  34. package/dist/calls/identityRegistry.d.ts.map +1 -1
  35. package/dist/calls/identityRegistry.js +9 -2
  36. package/dist/calls/identityRegistry.js.map +1 -1
  37. package/dist/ceremony/profiles.d.ts +38 -48
  38. package/dist/ceremony/profiles.d.ts.map +1 -1
  39. package/dist/ceremony/profiles.js +31 -36
  40. package/dist/ceremony/profiles.js.map +1 -1
  41. package/dist/identity/index.d.ts +1 -3
  42. package/dist/identity/index.d.ts.map +1 -1
  43. package/dist/identity/index.js +5 -11
  44. package/dist/identity/index.js.map +1 -1
  45. package/dist/identity/resolve.d.ts +6 -8
  46. package/dist/identity/resolve.d.ts.map +1 -1
  47. package/dist/identity/resolve.js +53 -86
  48. package/dist/identity/resolve.js.map +1 -1
  49. package/dist/index.d.ts +1 -0
  50. package/dist/index.d.ts.map +1 -1
  51. package/dist/index.js +3 -4
  52. package/dist/index.js.map +1 -1
  53. package/dist/payloads.d.ts +124 -0
  54. package/dist/payloads.d.ts.map +1 -0
  55. package/dist/payloads.js +59 -0
  56. package/dist/payloads.js.map +1 -0
  57. package/dist/platforms/handle.d.ts +11 -0
  58. package/dist/platforms/handle.d.ts.map +1 -0
  59. package/dist/platforms/handle.js +29 -0
  60. package/dist/platforms/handle.js.map +1 -0
  61. package/dist/platforms/id.d.ts +8 -0
  62. package/dist/platforms/id.d.ts.map +1 -0
  63. package/dist/platforms/id.js +21 -0
  64. package/dist/platforms/id.js.map +1 -0
  65. package/dist/platforms/index.d.ts +5 -0
  66. package/dist/platforms/index.d.ts.map +1 -0
  67. package/dist/platforms/index.js +8 -0
  68. package/dist/platforms/index.js.map +1 -0
  69. package/dist/platforms/node.d.ts +4 -0
  70. package/dist/platforms/node.d.ts.map +1 -0
  71. package/dist/platforms/node.js +36 -0
  72. package/dist/platforms/node.js.map +1 -0
  73. package/dist/platforms/platforms.d.ts +39 -0
  74. package/dist/platforms/platforms.d.ts.map +1 -0
  75. package/dist/platforms/platforms.js +90 -0
  76. package/dist/platforms/platforms.js.map +1 -0
  77. package/package.json +11 -3
  78. package/src/abis/bindErrors.ts +957 -0
  79. package/src/abis/ceremonyPayloads.ts +156 -0
  80. package/src/abis/ceremonyProofVerifier.ts +6 -6
  81. package/src/abis/handleEscrow.ts +71 -19
  82. package/src/abis/honkVerifierErrors.ts +73 -0
  83. package/src/abis/identityRegistry.ts +150 -194
  84. package/src/abis/index.ts +3 -0
  85. package/src/calls/handleEscrow.ts +12 -0
  86. package/src/calls/identityRegistry.ts +14 -2
  87. package/src/ceremony/profiles.ts +53 -65
  88. package/src/identity/index.ts +5 -11
  89. package/src/identity/resolve.ts +71 -118
  90. package/src/index.ts +3 -4
  91. package/src/payloads.ts +90 -0
  92. package/src/platforms/handle.ts +36 -0
  93. package/src/platforms/id.ts +26 -0
  94. package/src/platforms/index.ts +8 -0
  95. package/src/platforms/node.ts +41 -0
  96. package/src/platforms/platforms.ts +114 -0
  97. package/dist/identity/handle.d.ts +0 -22
  98. package/dist/identity/handle.d.ts.map +0 -1
  99. package/dist/identity/handle.js +0 -140
  100. package/dist/identity/handle.js.map +0 -1
  101. package/dist/identity/handleVectors.d.ts +0 -50
  102. package/dist/identity/handleVectors.d.ts.map +0 -1
  103. package/dist/identity/handleVectors.js +0 -89
  104. package/dist/identity/handleVectors.js.map +0 -1
  105. package/dist/identity/node.d.ts +0 -5
  106. package/dist/identity/node.d.ts.map +0 -1
  107. package/dist/identity/node.js +0 -19
  108. package/dist/identity/node.js.map +0 -1
  109. package/src/identity/handle.ts +0 -176
  110. package/src/identity/handleVectors.ts +0 -104
  111. 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, LibidFactory, WTIA9), a
5
- call builder for every state-changing function, and the identity helper layer:
6
- handle normalization and resolution.
7
-
8
- Both `src/abis/` and `src/calls/` are generated from the forge artifacts
9
- (`solidity/out`) by `scripts/codegen.mjs`, and neither is committed — CI
10
- regenerates them before every build, test and publish. Each ABI is exported
11
- `as const satisfies Abi`, so viem infers argument and return types from it, and
12
- each call builder reads its arguments off that ABI, so adding a write function
13
- to a contract produces its wrapper instead of requiring someone to remember to
14
- write one. The handle vector table in `src/identity/handleVectors.ts` is
15
- generated from `solidity/contracts/identity/handles.json` by
16
- `scripts/regen-identity-handles.py`.
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
- `@libid/contracts/ceremony` imports nothing, so a consumer of that subpath alone
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
- const holder = await client.readContract({
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: 'resolveHandle',
39
- args: [platformId, 'alice'],
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 because
53
- function names like `initialize` are on almost all of them. A builder returns
54
- the call as data — no provider, no signer — so you decide how it is submitted:
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 what was typed —
93
- // normalization happens on chain.
94
- const holder = await resolveHandle(reader, x, '@Alice')
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: does the id still agree with the handle?
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, and a page read across a removal may overlap or skip:
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, id: '42', handle: 'alice', handleCurrent: true }, …]
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
- A binding is one of the generated builders: the platform, this chain's verifier
113
- version for it, the opaque payload the ceremony produced, and whether to
114
- publish the handle. The value is what `quoteBind` returns for the same pair.
115
- An EOA sends it directly, a smart wallet wraps it in its own execute:
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: [platformId(PLATFORM_GITHUB_KEY), 1],
131
+ args: [github, 1],
125
132
  })
126
- const call = calls.identityRegistry.bind(IDENTITY_REGISTRY, fee, platformId(PLATFORM_GITHUB_KEY), 1, payload, true)
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/identity'
183
+ import { checkId, normalize, PLATFORM_X_KEY, RULES_X, HandleError } from '@libid/contracts/platforms'
134
184
 
135
- normalize(' @Alice_1 ', RULES_X) // 'alice_1'
136
- // Throws HandleError (with a kind matching the on-chain error) on refusal.
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
- Hash locally, so the handle text never reaches an RPC:
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 { handleHash, handleNode, platformId, PLATFORM_GOOGLE_KEY, rulesOf } from '@libid/contracts/identity'
145
-
146
- const google = platformId(PLATFORM_GOOGLE_KEY)
147
- const hash = handleHash('Alice@Gmail.com', await rulesOf(reader, google)) // HandleEscrow.deposit
148
- const node = handleNode(google, hash) // handleBinding, escrowed, claim, refund
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