entities validator selector, entities/owners and entities/operators require a Scale or Enterprise plan, as the entity endpoints they replace do.
What changes
How entities are organized
- Each entity has an
id, apathand aname. Select an entity by itsidor itspath. - Owners and operators are separate lists:
ownertakes an entity fromentities/owners,operatorone fromentities/operators. When you give both, a validator must match both. - Entities form a tree: a path is the parent’s path and the entity’s own segment, joined by
/. Selecting an entity includes the entities below it, solidoselects every Lido validator andlido/csmonly those of Lido’s CSM module. - A merged entity selects the entity it was merged into.
Find an entity’s new path
Entities can be named and grouped differently from the old ones. Look an entity up with thesearch filter of entities/owners or entities/operators, which matches the start of an entity’s name or path, ignoring case:
Lido, Lido CSM and Lido Simple DVT are the owners lido/curated, lido/csm and lido/simple-dvt. All three are below lido, so lido selects more validators than the old Lido did.
Three rules cover most old names:
- A name that was not regrouped works as a path. Paths are compared ignoring case, with every run of spaces or punctuation read as one hyphen, so
Rocket Poolselectsrocket-poolandether.fiselectsether-fi. A regrouped name does not:Lido CSMis not a path, because the entity is nowlido/csm. - An entity that was named by an address is a whale. The old entity
0x8e60…has the pathwhale-0x8e60…and the nameWhale_0x8e60…; the bare address is not a path.searchfinds it by the start of the address. - A sub-entity is an operator. Look its name up in
entities/operators.
owner or operator that names no entity returns 404, as does an owner given as operator or an operator given as owner. The old entity selector answered 404 to an unknown name on most endpoints, and entity/mev-timing an empty list.
An entity that kept its name can still cover different validators: the old model gave each validator one entity, and the new one gives it an owner and an operator. Its
validator_count, beaconscore and net_share can therefore differ from the old entity’s. Compare the figures of the entities you track once, before you switch.Select validators by entity
Every endpoint that takes thevalidator selector takes entities in place of entity. Before:
entities selection matches are refreshed hourly.
Read owners and operators from validators/metadata
Ask for the v2.1 schema with theAccept header:
owner and operator instead of entity and sub_entity. Each is an object with the entity’s id, path and name, or null when no entity is known. A validator with an owner can have no operator, and an operator known only by its address is a whale or a bare address, not a named company. The v2.1 schema answers 400 to the entity selector, and v2 answers 400 to entities, so switch the selector and the schema together.
Replace the entities overview and entity/sub-entities
List entities withentities/owners and entities/operators. Both return each entity’s validator count, BeaconScore® and net share, sorted by validator_count, largest first. sort_by sorts by beaconscore or net_share instead. range sets the window of beaconscore, 30d unless given: every window ends at the latest hourly count, so the validator counts and net_share are the same in every window. This request ranks owners by net share, as the entities overview did:
child_count gives how many there are, and search finds them by path: lido also finds lido/csm.
What changes in the list responses
Two things change what the rows add up to:
- A parent and the entities below it are separate rows.
lidois a row, and so arelido/curated,lido/csmandlido/simple-dvt, whose validatorslidoalready counts. To add up counts or shares, or to rank entities without counting a validator twice, keep only the rows whoseancestorsis empty. - Each list has its own
Unknownrow. The entities overview returned the validators without an entity as the entityUnknown.entities/ownersreturns the validators without an owner asUnknown, andentities/operatorsthose without an operator, so neither matches the overview’s. It has noidorpath, is left out when there are none, andsearchleaves it out. With the rows whoseancestorsis empty, it counts every validator once, and their shares add up to 1, except after an entity is merged or removed, until the next hourly count.
Replace entity/sub-entities
For the operators that run an owner’s validators, the closest to the old sub-entities, giveentities/operators the owner filter. Each operator’s validator_count, beaconscore and net_share then cover only the validators it runs for that owner, and its direct_validator_count is null; net_share stays their share of the whole network’s stake, as the old sub-entities’ did. entity/sub-entities answered 404 for an entity without sub-entities; an owner without operators returns only its Unknown row, and an owner the old model gave no sub-entities can have operators:
Unknown then holds the owner’s validators without an operator, which the old sub-entities did not list, so the top-level operators and Unknown count each of the owner’s validators once.
Replace entity/mev-timing
Send the entity as thevalidator selector of validators/mev-timing, which returns the same daily rows:
owner and operator. Two things differ:
- Every day counts the validators the entity has at the time of the call.
entity/mev-timingcounts those the entity had on that day, so days before an entity gained or lost validators can differ. - An entity that does not exist, and a selection that matches no validator, return
404instead of an empty list.
Find the calls you still need to migrate
Until the sunset, responses to deprecated calls carry two headers:Deprecation (RFC 9745) gives the day the deprecation was announced as a Unix timestamp, and Sunset (RFC 8594) the sunset as an HTTP date. Log the requests whose responses carry them.
After the sunset
The deprecated endpoints and theentity selector return 410 Gone with a message that names the replacement, for example:
validators/metadata returns the v2.1 schema to requests that do not ask for a version, and 410 Gone to requests for application/vnd.beaconcha.in.v2+json. API Error Messages lists every message.
