@aztec-labs/epoch-cache 6.0.0-rc.3 → 6.0.0
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 +32 -10
- package/dest/committee_lookup.d.ts +70 -0
- package/dest/committee_lookup.d.ts.map +1 -0
- package/dest/committee_lookup.js +40 -0
- package/dest/epoch_cache.d.ts +54 -42
- package/dest/epoch_cache.d.ts.map +1 -1
- package/dest/epoch_cache.js +177 -115
- package/dest/index.d.ts +2 -1
- package/dest/index.d.ts.map +1 -1
- package/dest/index.js +1 -0
- package/dest/test/index.d.ts +2 -1
- package/dest/test/index.d.ts.map +1 -1
- package/dest/test/index.js +1 -0
- package/dest/test/lookups.d.ts +16 -0
- package/dest/test/lookups.d.ts.map +1 -0
- package/dest/test/lookups.js +37 -0
- package/dest/test/test_epoch_cache.d.ts +13 -9
- package/dest/test/test_epoch_cache.d.ts.map +1 -1
- package/dest/test/test_epoch_cache.js +39 -14
- package/package.json +6 -6
- package/src/committee_lookup.ts +84 -0
- package/src/epoch_cache.ts +218 -163
- package/src/index.ts +1 -0
- package/src/test/index.ts +1 -0
- package/src/test/lookups.ts +40 -0
- package/src/test/test_epoch_cache.ts +39 -20
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { SlotNumber } from '@aztec-labs/foundation/branded-types';
|
|
2
2
|
import { getEpochAtSlot, getSlotAtTimestamp, getTimestampForSlot, getTimestampRangeForEpoch } from '@aztec-labs/stdlib/epoch-helpers';
|
|
3
|
+
import { toCommitteeLookup, withoutMembers } from '../committee_lookup.js';
|
|
3
4
|
import { PROPOSER_PIPELINING_SLOT_OFFSET } from '../epoch_cache.js';
|
|
4
5
|
/** Default L1 constants for testing. */ const DEFAULT_L1_CONSTANTS = {
|
|
5
6
|
l1StartBlock: 0n,
|
|
@@ -44,7 +45,7 @@ import { PROPOSER_PIPELINING_SLOT_OFFSET } from '../epoch_cache.js';
|
|
|
44
45
|
return this;
|
|
45
46
|
}
|
|
46
47
|
/**
|
|
47
|
-
* Sets the proposer address returned by
|
|
48
|
+
* Sets the proposer address returned by lookupProposer.
|
|
48
49
|
* @param proposer - The address of the current proposer.
|
|
49
50
|
*/ setProposer(proposer) {
|
|
50
51
|
this.proposerAddress = proposer;
|
|
@@ -94,10 +95,12 @@ import { PROPOSER_PIPELINING_SLOT_OFFSET } from '../epoch_cache.js';
|
|
|
94
95
|
getLagInEpochsForValidatorSet() {
|
|
95
96
|
return this.lagInEpochsForValidatorSet;
|
|
96
97
|
}
|
|
97
|
-
getCommittee(_slot) {
|
|
98
|
+
/** An empty committee is `open`, as the real cache reports a target committee size of zero. */ getCommittee(_slot) {
|
|
99
|
+
return Promise.resolve(this.getCommitteeLookup());
|
|
100
|
+
}
|
|
101
|
+
getCommitteeLookup() {
|
|
98
102
|
const epoch = getEpochAtSlot(this.currentSlot, this.l1Constants);
|
|
99
|
-
return
|
|
100
|
-
committee: this.committee,
|
|
103
|
+
return toCommitteeLookup(this.committee, {
|
|
101
104
|
epoch,
|
|
102
105
|
seed: this.seed,
|
|
103
106
|
isEscapeHatchOpen: this.escapeHatchOpen
|
|
@@ -177,23 +180,45 @@ import { PROPOSER_PIPELINING_SLOT_OFFSET } from '../epoch_cache.js';
|
|
|
177
180
|
nextSlot: next.slot
|
|
178
181
|
};
|
|
179
182
|
}
|
|
180
|
-
|
|
181
|
-
return Promise.resolve(this.proposerAddress
|
|
183
|
+
/** An unset proposer is an `open` committee, independently of the committee set with {@link setCommittee}. */ lookupProposer(_slot) {
|
|
184
|
+
return Promise.resolve(this.proposerAddress === undefined ? {
|
|
185
|
+
state: 'open'
|
|
186
|
+
} : {
|
|
187
|
+
state: 'members',
|
|
188
|
+
proposer: this.proposerAddress
|
|
189
|
+
});
|
|
182
190
|
}
|
|
183
191
|
getRegisteredValidators() {
|
|
184
192
|
return Promise.resolve(this.registeredValidators);
|
|
185
193
|
}
|
|
186
|
-
|
|
187
|
-
|
|
194
|
+
lookupMembership(_slot, validator) {
|
|
195
|
+
const lookup = this.getCommitteeLookup();
|
|
196
|
+
return Promise.resolve(lookup.state === 'members' ? {
|
|
197
|
+
state: 'members',
|
|
198
|
+
inCommittee: lookup.committee.some((v)=>v.equals(validator))
|
|
199
|
+
} : withoutMembers(lookup));
|
|
188
200
|
}
|
|
189
201
|
filterInCommittee(_slot, validators) {
|
|
190
|
-
const
|
|
191
|
-
|
|
202
|
+
const lookup = this.getCommitteeLookup();
|
|
203
|
+
if (lookup.state !== 'members') {
|
|
204
|
+
return Promise.resolve(withoutMembers(lookup));
|
|
205
|
+
}
|
|
206
|
+
const committeeSet = new Set(lookup.committee.map((v)=>v.toString()));
|
|
207
|
+
return Promise.resolve({
|
|
208
|
+
state: 'members',
|
|
209
|
+
inCommittee: validators.filter((v)=>committeeSet.has(v.toString()))
|
|
210
|
+
});
|
|
192
211
|
}
|
|
193
|
-
|
|
194
|
-
return Promise.resolve(
|
|
212
|
+
lookupEscapeHatch(_epoch) {
|
|
213
|
+
return Promise.resolve({
|
|
214
|
+
state: this.getCommitteeLookup().state,
|
|
215
|
+
isEscapeHatchOpen: this.escapeHatchOpen
|
|
216
|
+
});
|
|
195
217
|
}
|
|
196
|
-
|
|
197
|
-
return Promise.resolve(
|
|
218
|
+
lookupEscapeHatchAtSlot(_slot) {
|
|
219
|
+
return Promise.resolve({
|
|
220
|
+
state: this.getCommitteeLookup().state,
|
|
221
|
+
isEscapeHatchOpen: this.escapeHatchOpen
|
|
222
|
+
});
|
|
198
223
|
}
|
|
199
224
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@aztec-labs/epoch-cache",
|
|
3
|
-
"version": "6.0.0
|
|
3
|
+
"version": "6.0.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"exports": {
|
|
6
6
|
".": "./dest/index.js",
|
|
@@ -26,14 +26,14 @@
|
|
|
26
26
|
"../package.common.json"
|
|
27
27
|
],
|
|
28
28
|
"dependencies": {
|
|
29
|
-
"@aztec-labs/ethereum": "6.0.0
|
|
30
|
-
"@aztec-labs/foundation": "6.0.0
|
|
31
|
-
"@aztec-labs/stdlib": "6.0.0
|
|
29
|
+
"@aztec-labs/ethereum": "6.0.0",
|
|
30
|
+
"@aztec-labs/foundation": "6.0.0",
|
|
31
|
+
"@aztec-labs/stdlib": "6.0.0",
|
|
32
32
|
"dotenv": "^16.0.3",
|
|
33
33
|
"get-port": "^7.1.0",
|
|
34
34
|
"jest-mock-extended": "^4.0.0",
|
|
35
35
|
"tslib": "^2.4.0",
|
|
36
|
-
"viem": "
|
|
36
|
+
"viem": "2.57.1",
|
|
37
37
|
"zod": "~4.4.3"
|
|
38
38
|
},
|
|
39
39
|
"devDependencies": {
|
|
@@ -89,6 +89,6 @@
|
|
|
89
89
|
]
|
|
90
90
|
},
|
|
91
91
|
"engines": {
|
|
92
|
-
"node": ">=20.
|
|
92
|
+
"node": ">=20.16"
|
|
93
93
|
}
|
|
94
94
|
}
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
import { CommitteeNotStableError } from '@aztec-labs/ethereum/contracts';
|
|
2
|
+
import type { EpochNumber } from '@aztec-labs/foundation/branded-types';
|
|
3
|
+
import type { EthAddress } from '@aztec-labs/foundation/eth-address';
|
|
4
|
+
|
|
5
|
+
/** The epoch's committee cannot be known yet: its sample seed can still change on L1. */
|
|
6
|
+
export type UnstableCommittee = {
|
|
7
|
+
state: 'unstable';
|
|
8
|
+
epoch: EpochNumber;
|
|
9
|
+
/** L1 block at which the seed was found not to be fixed yet. */
|
|
10
|
+
l1BlockNumber: bigint;
|
|
11
|
+
};
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* Outcome of a committee lookup, with `TMembers` the data derived from a non-empty committee and `TKnown` the data
|
|
15
|
+
* available in every state whose committee is known:
|
|
16
|
+
* - `members`: the epoch has a non-empty committee.
|
|
17
|
+
* - `open`: the target committee size is zero, so anyone may propose and nobody attests.
|
|
18
|
+
* - `none`: L1 has no committee for the epoch, because the validator set is smaller than the target committee size.
|
|
19
|
+
* - `unstable`: see {@link UnstableCommittee}. Never treat it as `open` or `none`: it says nothing about the committee.
|
|
20
|
+
*/
|
|
21
|
+
export type CommitteeLookupOf<TMembers extends object, TKnown extends object = object> =
|
|
22
|
+
| ({ state: 'members' } & TMembers & TKnown)
|
|
23
|
+
| ({ state: 'open' } & TKnown)
|
|
24
|
+
| ({ state: 'none' } & TKnown)
|
|
25
|
+
| UnstableCommittee;
|
|
26
|
+
|
|
27
|
+
/** Data an epoch's entry holds whenever its committee is known. */
|
|
28
|
+
export type EpochCommitteeInfo = {
|
|
29
|
+
epoch: EpochNumber;
|
|
30
|
+
seed: bigint;
|
|
31
|
+
/** True if the epoch is within an open escape hatch window. */
|
|
32
|
+
isEscapeHatchOpen: boolean;
|
|
33
|
+
};
|
|
34
|
+
|
|
35
|
+
/** An epoch's committee. */
|
|
36
|
+
export type CommitteeLookup = CommitteeLookupOf<{ committee: EthAddress[] }, EpochCommitteeInfo>;
|
|
37
|
+
|
|
38
|
+
/** An epoch's committee once known, i.e. any state but `unstable`. */
|
|
39
|
+
export type KnownCommitteeLookup = Exclude<CommitteeLookup, UnstableCommittee>;
|
|
40
|
+
|
|
41
|
+
/** A slot's proposer, which only a `members` committee has. */
|
|
42
|
+
export type ProposerLookup = CommitteeLookupOf<{ proposer: EthAddress }>;
|
|
43
|
+
|
|
44
|
+
/** Whether an epoch's escape hatch is open, known in every state but `unstable`. */
|
|
45
|
+
export type EscapeHatchLookup = CommitteeLookupOf<object, { isEscapeHatchOpen: boolean }>;
|
|
46
|
+
|
|
47
|
+
/** Which of a set of addresses sit on a `members` committee. */
|
|
48
|
+
export type CommitteeMembershipLookup<T> = CommitteeLookupOf<{ inCommittee: T }>;
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Classifies a committee as `RollupContract.getCommitteeAt` returns it: `undefined` when L1 has no committee, and an
|
|
52
|
+
* empty list when the target committee size is zero.
|
|
53
|
+
*/
|
|
54
|
+
export function toCommitteeLookup(committee: EthAddress[] | undefined, info: EpochCommitteeInfo): KnownCommitteeLookup {
|
|
55
|
+
if (committee === undefined) {
|
|
56
|
+
return { state: 'none', ...info };
|
|
57
|
+
}
|
|
58
|
+
if (committee.length === 0) {
|
|
59
|
+
return { state: 'open', ...info };
|
|
60
|
+
}
|
|
61
|
+
return { state: 'members', committee, ...info };
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** Narrows a committee lookup without members to its state, which is all a lookup derived from it carries. */
|
|
65
|
+
export function withoutMembers(
|
|
66
|
+
lookup: Exclude<CommitteeLookup, { state: 'members' }>,
|
|
67
|
+
): { state: 'open' } | { state: 'none' } | UnstableCommittee {
|
|
68
|
+
return lookup.state === 'unstable' ? lookup : { state: lookup.state };
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* Returns the lookup if its committee is known, and throws {@link CommitteeNotStableError} otherwise. For callers that
|
|
73
|
+
* cannot act without the committee and rely on a thrown error to retry later.
|
|
74
|
+
*/
|
|
75
|
+
export function requireStableCommittee<T extends { state: string }>(lookup: T | UnstableCommittee): T {
|
|
76
|
+
if (isUnstableCommittee(lookup)) {
|
|
77
|
+
throw new CommitteeNotStableError(BigInt(lookup.epoch), lookup.l1BlockNumber);
|
|
78
|
+
}
|
|
79
|
+
return lookup;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
function isUnstableCommittee(lookup: { state: string }): lookup is UnstableCommittee {
|
|
83
|
+
return lookup.state === 'unstable';
|
|
84
|
+
}
|