You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/docs.md
+28-24Lines changed: 28 additions & 24 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,7 +7,6 @@ This documentation is focused on the contracts but also clarifies assumptions ma
7
7
```mermaid
8
8
9
9
graph TD
10
-
11
10
subgraph ETHL1["Ethereum L1: Mainnet"]
12
11
FR(Fname Registry)
13
12
end
@@ -16,13 +15,13 @@ graph TD
16
15
FS(Fname Registry)
17
16
end
18
17
19
-
subgraph Hubs["Off-Chain"]
20
-
Hub1(Hub A)
21
-
Hub2(Hub B)
22
-
Hub3(Hub C)
18
+
subgraph Snapchain["Snapchain"]
19
+
NodeA(Node A)
20
+
NodeB(Node B)
21
+
NodeC(Node C)
23
22
end
24
23
25
-
subgraph ETHL2["Ethereum L2: OP Mainnet"]
24
+
subgraph OP["Ethereum L2: OP Mainnet"]
26
25
BN(Bundler) --> IG(Id Gateway)
27
26
BN --> KG(Key gateway)
28
27
IG --> SR(Storage Registry)
@@ -31,27 +30,31 @@ graph TD
31
30
KR --> SKRV(Signed Key Request Validator)
32
31
KR --> IR
33
32
RP(RecoveryProxy) --> IG
34
-
35
33
end
36
34
35
+
subgraph Base["Ethereum L2: Base"]
36
+
TR(Tier Registry)
37
+
end
37
38
38
39
ETHL1 --> Offchain
39
-
ETHL2 --> Offchain
40
-
Offchain --> Hubs
41
-
ETHL2 --> Hubs
40
+
OP --> Offchain
41
+
Offchain --> Snapchain
42
+
OP --> Snapchain
43
+
Base --> Snapchain
42
44
```
43
45
44
46
## Table of Contents
45
47
46
48
1.[L2 Contracts](#1-l2-contracts)
47
49
1.[Id Registry](#11-id-registry)
48
-
2.[Id Gateway](#12-id-manager)
50
+
2.[Id Gateway](#12-id-gateway)
49
51
3.[Storage Registry](#13-storage-registry)
50
52
4.[Key Registry](#14-key-registry)
51
-
5.[Key Gateway](#15-key-manager)
53
+
5.[Key Gateway](#15-key-gateway)
52
54
6.[Validators](#16-validators)
53
55
7.[Bundler](#17-bundler)
54
56
8.[Recovery Proxy](#18-recovery-proxy)
57
+
9.[Tier Registry](#19-tier-registry)
55
58
2.[L1 Contracts](#2-l1-contracts)
56
59
1.[Fname Resolver](#21-fname-resolver)
57
60
3.[Offchain Systems](#3-off-chain-systems)
@@ -60,7 +63,7 @@ graph TD
60
63
61
64
# 1. L2 Contracts
62
65
63
-
The Identity, Storage and Key Registry contracts are deployed on OP Mainnet. The Tier Registry contract is deployed on Base Mainnet.
66
+
The Identity, Storage and Key Registry contracts are deployed on OP Mainnet. The Tier Registry contract is deployed on Base Mainnet.
64
67
65
68
## 1.1. Id Registry
66
69
@@ -195,7 +198,7 @@ The StorageRegistry contract may need to be upgraded in case a bug is discovered
195
198
4. A new Bundler contract is deployed, pointing to the correct contracts.
196
199
5. The new storage contract is unpaused.
197
200
198
-
## 1.3. Key Registry
201
+
## 1.4. Key Registry
199
202
200
203
The Key Registry contract lets addresses with an fid register or remove public keys. Keys added onchain are tracked by Hubs and can be used to sign Farcaster messages. The same key can be added by different fids and can exist in different states. Keys contain a key type that indicates how they should be interpreted and used. During registration, metadata can also be emitted to provide additional context about the key. Keys contain a metadata type indicating how this metadata should be validated and interpreted. The Key Registry validates metadata at registration time and rejects keys with invalid metadata.
201
204
@@ -265,7 +268,7 @@ The KeyRegistry contract may need to be upgraded in case a bug is discovered or
265
268
4. A new Bundler contract is deployed, pointing to the correct contracts.
266
269
5. The contract is set to untrusted state where anyone can register keys.
267
270
268
-
## 1.4. Key Gateway
271
+
## 1.5. Key Gateway
269
272
270
273
The Key Gateway is the user-facing contract responsible for adding new keys to the Key Registry. While IdRegistry defines the rules of key addition and deletion, the Key Gateway is responsible for the actual addition logic.
271
274
@@ -294,7 +297,7 @@ In such cases:
294
297
3. The old KeyManager is paused.
295
298
4. A new Bundler contract is deployed, pointing to the correct contracts.
296
299
297
-
## 1.5 Validators
300
+
## 1.6 Validators
298
301
299
302
Validators are single purpose contracts that implement a simple interface to validate key metadata. At registration time, the Key Registry looks up the associated validator by key type and metadata type, and calls it to validate the format of provided metadata. This makes the key registry extensible to future key types and metadata formats.
300
303
@@ -306,29 +309,29 @@ The only validator today is the Signed Key Request Validator, which validates th
306
309
307
310
An `owner` can update the address of the Id Registry contract.
308
311
309
-
## 1.6. Bundler
312
+
## 1.7. Bundler
310
313
311
314
The Bundler contract lets a caller register an fid, rent storage units and register a key in a single transaction to save gas. It is a simple wrapper around contract methods and contains little logic beyond tracking contract addresses, collecting parameters and invoking the appropriate functions.
312
315
313
-
## 1.7 Recovery Proxy
316
+
## 1.8 Recovery Proxy
314
317
315
318
The Recovery Proxy is an immutable proxy contract that allows the recovery execution logic to change without changing the recovery address associated with an fid. A client or recovery service operator can deploy a recovery proxy and use it as the recovery address for fids. For example, the Warpcast client uses a recovery proxy owned by a 2/3 multisig as the default recovery address for new accounts.
316
319
317
320
#### Administration
318
321
319
322
A recovery proxy can change its `owner`, and may be owned by an EOA, multisig, or smart contract. The `owner` of the recovery proxy can change the configured `IdRegistry` address.
320
323
321
-
## 1.8. Tier Registry
324
+
## 1.9 Tier Registry
322
325
323
-
The Tier Registry contract lets addresses purchase a subscription tier for an fid for a certain amount of time. Time purchased for each tier is additive. Each tier is also associated with some metadata including the token payment is accepted in and the price per day. Being a member of a tier will guarantee an fid a certain set of additional features on the Farcaster protocol until the time purchased expires.
326
+
The Tier Registry contract lets addresses purchase a subscription tier for an fid for a certain amount of time. Time purchased for each tier is additive. Each tier is also associated with some metadata including the token payment is accepted in and the price per day. Being a member of a tier will guarantee an fid a certain set of additional features on the Farcaster protocol until the time purchased expires.
324
327
325
-
### Tiers
328
+
### Tiers
326
329
327
-
The only tier today is the Pro tier (id 1) which guarantees users on the protocol long casts and 4 embeds.
330
+
The only tier today is the Pro tier (id 1) which guarantees users on the protocol long casts and 4 embeds.
328
331
329
332
### Invariants
330
333
331
-
1. Adding a tier: Tier ids are strictly incrementing. A new tier will have an id of 1 + the last added tier id.
334
+
1. Adding a tier: Tier ids are strictly incrementing. A new tier will have an id of 1 + the last added tier id.
332
335
2. Deactivating a tier: A tier can only be deactivated if it has been created and isn't already deactivated.
333
336
3. No balance: The contract never holds a payment token balance.
334
337
4. Events: Event invariants are specified in comments above each event.
@@ -340,11 +343,12 @@ The only tier today is the Pro tier (id 1) which guarantees users on the protoco
340
343
341
344
### Migration
342
345
343
-
This is the first TierRegistry contract so no migration is required.
346
+
This is the first TierRegistry contract so no migration is required.
344
347
345
348
### Upgradeability
346
349
347
350
The TierRegistry contract may need to be upgraded in case a bug is discovered or the logic needs to be changed. In such cases:
351
+
348
352
1. A new TierRegistry contract should be deployed in a paused state
349
353
2. The tier metadata (payment token, price, min and max times per purchase) should be manually entered by the owner using `setTier`
0 commit comments