Bring the wire format and API to parity with TypeScript SDK 3.0.1

[MastaP]

Follow-up to #83, targeting service-time so it can be folded in before that PR merges.

#83 mirrors the TypeScript SDK's #146. The TypeScript side then took two review rounds — #147, which shipped as 3.0.0, and #150/#151, which shipped as 3.0.1. This brings the Java SDK to the 3.0.1 shape, so the two match in structure and not only on the wire.

The interop test pins the published 3.0.1, so what it proves is agreement with the current release.

Beyond the 3.0.0 parity work

• A transfer decodes from its source, not the whole token. TransferTransaction.fromCbor and CertifiedTransferTransaction.fromCbor take the state being spent and the lock script over it; both are checked against the certification data during verification, so a wrong value fails there. That removed the self-reference the token requirement forced — Token.fromCbor used to construct a Token over a mutable list and add to it while decoding, so getLatestTransaction would advance and each transfer could read its source back off a half-built token.
• The response cannot contradict its own proof. The public three-argument constructor let a caller supply a certificate differing from the one inside the proof, and toCbor serialises the proof's — so the field was not preserved across a round trip. Private constructor, plus certified() and notCertified().
• The wire's two shapes live in the response. decodeOrAbsent and encodeNoCertifiedLeaf were on InclusionProof, the type that cannot represent an absent leaf. InclusionProofResponse decodes the tagged structure itself and builds the proof from the parts; InclusionProof.fromCbor is self-contained and rejects anything but a leaf.

What already agreed, and what did not

The two SDKs agree on everything sent to the aggregator. I verified this rather than assuming it — the CertificationData golden vectors are byte-identical in both repos, for the explicit and the absent deadline:

d998778602d9987883014101582103a19eef04b8856f50bf2d688b0d8804575115e53d2a7780da…

MintTransaction v2 (8 fields), TransferTransaction v2 (5 fields), InclusionProof (5 elements, version 1, all-or-none leaf invariant) and the leaf value SHA256(CBOR([txhash, referenceTime])) all matched line for line too.

What diverged is the token. This SDK cannot read a token 3.0.0 produces, and 3.0.0 cannot read one produced here.

Wire changes

	before	after
Token.VERSION	1	2
CertifiedMintTransaction	3 elements	2
CertifiedTransferTransaction	3 elements	2

The middle element was a copy of the leaf's reference time, stored beside a proof that already carries it. The service records that time on the record and serves the same value for every proof of the leaf, so the copy could never legitimately differ — it cost a wire element and a consistency check that could only ever agree.

Verification changes

InclusionProof used to carry both answers the aggregator can give — a certified leaf, and the absence of one — so every field was nullable and every consumer re-established which case it held. That is now split:

class InclusionProof {                       // a certified leaf; nothing else it can be
  CertificationData getCertificationData()   // was Optional
  long getReferenceTime()                    // was Optional<Long>
  InclusionCertificate getInclusionCertificate()
}

class InclusionProofResponse {               // what the aggregator answers
  InclusionProof getInclusionProof()         // null = not certified yet
  UnicityCertificate getUnicityCertificate() // present either way
}

The wire form expresses both shapes, so decoding it stays where the layout lives: decodeOrAbsent returns the proof or null and rejects any partial combination; fromCbor refuses anything but a leaf.

What falls out: the whole status taxonomy for absent fields is gone — MISSING_CERTIFICATION_DATA, MISSING_REFERENCE_TIME, INCOMPLETE_INCLUSION_PROOF, INCLUSION_CERTIFICATE_MISSING — because none of them can occur. Both certified-transaction decoders drop their guards. The poll loop branches on the response having no proof rather than on a status that meant the same thing, and its switch collapses to an if. There is no null handling left anywhere in the verification path.

The wire bytes do not change, and the interop test proves it rather than asserting it: a token minted by the published TypeScript SDK, which does not have this split, still decodes and verifies here unchanged.

The remaining behaviour changes:

• A leaf claiming to postdate the round that certified it is rejected (REFERENCE_TIME_AFTER_ROUND). Read the comment on that check before relying on it — the bound is one-sided and does not stop back-dating. Filed as Inclusion proofs do not let a verifier detect a back-dated reference time, so expiresAt is unenforceable against a dishonest aggregator aggregator-go#186.
• expiresAt is validated where it is accepted rather than failing later inside CBOR encoding.

One thing with no TypeScript counterpart

Both deadline comparisons are unsigned. TypeScript's bigint does not wrap; a Java long does. CborDeserializer.CborUnsignedLong.asLong says so in its own javadoc: a CBOR unsigned integer at or above 2^63 comes back as a negative long. A signed comparison would read such a reference time as earlier than every deadline and wave an expired request straight through — while the leaf value, computed from the same bits, still verified. Both REQUEST_EXPIRED and the round bound now use Long.compareUnsigned.

This was found by review, not by a failing test, and it would have shipped otherwise.

Interop against the published TypeScript SDK

A node container runs @unicitylabs/state-transition-sdk@3.0.0 from npm against the aggregator this suite already starts, mints and transfers a token, verifies it with its own SDK, and prints it. Java decodes and verifies the result.

The argument for it, concretely: revert Token.VERSION to 1 — the state this branch starts from — and CrossSdkEncodingTest passes 2/2 while the interop test fails. The existing golden vectors are structurally incapable of seeing a container divergence, because CertificationData bytes never move. That is exactly how this divergence survived until now.

Three properties worth noting:

• it exercises the artifact a consumer installs, not the TypeScript repo's source tree
• the token is certified by a real aggregator, so real signatures and certificates
• nothing is committed — no vector to go stale, no question of who regenerates it, and no companion PR in the TypeScript repo

The node step shells out to the docker CLI rather than using a Testcontainers GenericContainer. Testcontainers already requires that CLI for ComposeContainer, so it adds no dependency, and a one-shot container that fails reports its own output rather than "did not start correctly" with empty logs. The container joins the stack's network and addresses the aggregator by service name, so it needs no published port and no host-gateway assumption.

Integration tests

AggregatorStack starts the compose stack from the TypeScript SDK's own file — BFT root node, mongodb, redis, pinned aggregator build — waits for consensus to certify a round rather than for the healthcheck, and tears it down. RequestDeadlineIntegrationTest mirrors the TypeScript cases.

Tagged integration, so the existing integrationTest task picks it up and test keeps excluding it. No build change was needed for that.

RequestDeadlineIntegrationTest  tests=8 failures=0 skipped=0  time=13.3s
  PASS  acceptsADeadlineAheadOfTheRoundReferenceTime
  PASS  acceptsARequestThatLeavesTheDeadlineToTheService
  PASS  rejectsADeadlineThatHasAlreadyPassed
  PASS  rejectsADeadlineEqualToAReferenceTimeAlreadyReached
  PASS  bindsAServiceAssignedDeadlineWithoutRecordingIt
  PASS  servesBackTheExplicitDeadlineTheTransactionHashCommitsTo
  PASS  reportsAReferenceTimeNoLaterThanTheRoundThatCertifiedIt
  PASS  reportsALeaflessProofForARequestThatWasNeverSubmitted

JsSdkInteropIntegrationTest     tests=1 failures=0 skipped=0
  PASS  verifiesATokenMintedByThePublishedTypeScriptSdk

No containers and no generated genesis left behind afterwards.

Testcontainers 1.19.8 → 2.0.5

This is a fix, not housekeeping. The pinned 1.19.8 cannot reach a current Docker daemon at all: docker-java 3.4.x negotiates API 1.32, Docker 29 requires 1.44 and refuses, so every Testcontainers test in this repo failed before starting a container. 2.0.5 carries docker-java 3.7.1 and connects. Bumping within 1.x does not help — I tried 1.21.3 first.

junit-jupiter and mongodb are dropped: declared but never used — nothing here imports @Testcontainers, @Container or MongoDBContainer — and 2.x does not publish them. Only core is needed, for ComposeContainer and Wait.

One behavioural note for CI: 2.x removed containerised compose, so ComposeContainer shells out to the docker CLI. Present on any GitHub runner; worth knowing if the build ever moves into a container that lacks it.

Verification changes

InclusionProof used to carry both answers the aggregator can give — a certified leaf, and the absence of one — so every field was nullable and every consumer re-established which case it held. That is now split:

class InclusionProof {                       // a certified leaf; nothing else it can be
  CertificationData getCertificationData()   // was Optional
  long getReferenceTime()                    // was Optional<Long>
  InclusionCertificate getInclusionCertificate()
}

class InclusionProofResponse {               // what the aggregator answers
  InclusionProof getInclusionProof()         // null = not certified yet
  UnicityCertificate getUnicityCertificate() // present either way
}

The wire form expresses both shapes, so decoding it stays where the layout lives: decodeOrAbsent returns the proof or null and rejects any partial combination; fromCbor refuses anything but a leaf.

What falls out: the whole status taxonomy for absent fields is gone — MISSING_CERTIFICATION_DATA, MISSING_REFERENCE_TIME, INCOMPLETE_INCLUSION_PROOF, INCLUSION_CERTIFICATE_MISSING — because none of them can occur. Both certified-transaction decoders drop their guards. The poll loop branches on the response having no proof rather than on a status that meant the same thing, and its switch collapses to an if. There is no null handling left anywhere in the verification path.

The wire bytes do not change, and the interop test proves it rather than asserting it: a token minted by the published TypeScript SDK, which does not have this split, still decodes and verifies here unchanged.

The remaining behaviour changes:

• A leaf claiming to postdate the round that certified it is rejected (REFERENCE_TIME_AFTER_ROUND). Read the comment on that check before relying on it — the bound is one-sided and does not stop back-dating. Filed as Inclusion proofs do not let a verifier detect a back-dated reference time, so expiresAt is unenforceable against a dishonest aggregator aggregator-go#186.
• expiresAt is validated where it is accepted rather than failing later inside CBOR encoding.

One thing with no TypeScript counterpart

Both deadline comparisons are unsigned. TypeScript's bigint does not wrap; a Java long does. CborDeserializer.CborUnsignedLong.asLong says so in its own javadoc: a CBOR unsigned integer at or above 2^63 comes back as a negative long. A signed comparison would read such a reference time as earlier than every deadline and wave an expired request straight through — while the leaf value, computed from the same bits, still verified. Both REQUEST_EXPIRED and the round bound now use Long.compareUnsigned.

This was found by review, not by a failing test, and it would have shipped otherwise.

Interop tests — the part that would have caught this

Each SDK builds a token from entirely fixed inputs (keys, salt, token type, state mask, deadline, round clock; RFC 6979 signing on both sides), commits it, and decodes and fully verifies the other's.

The argument for them, concretely: revert Token.VERSION to 1 — the state this branch starts from —

CrossSdkEncodingTest:  0 failures / 2     ← existing cross-SDK test, blind to it
InteropVectorTest:     1 failure  / 2
JsProducedTokenTest:   1 failure  / 1

The existing golden vectors are structurally incapable of seeing a container divergence, because CertificationData bytes never move.

The two SDKs' UnicityCertificate test fixtures differ in three padding fields, so a shared token hex vector is impossible. It is not needed: each side reads the producer's certificate and trust base out of the fixture bundle.

TestAggregatorClient gains a reference-time setter so a generated vector is byte-reproducible.

The TypeScript half is unicitynetwork/state-transition-sdk-js#149.

Integration tests — unverified, please read

AggregatorStack starts the compose stack from the TypeScript SDK's own file — BFT root node, mongodb, redis, pinned aggregator build — waits for consensus to certify a round rather than for the healthcheck, and tears it down. RequestDeadlineIntegrationTest mirrors the TypeScript cases.

Tagged integration, so the existing integrationTest task picks it up and test keeps excluding it. No build change was needed.

These 8 tests have not been observed to pass. They compile, and I confirmed test excludes them, but the machine they were written on runs Docker 29, whose minimum API version (1.44) docker-java does not meet — it negotiates 1.32. I tried bumping Testcontainers to 1.21.3 and it did not help, so I reverted that rather than ship a change that fixes nothing. Please run ./gradlew integrationTest on a normal Docker host before trusting them.

Worth knowing separately: Testcontainers 1.19.8 as pinned here cannot talk to Docker 29 at all, so anyone on a current daemon cannot run integration tests in this repo regardless of this change.

Verification

./gradlew build — 142 tests, 0 failures (the branch base had 140; the split removed cases that are now unrepresentable and added decode-boundary ones), checkstyle clean. Run in a gradle:8.5-jdk21 container; there is no JDK on the machine this was written on.

./gradlew integrationTest — 9 tests, 0 failures, 0 skips: the 8 deadline cases plus the interop mint, all against the real aggregator the stack starts.

Both token shapes carry the 3.0.0 container prefix d99880 83 02 82 d99881 88 02 03.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 47260daae6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".