Skip to content

Unicity Trust Base v2: weighted BFT quorum (unequal votes), seals judged by the entry of their own epoch, release pins, cache and file store, GetTrustBase fetch loop, X-SDK-Version header (API-breaking, 4.0.0) - #101

Merged
ristik merged 10 commits into
unicitynetwork:mainfrom
ristik:upstream-pr/utb-v2
Nov 11, 2026

Conversation

@ristik

@ristik ristik commented Nov 8, 2026 •

Copy link
Copy Markdown
Member

What changed

Weighted quorum. Entries and seals use the BFT Core quorum with unequal votes: each member carries a stake-weighted vote, the threshold is exactly floor(2W/3)+1 of the total weight W, and every successor entry needs that weight of its predecessor's members (a seal needs it of the entry of its own epoch).

Verification no longer reads the single-record JSON trust base (RootTrustBase). It runs against a trust-base history: Unicity Trust Base entries (CBOR tag 39000), started from a genesis entry whose entry id the application pins, extended only by entries that carry a weighted quorum of signatures of their predecessor (tag 39015 bundles are the file and wire form).

  • Entry, bundle, history (TrustBaseEntry, TrustBaseBundle, TrustBaseHistory, TrustBaseHistoryView): strict decoding (unique encoding), identity over the unsigned bytes (EntryID = SHA-256), append-only chain, weighted quorum (more than two thirds of the predecessor's weight; an unknown or bad signature fails the entry), typed errors (TrustBaseGapException, TrustBaseConflictException, TrustBasePinMismatchException, ...). Limits: 256 members, 128-byte node ids, 128 KiB per entry (TrustBaseEntry.MAX_ENTRY_BYTES), pages of 1 MiB / 64 entries. The largest valid entry (256 members, 128-byte ids, 256 predecessor signatures, 95,365 bytes) round-trips as a shared fixture.
  • Seals judged by the entry of their own epoch (UnicitySealTrustBaseEntryRule, SealQuorumRule, the verification session): the entry of the seal's epoch is looked up, the seal's round must lie inside that epoch's interval, then the weighted quorum of that entry is checked (the upstream seal rule: unknown or bad extra signatures count zero). Only a seal whose epoch is above the held tip (or an empty history) fails with the typed, retryable NoTrustBaseEntryResult; a seal of another network or of an epoch before the genesis is an ordinary, final failure. A seal carries at most 256 supplied signatures (UnicitySeal.MAX_WITNESSES, checked at decode, structure, session and rule).
  • Fetching (TrustBaseSource, HttpTrustBaseSource, TrustBaseUpdater): GET /api/v1/trustbases, bounded read, no redirects, optional bearer key, cancellation; the first page freezes the snapshot (end epoch and end entry id) and later pages echo it; sources are untrusted; an authenticated prefix is kept when a later page fails; verifyWithUpdate verifies, fetches once on the no-entry result and verifies once more.
  • Release pins, cache and file store, version header: see below.

API-breaking changes (no backwards compatibility)

What does not change: the token format, the proof and certificate wire formats (inclusion and non-inclusion proofs, unicity certificate and seal encodings) and existing tokens: no encoder of a token, proof, certificate or seal is touched. Only the SDK API changes: NetworkId.TESTNET removed, the seal and verification API (TrustBaseHistoryView, beginOperation(PartitionViewPolicy)) and trust base loading (a bundle instead of the JSON RootTrustBase). The new decode bounds: a seal with more than 256 signatures is refused, and CBOR text strings must be valid UTF-8 (previously decoded with the platform charset).

  • RootTrustBase (JSON authority) is removed, with fromJson/toJson and bft-trustbase.*.json files. TrustBaseHistoryView replaces it in every verifier and caller (UnicityCertificateVerifier.verify, verifyCertificate, NonInclusionVerifier, ProofConsolidator, ...). A trust base serializes as a bundle (toBundle(), TrustBaseBundle.decode). getNetworkId() on a history is an Optional (empty while the history holds no entry), so minting code uses getNetworkId().get().
  • VerificationPolicy and the legacy quorum-only path are removed: beginOperation(PartitionViewPolicy) replaces beginOperation(VerificationPolicy, PartitionViewPolicy).
  • Seal verification is by epoch (above): a seal above the held tip is NoTrustBaseEntryResult, never a verification against the latest entry. More than 256 seal signatures is refused at decode.
  • NetworkId.TESTNET (2) is removed; there is no constant for the old testnet and id 2 stays a valid unnamed id. NetworkId.TESTNET2 (4) is added. MAINNET (1) and LOCAL (3) are unchanged.
  • Every wire and storage format of the history is new (tags 39000, 39015); there is no migration path from any earlier layout.
  • The SDK now sends one more request header on every aggregator call (below).

Version

All three SDKs ship as 4.0.0 (owner decision); the release must use -Pversion=4.0.0 (release.yml passes the workflow input; the last upstream tag is 1.4.2, so this is a major bump for an API-breaking release). This PR also sets 4.0.0 where a default or documented version lives: the build.gradle.kts fallback (was 3.0-SNAPSHOT, used when -Pversion is not passed) and the README dependency line. The generated SdkVersion.VERSION (from the Gradle project version) is what the X-SDK-Version header reports (java/4.0.0), so it cannot drift from the artifact. Fork main gets the same through ristik#11; this branch is rebuilt from main once that merges.

Release pins (tied to unicitynetwork/unicity-ids#11)

ReleasePins carries the genesis trust base of mainnet (network 1) and testnet2 (network 4) as library resources (src/main/resources/release-pins/): the two bundles unicity-trustbase.{mainnet,testnet2}.cbor and manifest.json, byte-identical to the files of unicitynetwork/unicity-ids#11, commit 513dc4fcf01ee802a97d59a5bc4e50ba64786d45 (recorded in the manifest's source); generated, verified at load (bundle digest, genesis against its pin, network, epochs). The manifest is byte-identical to the JS and Rust SDKs' (sha256 7bbaad4f…).

Network Id Genesis epoch Pinned EntryID Bundle sha256
mainnet 1 1 0b6f8143e19e2a585be3534e8f1062f36c3b9621e506158f10abfbc9a56f4e4c 9d01b8713cab42dab269e1ad6e244cf11e7f8c4b580682a98402db348b37bd52
testnet2 4 1 4b49eb2bb0729051b89a48668fd6ef1fda284aad2e10b7d5f23aad4b5faef37f 5b0a4fb7bd6c2d71068c0e65659aa60733dcc9083e9290fc22c2dd8e8e60f08a

unicitynetwork/unicity-ids#11 is still open at the time of writing (head 513dc4fc). This PR must not merge before it does, or the pins must be regenerated from whatever lands. Real mainnet and testnet2 seals verify through these bundles (test vectors).

Cache and store API

  • TrustBaseSession.openPublic(network, override, store, ...) starts from the embedded release pin (a newer public pin ReleasePin must extend the release lineage); openPrivate(namespace, pin, store, ...) is a private network with a pin you supply (never the public namespace); openLocal(bundle, store, ...) is a local deployment, taking network, genesis and digest from the bundle (namespace local). Each returns an Opened with the session and CacheDiagnostics (a refused cache leaves the embedded history in place).
  • session.append(entry) / appendAsync, refresh(sources, ...), history() (read-only TrustBaseHistoryView), exportBundle(), flush(), isDirty(), getConflict() (two histories that disagree at one epoch are conflict evidence and are never silently merged, sticky).
  • TrustBaseStore: read(key, maxBytes) and compareAndSwap(key, expectedRevision, bytes); flush retries up to MAX_CAS_ATTEMPTS = 4 and reports a failed save separately without losing the dirty state. MemoryTrustBaseStore is in the core.
  • FileTrustBaseStore (package ...trustbase.file, optional, nothing in the core refers to it): one file per key in a caller-chosen directory, named utb-<sha256(key)>.cbor with the lock directory utb-<sha256(key)>.lock, the same names as the JS and Rust adapters; bounded reads, atomic replacement (same-directory temporary file and atomic move), a lock that is never waited on and never stolen (contention returns BUSY). On Android the application picks the directory and a non-UI executor.
  • Cache key: layout version, network, genesis identity and trust namespace; endpoints, tips and SDK versions are not part of it.

Version header

Every aggregator request (including the trust-base GET) carries X-SDK-Version: java/<project version> by default (SdkVersionHeader), so the SDK versions in use can be measured; the aggregator never reads it. SdkVersionHeader.of(value) sets a custom printable-ASCII value and SdkVersionHeader.disabled() turns it off. Unlike the JS SDK there is no browser case, so it is on by default everywhere.

Shared vectors

Vendored byte for byte, with provenance in the README beside each: vectors/trust-base-v2/vectors.json (bft-go-base utb/upstream-v2, c32454f), vectors/trust-base-v2/max-entry/v1/max-entry.json (bft-go-base utb/gettrustbase-codec, 81ee667, the 256-member fixture), vectors/gettrustbase/vectors.json (bft-core GetTrustBase response vectors, 45 cases), vectors/utb-cache/v1/vectors.json (the cache vectors shared with the Rust and JS SDKs), vectors/real-seals/ (real mainnet and testnet2 seals and the two bundles).

Evidence

Checked on upstream-pr/utb-v2 (39c3405, upstream main 1496b9a as the base), 2026-11-08, with the Gradle wrapper (8.8) and Temurin JDKs:

  • JDK 21 (the CI version): ./gradlew build: BUILD SUCCESSFUL. 886 tests, 0 failures, 0 errors, 4 skipped. The check task includes animalsnifferMain against the Android API 31 signature (gummy-bears-api-31), which passed.
  • JDK 11 (the source/target level, and the release workflow's JDK): ./gradlew clean build androidJar jvmJar sourcesJar javadocJar: BUILD SUCCESSFUL, the same 886 tests, 0 failures, 4 skipped; the Android and JVM jars, sources and javadoc build. The Android animal-sniffer check is the Android evidence; nothing was run on an Android device or emulator.
  • Checkstyle prints 375 warnings (non-fatal); upstream main itself prints 951 with the same configuration, so this PR adds no checkstyle debt.
  • Integration tests (tag integration, Docker/Testcontainers) are excluded from ./gradlew test and were not run here. CI on fork main 9fe6bf8 (run 42463319580) is green.
  • The stack landed on fork main as fork PRs UTB parity 1/4: network names (TESTNET2) and the X-SDK-Version header ristik/state-transition-sdk-java#1 through UTB parity 8/8: approved release pins, real-seal tests, offline-to-new-epoch tests ristik/state-transition-sdk-java#8, merged by rev3 with main CI green after each.
  • Cross-SDK: the release manifest, the bundles, the max-entry fixture and the cache vectors are byte-equal to the JS and Rust SDKs'; the file-store names are shared.

Known nits

None open. (The README networks-table wording was fixed in ristik#10, merged as 5071407.)

Not in this PR

  • No integration-branch (B1/EVM) work; no change to unicity-ids.
  • The fork's CI/publish setup is not part of this PR.

Documentation: README.md keeps setup concise and identifies the build JDK; docs/api-reference.md covers sessions, pins, refresh, stores, limits and errors.

  • Update (latest commit): the shared non-inclusion corpus no longer carries a JSON trust base: its authorities are Unicity Trust Base v2 bundles (tag 39015, one genesis entry each, named by trustBaseBundle in the contexts), cases unchanged, re-vendored byte for byte from ristik/aggregator-go risto/ni-corpus-utb-authority.
  • Update (latest commits): no version-1 or JSON trust base is left in the tests or fixtures; the shared corpora (non-inclusion, uc-consolidation) carry their authorities as trust base v2 bundles on the local network and are re-vendored byte for byte from ristik/aggregator-go risto/ni-corpus-utb-authority (counterpart bft-core change: ucfixture: local network (3) and trust base v2 bundle authority; regenerated uc-consolidation producer subset ristik/bft-core#1000).

…ged by the entry of their own epoch, release pins, cache and file store, GetTrustBase fetch loop, X-SDK-Version header (API-breaking, 4.0.0)

Signed trust-base entries (tag 39000) and bundles (tag 39015). Entries and seals use the BFT Core quorum with unequal votes: stake-weighted members, threshold floor(2W/3)+1 of the total weight W. Seals are verified against the entry of their own epoch; release pins for mainnet and testnet2; trust-base cache with a file store; GetTrustBase fetch loop and HTTP source; X-SDK-Version header.

API-breaking (release version 4.0.0): RootTrustBase and VerificationPolicy removed, NetworkId.TESTNET removed, TESTNET2 added, beginOperation(PartitionViewPolicy). Unchanged: the token format, the proof and certificate wire formats and existing tokens. A seal with more than 256 signatures is refused at decode, and CBOR text must be valid UTF-8. See the PR description.
@ristik
ristik requested a review from MastaP November 8, 2026 08:43

@MastaP MastaP left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Reviewed at a80b89c. The new commit changes docs only; the code is the same as at 39c3405, where I read every changed production line. Not approving yet: item 1.

What I checked:

  • ./gradlew build (JDK 21): 886 tests, 0 failures, 4 skipped.
  • The core rules match bft-go-base#20 on a 245-case cross-implementation corpus, including unsigned 64-bit values, UTF-16 vs UTF-8 ordering and strict UTF-8.
  • The release pins are byte-identical to unicity-ids#11.
  • Real mainnet and testnet2 seals verify offline through openPublic.
  • A 302 isn't followed and the key isn't replayed. The size cap applies to the actual stream.
  1. A fake snapshot end above the honest tips makes honest sources final for the call (TrustBaseUpdater.java:244-267).
    • aggregator-go#273 answers snapshotEnd above its tip with NotYetAvailable (internal/trustbase/utb/history.go:445-448). The drop-the-snapshot retry handles only HISTORY_MISMATCH (:254), so the honest source falls through to finallyRefused (:263-265).
    • Against the real #273 handler serving 5 epochs: the honest source alone appends 4 (tip 5).
    • With a hostile first source serving one real entry, a cursor and a fake effectiveEnd: NONE_SERVED, appended 1, tip 2.
    • TrustBaseUpdaterTest.anHonestSourceRefusingAFakeSnapshotIsAskedAgainWithoutIt models the honest server answering HistoryMismatch for an end above its tip, which #273 doesn't do.
    • JS #206 and Rust #73 have the same logic.

Lower:

  1. verifySuccessor and TrustBaseHistory.append don't validate the successor's structure (TrustBaseEntry.java:624-648). Go's VerifySuccessor runs Validate() first.
    • Repro: an entry built with the public constructor, with quorumThreshold 1 where 3 is required for weight 4, and signed by the predecessor quorum. It is APPENDED, and a one-signer seal at that epoch then authenticates OK.
    • Go refuses the same entry: "quorum threshold 1, expected 3".
    • Every wire path decodes, and so validates, first, so this is not reachable remotely. Calling validate() at the start of verifySuccessor closes it.
  2. Non-inclusion loses the typed missing-entry signal.
    • NonInclusionVerifier.java:198-212 reports NO_TRUST_BASE_ENTRY as AUTHORITY_REJECTED with no cause; ProofConsolidator.java:534-546 maps it to UNAUTHENTICATED.
    • So a non-inclusion proof sealed in an epoch the client doesn't hold yet looks final.
    • With the real testnet2 vector and an empty pinned history, the certificate check gives NoTrustBaseEntryResult, while non-inclusion gives reason=AUTHORITY_REJECTED cause=null.
  3. Test gaps.
    • Removing the network check in verifySuccessor (:629) fails none of the 886 tests. The "another network" case also changes the genesis, so the previous-id check fires first.
    • Removing the epoch check (:633) also fails none. append's gap logic masks it, but a direct verifySuccessor call then accepts prev+2.

Notes:

  • Today's gateways (V1 body): you get PAGE causes, which are retryable and do no damage, and openPublic doesn't fetch. But with any V1 source listed, refresh can't report "current".
  • Namespace check: openPrivate refuses only the exact string public; Public, PUBLIC and local are accepted. This is harmless with the shipped stores, because the keys include the genesis id.
  • Merge and release: merge after unicity-ids#11, and release with -Pversion=4.0.0.

The non-inclusion corpus is re-vendored byte for byte from ristik/aggregator-go risto/ni-corpus-utb-authority (generator commit 7350e8f): cases unchanged, authorities are one-entry trust base v2 bundles named by trustBaseBundle, authority/*.json gone; the source lock and the pinned manifest hash follow. TrustBaseTestUtils.fromLegacyJson and src/test/resources/trust-base.json are removed: the consolidation and signature-recovery fixtures build their genesis entry directly, TokenE2ETest and AggregatorStack open the bundle the aggregator under test serves (GET /api/v1/trustbases, the local-network setup), and the JS interop script uses the 4.0.0 JS API with that bundle.
The docker stack is the TypeScript SDK's integration stack (src/test/resources/integration: compose file, aggregator Dockerfile, stack.env and build-images.sh): both images are built from pinned commits of the ristik forks, the root runs with the signed trust base history and the aggregator serves its bundle; AggregatorStack opens that bundle as a local session and checks its genesis against the one the stack wrote. The only trust-base.json left in the stack is the node-side input of the bft-core binaries. Non-inclusion and uc-consolidation corpora are re-vendored byte for byte from ristik/aggregator-go risto/ni-corpus-utb-authority (locks and pins updated): authorities are one-entry bundles on the local network (3), and the corpus support code opens bundles. The split-vector README records the 4.0.0 check.
…hority f072f4a (merged up with main: the bft-core pin of unicitynetwork#16); locks and pins updated
…(NOT_YET_AVAILABLE too), a successor is validated first, non-inclusion and consolidation keep the typed missing-entry cause, release pins at the merged unicity-ids ef00ff25

- TrustBaseUpdater: a source that answers a snapshot-carrying request with
  HISTORY_MISMATCH or NOT_YET_AVAILABLE (what aggregator-go answers for an end
  above its tip) is asked again from the tip without the snapshot.
- TrustBaseEntry.verifySuccessor and TrustBaseHistory.append validate the
  entry's structure first, as Go's VerifySuccessor does.
- NoTrustBaseEntryException: the typed missing-entry signal is the cause of a
  non-inclusion rejection and of a consolidation failure for certificate evidence.
- Release pins: manifest source commit ef00ff25 (bundles unchanged, byte for byte).
- Tests: the updater against the real server's answer, one test per successor rule
  (structure, network, epoch), the typed cause on the real testnet2 vector and in
  the consolidation corpus.
@ristik

ristik commented Nov 9, 2026 •

Copy link
Copy Markdown
Member Author

Thanks for the review. Pushed 0c24027f6e5b5395dc822a38d910aa9cb45ffb78. Each item against the current head first; all four were still present at 00bd71b (the JSON trust base removal did not touch them).

  1. Fake snapshot end makes honest sources final. Fixed in TrustBaseUpdater. A source that answers a snapshot-carrying request with HISTORY_MISMATCH or NOT_YET_AVAILABLE (what aggregator-go answers for an end above its tip) is now asked again from the held tip without the snapshot; without a snapshot a refusal stays final, so it still terminates. Test anHonestSourceAnsweringNotYetAvailableToAFakeEndIsAskedAgainWithoutIt models the honest server as #273 does and a hostile first source with a cursor and a fake end: both honest entries are appended (appended 4, tip 5). The HistoryMismatch test stays. The call keeps its highest announced end apart from the snapshot, so dropping the snapshot does not forget it: a not-yet-available answer without a snapshot from a source that only knows an older tip is transient (asked again next round), not "current", while an end at or above the next epoch was announced. nothingNewerMeans… is rewritten accordingly (the lagging source ends as NONE_SERVED and the authenticated prefix is kept). Removing the new status check, or the announced-end guard, fails its test.
  2. verifySuccessor / append skip structural validation. Fixed: verifySuccessor calls validate() first (as Go's VerifySuccessor does) and TrustBaseHistory.append validates before anything else. Your repro (public-constructor entry, quorumThreshold 1 where 3 is required, signed by the predecessor quorum) is now refused with TrustBaseInvalidException, and the history keeps its tip; the same entry with the exact threshold is appended (control).
  3. Non-inclusion loses the typed missing-entry cause. Fixed: the typed no-entry result (epoch of the seal, held tip) is now the cause of the NonInclusionVerificationException (new NoTrustBaseEntryException; the reason stays AUTHORITY_REJECTED, no new reason value), and the consolidation failure for certificate evidence keeps its outcome (UNAUTHENTICATED) and carries the same cause. Tests: the real testnet2 vector with an empty pinned history gives epoch 1, held tip none, and another network's bundle gives no cause; the consolidation corpus case shards-1 with an empty history gives UNAUTHENTICATED with the typed cause, and with its history it consolidates (control).
  4. Test gaps. Added TrustBaseSuccessorRulesTest: one test per rule, each with a successor that is signed by the predecessor quorum and wrong in that one respect only (structure, network with the right predecessor id, epoch prev+2 called directly). Removing the network check, the epoch check, or the validation each fails exactly its test.

Also: release pins re-pointed to the merged unicity-ids ef00ff25972e4db23485cc982e059a7022c2e463 (the bundles are byte-identical to the ones at 513dc4fc, sha256 checked; only the manifest's source commit and therefore its sha256 changed, now 56b390ab…27fc7).

Tests only, no code change needed: the cross-SDK CBOR text-string vectors (generated by Go at bft-go-base dbf94198, shared with the JS and Rust SDKs) are vendored under and pass: a leading U+FEFF is kept, invalid UTF-8 is refused, and a member id that differs only by the leading U+FEFF is a member of its own whose signature counts.

Notes: the V1-gateway and namespace-check points are unchanged (harmless as you describe). Verification: all 889 tests of the unit suites (without the Testcontainers, cucumber and JS-interop suites) pass with --release 11, javadoc is clean; the repo's ./gradlew build itself is for CI on this PR.

…e snapshot

Dropping the snapshot after HISTORY_MISMATCH / NOT_YET_AVAILABLE no longer forgets that a higher end was announced: a not-yet-available answer without a snapshot whose end is below the next epoch counts as current only when no end at or above it was announced; otherwise it is transient and asked again in the next round. Reset where the snapshot is reset because an entry was refused or the target moved on.
…valid UTF-8 refused, BOM twin members count), generated by Go at bft-go-base dbf94198
@ristik
ristik requested a review from MastaP November 10, 2026 11:57

@MastaP MastaP left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Re-reviewed at 0c24027. I read every production change since a80b89c (8 files). Items 1, 2 and 4 are fixed. Item 3 is fixed for non-inclusion and for evidence seals, but not for the other two seal checks of a consolidation. Not approving yet, for that one item.

Fixed:

  1. NotYetAvailable on a snapshot request: against the real aggregator-go#273 handler (at its fix head), my earlier scenario now ends at tip 5, the same as the honest source alone. Before the fix it ended at tip 2.
  2. Validation: verifySuccessor and TrustBaseHistory.append validate the entry first.
  3. Tests: TrustBaseSuccessorRulesTest covers the network, epoch and structure checks one at a time.

Still open: item 3, for two of the three seal checks.

  • Direct-target master seal (ProofConsolidator.java:624-627): null is passed as the cause.
    • Repro on the consolidation guard harness: the token's own proofs are in epoch 1, which the client holds. The batch is re-certified with the seal moved to epoch 2 and re-signed by the same root key.
    • The certificate check of that UC gives NoTrustBaseEntryResult (epoch 2, held tip 1).
    • But ProofConsolidator and TokenProofClient both fail with UNAUTHENTICATED and cause=null; only the message says NO_TRUST_BASE_ENTRY.
  • Partition-view seal (PartitionViewAuthenticator.java:234-238): it throws PartitionViewException(AUTHENTICATION) with no cause, and authenticateView wraps that.
    • Repro with TestChain: a view sealed by an epoch-2 authority, checked against a history holding epoch 1, gives reason=AUTHENTICATION cause=null.
    • Control: with epoch 2 appended, the view authenticates.

The master seal is the newest seal in a consolidation, so after a committee rotation it is the one most likely to be in an epoch the client doesn't hold yet. JS #206 carries the typed cause at all three checks, and Rust #73 keeps the typed VerificationError at all three.

Checks:

  • ./gradlew build (offline, JDK 21) passes, and CI passes.
  • The release pins are byte-identical to unicity-ids ef00ff25, and the manifest is 56b390ab… as in JS and Rust.
  • On the cross-implementation corpus, Java's verdicts are unchanged.

Notes: the corpora come from the ristik fork generator (details on JS #206), and the integration stack builds from ristik forks.

…d missing-entry cause

A consolidation checks three seals; the evidence seal already carried the
typed NoTrustBaseEntryException as the cause. The other two now do too:

- ProofConsolidator.authenticateDirect: a direct-target master seal of an
  epoch the history does not hold fails UNAUTHENTICATED with the typed cause.
- PartitionViewAuthenticator: AUTHENTICATION with the typed cause; the
  consolidation's view path passes it on as the direct cause, as at the other
  two checks (the message is unchanged).

Final seal failures (bad quorum, wrong network) carry no typed cause.

Tests: an epoch-2 re-signed direct target (ProofConsolidator and
TokenProofClient) with an epoch-1 history, control with epoch 2 appended; an
epoch-2 partition view with an epoch-1 history, control with epoch 2
appended; below quorum and an alien key carry no typed cause.
@ristik

ristik commented Nov 11, 2026

Copy link
Copy Markdown
Member Author

Thanks for the re-review. I pushed fb6fe57b3a665ab5a7fe196cefe4d38d72e8aaa2, which fixes the remaining part of item 3. All three seal checks of a consolidation now give the typed NoTrustBaseEntryException as the direct cause.

  • Direct-target master seal (ProofConsolidator.authenticateDirect): it fails UNAUTHENTICATED with the typed cause, so TokenProofClient gets the same cause.
  • Partition-view seal (PartitionViewAuthenticator): it throws AUTHENTICATION with the typed cause. The consolidation's view path (ProofConsolidator.viewFailure) makes that the direct cause of the consolidation failure, as the evidence path does. The message is unchanged, and any other view failure is still the cause itself.
  • Final seal failures carry no typed cause: below quorum, an alien key, wrong network, or an epoch before genesis.

Tests:

  • ConsolidationGuardTest, your repro: the re-certified batch has its seals moved to round 2 of epoch 2 and re-signed by the same root key, against a history holding epoch 1. ProofConsolidator and TokenProofClient both fail UNAUTHENTICATED with the typed cause (epoch 2, held tip 1). In the control, epoch 2 is appended (signed by the epoch-1 quorum) and the same batch consolidates. The alien-key test now also asserts that there is no typed cause.
  • PartitionViewAuthenticatorTest, your TestChain repro: a view sealed by an epoch-2 authority, against epoch 1, gives AUTHENTICATION with the typed cause. The control with epoch 2 appended authenticates, and the below-quorum case has no cause.
  • ConsolidationGuardTest, view path: the same refused view through viewFailure gives UNAUTHENTICATED with the typed cause as the direct cause, and a topology failure stays the cause itself.

Docs: I added one sentence to docs/api-reference.md, in the paragraph on missing entries: where a refusal is an exception (non-inclusion, consolidation, partition view), the same signal is its cause.

./gradlew build passes on CI for this head: https://github.com/ristik/state-transition-sdk-java/actions/runs/42975491279 (on the fork, where the change ran as a scratch PR before I pushed it here).

@ristik
ristik requested a review from MastaP November 11, 2026 08:29

@MastaP MastaP left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Re-reviewed at fb6fe57. I read the production changes since 0c24027 (ProofConsolidator, PartitionViewAuthenticator and the docs sentence). Item 3 is now fixed at all three seal checks of a consolidation. Approving.

Verified:

  • Direct-target master seal: my repro (the batch re-certified with its seal moved to epoch 2 under the same root key, against a history holding epoch 1) now fails UNAUTHENTICATED with NoTrustBaseEntryException (epoch 2, held tip 1) as the cause, through both ProofConsolidator and TokenProofClient. At 0c24027 the cause was null.
  • Partition-view seal: my TestChain repro (an epoch-2 view checked against epoch 1) now gives AUTHENTICATION with the typed cause.
  • The new tests catch a revert: putting back null at the master seal, null in PartitionViewAuthenticator, or e as the cause in viewFailure each fails at least one of the new tests in ConsolidationGuardTest and PartitionViewAuthenticatorTest.
  • Failures other than a missing entry keep their previous cause, and no code depends on the view failure's cause being a PartitionViewException.
  • ./gradlew clean build --offline (JDK 21): 899 tests, 0 failures, 4 skipped. CI passes on this head.

Nit (non-blocking): viewFailure was inserted below the Javadoc of UnavailableSignal (ProofConsolidator.java:127, "Service outcome that ends the attempt as unavailable…"), so that comment now dangles above viewFailure's own Javadoc.

The notes from my previous review still apply: the corpora come from the ristik fork generator, and the integration stack builds from ristik forks.

@ristik
ristik merged commit e5eb451 into unicitynetwork:main Nov 11, 2026
1 check passed
@ristik
ristik deleted the upstream-pr/utb-v2 branch November 11, 2026 11:17
ristik added a commit to ristik/state-transition-sdk-java that referenced this pull request Nov 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants