Skip to content

[committerpb] Add the abort snapshot transaction status and key encoding - #191

Merged
liran-funaro merged 1 commit into
hyperledger:mainfrom
cendhu:snapshot-abort
Sep 29, 2026
Merged

liran-funaro merged 1 commit into
hyperledger:mainfrom
cendhu:snapshot-abort

Conversation

@cendhu

@cendhu cendhu commented Sep 15, 2026 •

Copy link
Copy Markdown
Contributor

Type of change

  • New feature

Description

  • SnapshotState.Status gains ABORTED = 6: terminal, meaning the snapshot will not be
    hashed. Written only by the validator-committer when an abort snapshot transaction
    commits, the rule CHECKPOINTED already follows, and never by the snapshot hasher.
  • MALFORMED_SNAPSHOT_INVALID_ABORT_KEY = 122: an abort transaction's read-write key does
    not decode as an abort key.
  • REJECTED_SNAPSHOT_ABORT_NO_SUCH_SNAPSHOT = 123: a well-formed abort key naming a block
    that is not the snapshot awaiting its checkpoint, or one whose lifecycle is already
    closed. Both are per-transaction rejections rather than failures, because the submitter
    chose the block number and local state is not in question.
  • MALFORMED_SNAPSHOT_NOT_MARKER_ONLY's comment is updated: a _snapshot TX is now valid
    in two shapes, a marker-only snapshot request and an abort carrying exactly one
    read-write.
  • SnapshotAbortKey(blockNum) builds the _snapshot write key of an abort snapshot
    transaction: the \xffabort/ prefix followed by the block number, encoded order-preserving
    as a checkpoint key is. The leading raw 0xff byte cannot occur in valid UTF-8 transaction
    IDs, which the sidecar already enforces; no hex-ID assumption is needed.
  • IsSnapshotAbortKey inspects the prefix only, so a prefixed key whose block number does
    not decode is rejected as a malformed abort rather than mistaken for a snapshot request.
  • BlockNumFromSnapshotAbortKey decodes the block number and rejects trailing bytes rather
    than ignoring them: accepting a prefix would attribute the abort to the wrong snapshot.
  • snapshot.pb.go and status.pb.go regenerated via make proto.

Additional details (Optional)

The key encoding lives in this module rather than in fabric-x-committer because the only
legitimate submitter of an abort is an administrator, whose tooling depends on this module.

Related issues

@cendhu cendhu added enhancement New feature or request snapshot Database snapshot and checkpoint feature labels Sep 15, 2026
@coveralls

coveralls commented Sep 15, 2026 •

Copy link
Copy Markdown

Coverage Status

coverage: 82.041% (+0.04%) from 82.004% — cendhu:snapshot-abort into hyperledger:main

@cendhu
cendhu requested a review from liran-funaro September 15, 2026 09:36
Comment thread api/committerpb/snapshot_abort_key.go Outdated
// an abort must be recognizable from the key alone: that is what lets the commit path
// tell an abort transaction from a snapshot request without reading the record it
// names. A transaction ID is a hex-encoded digest, so it cannot contain '/'.
var snapshotAbortKeyPrefix = []byte("abort/")

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The issue is that we never actually verify this.
If we did, we could decode the TX-ID into binary and reduce the write size to the DB and over the network.
This was flagged as an issue during the evaluation, but I dismissed it because we never enforce "hex-encoded digest".
If we want to rely on it, we must enforce it in the sidecar.

@cendhu cendhu Sep 29, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The hex-ID assumption was not enforced. Changed the abort prefix to \xffabort/, where \xff is the raw byte 0xff. The sidecar already requires transaction IDs to be valid UTF-8, which cannot contain this byte, so the key distinction no longer relies on hex IDs or requires a new TX-ID restriction.

Added regression coverage for abort/foo, a transaction ID matching the old abort-key encoding, Unicode IDs, and malformed binary-prefixed keys. make test passed all 1,614 tests with the race detector; make lint passed.

This updates the abort-key encoding introduced by this PR; callers must use the updated helper.

#### Type of change

- New feature

#### Description

- `SnapshotState.Status` gains `ABORTED = 6`: terminal, meaning the snapshot will not be
  hashed. Written only by the validator-committer when an abort snapshot transaction
  commits, the rule `CHECKPOINTED` already follows, and never by the snapshot hasher.
- `MALFORMED_SNAPSHOT_INVALID_ABORT_KEY = 122`: an abort transaction's read-write key does
  not decode as an abort key.
- `REJECTED_SNAPSHOT_ABORT_NO_SUCH_SNAPSHOT = 123`: a well-formed abort key naming a block
  that is not the snapshot awaiting its checkpoint, or one whose lifecycle is already
  closed. Both are per-transaction rejections rather than failures, because the submitter
  chose the block number and local state is not in question.
- `MALFORMED_SNAPSHOT_NOT_MARKER_ONLY`'s comment is updated: a `_snapshot` TX is now valid
  in two shapes, a marker-only snapshot request and an abort carrying exactly one
  read-write.
- `SnapshotAbortKey(blockNum)` builds the `_snapshot` write key of an abort snapshot
  transaction: the `\xffabort/` prefix followed by the block number, encoded order-preserving
  as a checkpoint key is. The leading raw `0xff` byte cannot occur in valid UTF-8 transaction
  IDs, which the sidecar already enforces; no hex-ID assumption is needed.
- `IsSnapshotAbortKey` inspects the prefix only, so a prefixed key whose block number does
  not decode is rejected as a malformed abort rather than mistaken for a snapshot request.
- `BlockNumFromSnapshotAbortKey` decodes the block number and rejects trailing bytes rather
  than ignoring them: accepting a prefix would attribute the abort to the wrong snapshot.
- `snapshot.pb.go` and `status.pb.go` regenerated via `make proto`.

#### Additional details (Optional)

The key encoding lives in this module rather than in fabric-x-committer because the only
legitimate submitter of an abort is an administrator, whose tooling depends on this module.

#### Related issues

- resolves partly hyperledger#190

Signed-off-by: Senthilnathan <cendhu@gmail.com>
@liran-funaro
liran-funaro merged commit 38584e4 into hyperledger:main Sep 29, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request snapshot Database snapshot and checkpoint feature

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants