hiero-ledger / hiero-ledger/hiero-consensus-node
CLPR-3: Payment & Routing Layer — connectors, payments, and application delivery
- Dominant language
- Java
- Stars
- 406
- Forks
- 226
- Avg merge
- 3d 4h
- Merged PRs (30d)
- 210
Description
## Epic CLPR-3: Payment & Routing Layer
**Parent:** hiero-ledger/roadmap#48
**Repo:** hiero-ledger/hiero-consensus-node
### Objective
Implement Connector registration, authorization, payment, slashing, and application dispatch on Hiero. Connectors are the economic actors that authorize messages, fund execution, and are slashed for failures.
### Background
A Connector is registered on a specific Connection and has a counterpart on the peer ledger. The source-side Connector has an authorization contract; the destination-side provides balance and staked collateral. Bilateral registration is required for end-to-end operation. Connector balances and stakes are held in the CLPR service's internal accounting (not the Connector contract's account).
### Expected Functionality
1. **Connector registration** — `registerConnector` (HAPI + system contract) with initial balance, stake, authorization contract, and source connector address mapping.
2. **Connector lifecycle** — Top-up, withdraw, deregister (HAPI + system contract). `getConnector` as system contract `view` function.
3. **Message authorization** — `IClprConnectorAuth.authorizeMessage()` called during `sendMessage` (system contract).
4. **Application dispatch** — Data messages dispatched to `target_application` via `onClprMessage()` in child transaction context. Responses generated and enqueued.
5. **Payment flow** — Connectors charged (execution cost + margin). Margin reimburses submitting endpoint.
6. **Slashing** — Escalating penalties for `CONNECTOR_NOT_FOUND` and `CONNECTOR_UNDERFUNDED`. Ban after threshold.
7. **Queue protection** — Per-Connector queue quotas and fee escalation prevent monopolization.
### Constraints
- Black-box testing only
- Bilateral Connector registration required for end-to-end operation
- Slashing is bilateral: both source and destination sides enforce independently
- Connector funds held in CLPR service accounting, not Connector contract accounts
### Stories
- CLPR-3.1: Connector wire formats, state schema, and system contract interface
- CLPR-3.2: Connector registration and lifecycle
- CLPR-3.3: Connector authorization and application dispatch
- CLPR-3.4: Slashing, penalties, and reimbursement
- CLPR-3.5: Queue monopolization protection
### Dependencies
- CLPR-1 (Connections)
- CLPR-2 (Messaging — dispatch happens within SubmitBundle)
### Spec References
- [Cross-Platform Spec §2.2, §4.6](clpr-service-spec.md) — Connector state, slashing
- [Hiero Impl Spec §6, §7](clpr-hiero-impl-spec.md) — Connector authorization, application dispatch, fund custody
Contributor guide
Research direction
Start with clpr-service-spec.md §2.2 and §4.6, then clpr-hiero-impl-spec.md §6 and §7, while reviewing the CLPR-1 and CLPR-2 dependencies. Use the five listed stories to define the scope and apply the stated black-box testing constraint. Done means connector registration and lifecycle, authorization and dispatch, payment and slashing, and queue protection are implemented.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java
- Domain
- backend-api-design, blockchain, payments
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 20/100