hyperledger / hyperledger/fabric-x-common
[committerpb] A snapshot that can never be hashed has no terminal state
- Dominant language
- Go
- Stars
- 21
- Forks
- 15
- Avg merge
- 2d 19h
- Merged PRs (30d)
- 20
Description
Part of the database snapshot & checkpoint feature (see `specs/001-db-snapshot/rfc-db-snapshot.md` in fabric-x-committer), and a follow-up to #143.
## Summary
A snapshot that can never be hashed has no terminal state, so a single such snapshot stops an organization from ever taking another one.
## The gap
The validator-committer admits a new snapshot only once the latest `_snapshot` record is `CHECKPOINTED` (`REJECTED_SNAPSHOT_IN_PROGRESS` / `REJECTED_SNAPSHOT_NO_CHECKPOINT`, added in #143). A record parked at `FAILED` is retried forever, and there is no way out but editing the state database by hand.
There is no way to say "abandon this snapshot" — and it cannot be local state either: a node re-ingesting from genesis rebuilds the state at the snapshot height, would hash successfully, and would publish a digest for a snapshot the original organization abandoned.
## Proposal
An **abort snapshot transaction**, submitted by an administrator, ordered and endorsed on the ledger. In `fabric-x-common` this needs:
1. `SnapshotState.Status.ABORTED = 6` — terminal, meaning the snapshot will not be hashed and no checkpoint attests to it. Written only by the validator-committer when an abort transaction commits (the rule `CHECKPOINTED` already follows), never by the snapshot hasher: a hasher aborting on its own findings would let one organization abandon a snapshot another hashes successfully, and the two histories would diverge on re-ingestion.
2. Two statuses for an abort that names no abortable snapshot:
- `MALFORMED_SNAPSHOT_INVALID_ABORT_KEY` — the read-write key does not decode as an abort key.
- `REJECTED_SNAPSHOT_ABORT_NO_SUCH_SNAPSHOT` — a well-formed key naming a block that is not the snapshot awaiting its checkpoint, or one whose lifecycle is already closed (`CHECKPOINTED`/`ABORTED`).
Both are per-transaction rejections rather than failures, because the submitter chose the block number and local state is not in question.
3. The abort write-key encoding (`SnapshotAbortKey` / `IsSnapshotAbortKey` / `BlockNumFromSnapshotAbortKey`). It belongs here, not in fabric-x-committer, because the only legitimate submitter is an administrator whose tooling depends on this module: a key only the committer could construct would make the transaction unbuildable by the one party allowed to send it.
`ns__snapshot` holds snapshot records keyed by transaction ID, so an abort key must be distinguishable from one by the key alone — that is what lets the commit path tell an abort from a snapshot request without first reading the record it names. An `abort/` prefix cannot collide: a transaction ID is a hex-encoded digest and holds no `/`. The block number follows, encoded order-preserving as a checkpoint key is, so aborts can be compared and range-scanned on the stored key. A snapshot is named by block number alone — a snapshot is a cut of committed state and a block holds at most one `_snapshot` transaction, so the transaction number adds nothing.
## Scope
- [ ] `fabric-x-common`: `ABORTED`, the two statuses, the abort key encoding, regenerated `*.pb.go`.
- [ ] `fabric-x-committer`: validate and commit abort transactions (sidecar/coordinator/VC), write `ABORTED`, and stop retrying an aborted snapshot.
- [ ] Administrator tooling: build and submit an abort transaction.
## Downstream impact
Additive enum values and new exported helpers only; no renames or renumbering. Backward compatible for `fabric-x-orderer`, `fabric-x-committer`, and `fabric-x`.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with specs/001-db-snapshot/rfc-db-snapshot.md in fabric-x-committer and inspect snapshot status and key handling in fabric-x-common. Trace validation and commit paths across the sidecar, coordinator, and validator-committer, then review the administrator tooling scope. Done means the listed enum values, abort-key helpers, regenerated *.pb.go, downstream validation and commit behavior, retry handling, and tooling are covered.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- backend, distributed-systems
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100