hiero-ledger / hiero-ledger/hiero-consensus-node

CLPR-1.2: Admin key and ledger configuration management

Open
#24,486 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Java
Stars
406
Forks
226
Avg merge
3d 4h
Merged PRs (30d)
210

Description

## Story CLPR-1.2: Admin Key and Ledger Configuration

**Parent Epic:** #24484 (CLPR-1: Network Layer)

### Objective

Implement the `SetLedgerConfiguration` and `GetLedgerConfiguration` handlers, enabling an administrator to configure this ledger's CLPR throttles and anyone to query the current configuration.

### Acceptance Criteria

- **AC-1:** The CLPR admin key is a system entity key stored in CLPR service state, analogous to the address book admin key. On Hedera mainnet it is controlled by the governing council; on HashSpheres by the network operator.
- **AC-2:** `ClprSetLedgerConfigurationHandler` stores the new configuration with the consensus timestamp. Any caller-supplied `timestamp` is ignored.
- **AC-3:** `protocol_version` is determined by the CLPR service code version, not caller-supplied. The handler sets it automatically.
- **AC-4:** `chain_id` is immutable, determined by the ledger at CLPR activation. It cannot be changed via `SetLedgerConfiguration`. Attempts to change it are rejected.
- **AC-5:** Throttle fields (`ClprThrottles`) are validated per spec boundaries. Zero values are acceptable.
- **AC-6:** The handler requires the CLPR admin key. Unauthorized transactions are rejected.
- **AC-7:** `ClprGetLedgerConfigurationHandler` returns the current `ClprLedgerConfiguration` (protocol_version, chain_id, service_address, timestamp, throttles) as a paid query. Fee schedule updated in `simple-fees`.
- **AC-8:** When CLPR is disabled (feature flag), both `SetLedgerConfiguration` and `GetLedgerConfiguration` return `NOT_SUPPORTED`.
- **AC-9:** `GetLedgerConfiguration` when no configuration exists returns `CLPR_NOT_CONFIGURED`.
- **AC-10:** First-time config set works. Subsequent sets replace the previous config entirely.
- **AC-11:** Two sequential config sets produce different consensus timestamps; query returns the latest.
- **AC-12:** Black-box tests: first-time config set, config update, admin key enforcement, query returns config with server-assigned timestamp, query fee charged, query when no config exists, query when disabled, set when disabled, chain_id immutability enforced, throttle validation

### Notes

- `SetLedgerConfiguration` manages throttles only. There is no approved verifiers map — verifiers are specified per-Connection at registration and are immutable.
- Lazy config propagation uses timestamp comparison — each Connection's `last_config_timestamp` is compared against the configuration's `consensus_timestamp` when traffic flows.
- The `service_address` is a fixed constant on Hiero (impl spec §11.3).

### Dependencies

- #24485 (CLPR-1.1: wire formats and state schema)

### Risk

**Low** — Straightforward admin key pattern and singleton store write.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing dependency #24485 for the wire formats and state schema, then trace the SetLedgerConfiguration and GetLedgerConfiguration handlers. Use the acceptance criteria and listed black-box scenarios to verify admin authorization, immutable chain_id, validation, timestamps, fees, disabled behavior, and replacement of existing configuration.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api, backend, distributed-systems
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.