ValidatorRegistry - YouthChain

Address: 0x286b9783b3245a253c3350c60d91cd50cc5e4c5cSource: contracts/src/ValidatorRegistry.sol · node-side reader: crates/yc-execution/src/validator_registry.rs

The node does not read this registry unless you tell it to. yc-node calls activeSet() only when the VALIDATOR_REGISTRY environment variable is set on that node, and only at epoch boundaries. In the deployed testnet compose file that variable is set on the indexer service, not on any yc-node-* service — so today the consensus validator set comes from genesis and nothing rotates from this contract. See Consensus integration for the full rule.

What is stored per validator

struct Validator {
    address addr;
    uint256 stake;
    uint64  registeredAt;
    uint32  engagementScore;
    bool    active;
    uint256 slashedAmount;
    bytes   blsPublicKey;
    bytes   edPublicKey;
    string  p2pEndpoint;
}

The registry holds two keys per validator, not one: a 48-byte BLS public key (BLS_PUBKEY_LENGTH) used for block proposals and the aggregated commit, and a 32-byte ed25519 public key (ED_PUBKEY_LENGTH) which is the node’s transaction-signing identity. p2pEndpoint is what the node uses to refresh its validator peer list. Constants that gate registration and slashing:

Constant	Value
`MIN_STAKE`	`10_000 ether` (10,000 YCE)
`BLS_PUBKEY_LENGTH`	48
`ED_PUBKEY_LENGTH`	32
`UNBOND_PERIOD`	7 days
`DOWNTIME_SLASH_COOLDOWN`	1 hour
`SLASH_BPS_DOUBLE_VOTE` / `INVALID_BLOCK` / `WITHHOLDING` / `DOWNTIME`	1000 / 500 / 100 / 50 bps
`LEAK_TRIGGER_ONLINE_BPS`	6670 (66.70%)
`LEAK_RATE_BPS_PER_EPOCH` / `LEAK_CAP_BPS` / `LEAK_EPOCH_SECS`	12 / 5000 / 3 hours

Registering

function register(
    uint256 stakeAmount,
    bytes calldata blsPublicKey,
    bytes calldata edPublicKey,
    string calldata p2pEndpoint
) external;

register is not payable. The stake is pulled with yce.transferFrom(msg.sender, ...), so the caller must approve the registry for at least stakeAmount first.

It reverts with StakeTooLow below MIN_STAKE, AlreadyRegistered if the caller is already active, and InvalidBlsKeyLength / InvalidEdKeyLength if either key is the wrong size. On success engagementScore is seeded to 100, active becomes true, and ValidatorRegistered(who, stake, p2pEndpoint) is emitted. Re-registering after exit() reuses the existing slot in validatorList.

const stake = 10_000n * 10n ** 18n;
await yce.approve(REGISTRY, stake);
await registry.register(stake, blsPublicKey, edPublicKey, "http://my-node:9000");

Leaving

There is no deregister(). Exit is two-phase:

requestUnbond()

Marks the validator and records unbondRequestedAt. Emits ValidatorUnbondRequested(who, unlocksAt).

Wait UNBOND_PERIOD

7 days.

exit()

Returns the remaining stake and emits ValidatorExited(who, returned). Reverts with UnbondNotReady before the period elapses.

updateEndpoint(string p2pEndpoint) changes the advertised endpoint without unbonding.

Reads

function activeSet() external view returns (
    address[] addrs,
    bytes[]   blsKeys,
    bytes[]   edKeys,
    string[]  endpoints,
    uint256[] stakes
);
function validators(address) external view returns (Validator memory);
function getValidator(address) external view returns (uint256 stake, uint64 registeredAt, uint32 engagementScore, bool active, uint256 slashedAmount);
function validatorCount() external view returns (uint256);        // ever registered
function activeValidatorCount() external view returns (uint256);  // currently active
function isJailed(address) external view returns (bool);
function MIN_STAKE() external view returns (uint256);

activeSet() returns five parallel arrays in registration order and filters on active only — a jailed-but-active validator is still returned. Canonical ordering is applied node-side, not by the contract.

Slashing and inactivity leak

All punitive entry points are gated by a single onlySlasher address (set in the constructor, changeable via setSlasher). There is no DAO and no owner, and there is no slash(address, uint256) taking an absolute amount — every penalty is a basis-point fraction of the validator’s stake, burned via IYCEBurnable.burn.

function slashDoubleVote(address who, bytes32 a, bytes32 b) external; // onlySlasher
function slashInvalidBlock(address who) external;                     // onlySlasher
function slashWithholding(address who) external;                      // onlySlasher
function slashDowntime(address who) external;                         // onlySlasher
function slashCustom(address who, uint256 bps, string reason) external; // onlySlasher, bps <= 10_000
function updateEngagementScore(address who, uint32 score) external;   // onlySlasher
function reportNetworkOnline(uint256 onlineBps) external;             // onlySlasher
function applyInactivityLeak(address who) external;                   // onlySlasher
function clearInactivityLeak(address who) external;                   // onlySlasher
function setSlasher(address next) external;                           // onlySlasher

The indexer’s slasher daemon (yscan/indexer/src/slasher.ts) is the process that calls these.

Events

event ValidatorRegistered(address indexed who, uint256 stake, string p2pEndpoint);
event ValidatorEndpointUpdated(address indexed who, string p2pEndpoint);
event ValidatorUnbondRequested(address indexed who, uint64 unlocksAt);
event ValidatorExited(address indexed who, uint256 returned);
event ValidatorSlashed(address indexed who, uint256 burned, string reason);
event ValidatorJailed(address indexed who, uint64 jailUntil, string reason);
event EngagementScoreUpdated(address indexed who, uint32 score);
event SlasherUpdated(address indexed slasher);
event InactivityLeakState(bool active, uint256 onlineBps);
event InactivityLeakApplied(address indexed who, uint256 burned, uint256 cumulativeBps);

Consensus integration

This is the part most often misread, so it is stated precisely.

When the registry is read

apply_epoch_boundary (crates/yc-node/src/dag.rs) returns immediately unless block_number != 0 && block_number % EPOCH_LENGTH == 0. EPOCH_LENGTH is a compile-time constant of 100 blocks (crates/yc-types/src/constants.rs), not an environment variable; changing it is a hard fork. It is not read every slot. onchain_validator_set then reads VALIDATOR_REGISTRY from the environment. If the variable is unset — or holds something that is not a 20-byte hex address — it returns an empty vector silently, no activeSet() call is made, and no set is proposed. The boundary hook is reached only from the FireDAG commit path (dag.rs) and the sync path (crates/yc-node/src/sync.rs). A node running the legacy single-leader path calls maybe_rotate_at_epoch directly and never consults the registry at all.

How a set is admitted

Decode

read_active_validator_set performs a read-only EVM call to activeSet() from the zero address and decodes the five arrays into OnChainValidator { address, bls_public_key, ed_public_key, p2p_endpoint, stake_wei }.

Canonical order

The set is sorted ascending by address — in decode_active_set, then again in maybe_rotate_at_epoch. Registration order in the contract is irrelevant.

Minimum size

Fewer than 4 entries and no proposal is queued at all. maybe_rotate_at_epoch independently rejects any proposed set below 4 with epoch rotation REJECTED ... BFT minimum is 4.

Identical-set check

If the proposal is structurally identical to the live set — same length, and pairwise the same address and the same BLS public key — then stakes are copied into the live entries in place and the function returns without rotating. Ed25519 keys, endpoints, stakes and engagement scores are not part of that comparison, so a pure stake change is a refresh, never a rotation.

Quorum-overlap guard

Let retained be the number of proposed addresses that were already in the live set. The rotation is rejected unless retained >= 2 * old_count / 3 + 1 and retained >= 2 * new_count / 3 + 1 (integer division). For a 4-validator set both quorums are 3. On failure the node logs epoch rotation REJECTED ... unsafe quorum overlap and keeps the current set.

Apply

Attestation buffers are remapped old index to new index by address, the new BLS set becomes authoritative from block_number + 1, and the DAG frontier is reset. The node logs epoch rotation APPLIED at block N: X → Y validators (retained R, my_index now: ...).

A queued proposal is consumed at every boundary even when it is subsequently rejected. A set that fails the minimum-size or quorum-overlap guard is discarded, not retried; it must be re-proposed at the next boundary.

What BLS keys are used for

Verifying each peer’s commit signature on /internal/bft/proposal responses.
Verifying the aggregated commit signature carried by an incoming block.

If the active set lists this node at some index but with a BLS public key that differs from the one the node holds, attach_own_keys refuses to attach and the node stays mute — it follows the chain without signing, and logs STAYING MUTE. That is a local decision by that node; it is not a block-rejection rule.

Running a candidate node

A candidate is a node that holds its own keys, follows the chain, and starts signing only once an epoch rotation admits it.

Variable	Candidate
`YOUTHCHAIN_CANDIDATE_SEED`	Required. 32-byte hex seed.
`NODE_INDEX`	Must not be set. Setting both panics at startup — a node is either in the initial validator set or a candidate.
genesis `validator_keys` or `YOUTHCHAIN_VALIDATOR_SEEDS`	Required, so the candidate knows the active set’s public identities.
`SELF_URL`, `PEERS`	Required for peering and for endpoint refresh.

Both of the candidate’s keys derive from that one seed: the ed25519 keypair is the seed itself, and the BLS keypair is derived from hash("YC_BLS_v1" || seed). Register that BLS public key on-chain — registering any other one means the node will refuse to sign after admission. Note that this differs from the genesis validators, whose BLS seeds are derived from their index rather than from an ed25519 seed.

Checking a node’s own view: `yc_nodeIdentity`

curl -s -X POST $RPC -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"yc_nodeIdentity","params":[],"id":1}'

{
  "address": "0x...",
  "blsPublicKey": "0x...",
  "validatorIndex": 2,
  "signing": true,
  "role": "validator",
  "activeSetSize": 4
}

Field	Meaning
`address`	The node’s own signing address, or `null` if it holds no keys.
`blsPublicKey`	The BLS public key it would sign with, or `null`.
`validatorIndex`	Index in the address-sorted active set, or `null` if it is not in the set.
`signing`	`true` exactly when `validatorIndex` is non-null.
`role`	`"validator"` — holds keys and is in the current set with a matching BLS key. `"candidate"` — holds keys but is not in the current set (or is listed with a different BLS key and is deliberately mute). `"follower"` — holds no keys at all; seedless, and cannot be admitted without a restart with a seed.
`activeSetSize`	Size of the current active set.

This is the fastest way to confirm whether a rotation actually admitted your node: role flips from candidate to validator and signing becomes true at the boundary block.

​What is stored per validator

​Registering

​Leaving

​Reads

​Slashing and inactivity leak

​Events

​Consensus integration

​When the registry is read

​How a set is admitted

​What BLS keys are used for

​Running a candidate node

​Checking a node’s own view: yc_nodeIdentity

What is stored per validator

Registering

Leaving

Reads

Slashing and inactivity leak

Events

Consensus integration

When the registry is read

How a set is admitted

What BLS keys are used for

Running a candidate node

Checking a node’s own view: `yc_nodeIdentity`