hyperledger / hyperledger/fabric-x-common

[committerpb] A snapshot that can never be hashed has no terminal state

Open
#190 0 comments 0 reactions 0 assignees View on GitHub
enhancement snapshot
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.