[TGE] V2 Unicity ID support (Java SDK)

[martti007]

Create support for unicity id for minting and transfering tokens

[vrogojin]

More details needed. Do we have latest specs on that?

[martti007]

unicitynetwork/state-transition-sdk-js#98

More information here

[b3y0urs3lf]

Tested on top of: issue-52 merge commit (4b1fc0a). Branch bdd-phase-0 of state-transition-sdk-java.

Test environments verified:

• Hermetic (StrictTestAggregatorClient) — full nametag + UnicityId envelope coverage
• Real bft-shard 16-shard topology — every UnicityId mint registers via the live aggregator (X-State-ID header drives shard routing)

Result: all 4 nametag features + UnicityId envelope round-trip pass against both environments. The 5 @pending-src-cleanup scenarios in token-nametag-negative.feature are
intentionally skipped — they encode forward contracts for option-2 source removal (mirror TS exactly).

What the PR changed

• UnicityId class — (name, domain) → deterministic TokenId via unicityId.toTokenId() (stable hash of the (name, domain) pair)
• UnicityIdMintTransaction class — separate mint envelope distinct from MintTransaction; carries unicityId, targetPredicate, lockScript (signing service), recipient, plus the
  standard tokenId/tokenType slots
• UnicityIdToken class — mint-only token type (no transfer method, no public transactions list); represents a registered nametag whose genesis.targetPredicate is the recipient
  predicate for tokens addressed via that nametag
• CertifiedUnicityIdMintTransaction + CertifiedUnicityIdMintTransactionVerificationRule — verification rule for nametag tokens; can verify against an expected issuer public key
• X-State-ID HTTP header on the JsonRpcAggregatorClient (JsonRpcAggregatorClient.java:18,60) — stateId attached to every JSON-RPC submit; the bft-shard subscription proxy uses this
  header to route the request to the correct shard
• CBOR array-length enforcement — CborDeserializer.decodeArray(bytes, expectedLength) now strictly enforces array arity before decoding individual elements

BDD coverage by area

1. UnicityId / UnicityIdMintTransaction CBOR envelope (round-trip + tag/version enforcement)

• unicity-id-mint-transaction-envelope.feature — UnicityIdMintTransaction round-trip preserves all fields (round-trips through CBOR; asserts tokenId, tokenType, lockScript,
  recipient, targetPredicate, unicityId all preserved byte-for-byte)
• cbor-envelope-tags.feature — UnicityIdMintTransaction decoded with the wrong CBOR tag throws CborError (tag 39041 enforcement; off-tag payload rejected)
• cbor-envelope-tags.feature — UnicityIdMintTransaction decoded with version 2 throws CborError (version slot enforcement)

2. Nametag registration end-to-end (UnicityIdToken.mint(...) via NametagRegistry.registerNametag(...))

• token-nametag.feature — Alice registers a nametag and it verifies (registration is proven by the Given step itself: NametagRegistry.registerNametag() calls
  UnicityIdToken.mint(trustBase, predicateVerifier, certified) which internally runs CertifiedUnicityIdMintTransactionVerificationRule.verify() — completes successfully =
  registration verified)

3. Nametag-as-recipient — minting/transferring tokens addressed via @NameTag

• token-nametag.feature — Bob sends a token to Alice addressed via (2 outline rows: pubkey, nametag); for nametag, recipient is resolved as
  nametag.getGenesis().getTargetPredicate() from Alice's UnicityIdToken
• token-nametag.feature — Nametag bytes do not appear in the minted token's CBOR (verifies the nametag string @alice is hashed/encoded — never appears literally in the token CBOR)
• token-minting.feature — Mint a token addressed to Bob via (2 outline rows: pubkey, nametag — minting flow exercises nametag resolution)

4. Mixed-method addressing — pubkey ↔ nametag interleaved within a single token's lifetime

• token-mixed-addressing.feature — 4-hop transfer chain runs under addressing sequence (10 outline rows covering: all-pubkey, single-nametag-at-each-position, paired-nametag,
  all-nametag, edge-position-nametag)
• token-mixed-addressing.feature — 2-hop chain, (2 outline rows: nametag→pubkey, pubkey→nametag)
• token-transfer-chain.feature — 3-hop transfer chain entered via (2 outline rows: pubkey, nametag entry)
• token-long-transfer-chain.feature — Mint entry via then 4-hop pubkey chain (2 outline rows: pubkey, nametag entry)
• token-payment-journey.feature — Entry payment to a recipient addressed via (2 outline rows)

5. Nametag-addressed split children (full split + addressing cross-product)

• token-nametag-split.feature — Split child 1 is routed to Bob via (2 outline rows)
• token-nametag-split.feature — Mixed-recipient split — child 1 via , child 2 via (4 outline rows: full pubkey/nametag cross-product for two split
  children)
• token-nametag-split.feature — Two-level split with mixed addressing (entry , grandchild ) (4 outline rows: 2-level split where each level can be addressed
  independently)

6. CBOR strict array-length enforcement (the parser hardening from this PR)

• cbor-envelope-tags.feature — SplitMintJustification arity gate fires before any version concern (2 rows: arity 1 and arity 3 — both rejected with "array" error before version is
  even checked, proving array-length enforcement runs first)
• state-id-encoding.feature — StateId.fromCBOR with a -byte payload (5 outline rows: 0/31/33/34 byte payloads rejected with "data length"; 32 succeeds — exact-length
  enforcement)
• state-id-encoding.feature — StateId.fromCBOR rejects the legacy 34-byte algorithm-prefixed form (the legacy form had [algo-prefix-byte, ...32-byte-hash] for a total of 34 bytes;
  new strict parser rejects it)
• inclusion-certificate-binary.feature — InclusionCertificate.decode rejects malformed binary of length <0/31/33/63/65> (5 outline rows; binary wire format is bitmap=32 bytes +
  sibling chunks of 32 bytes; non-aligned lengths rejected)

7. X-State-ID HTTP header — implicitly exercised by every aggregator interaction

The header itself is internal SDK plumbing (JsonRpcAggregatorClient.java:18,60). It is exercised every time the BDD harness submits a CertificationData against the bft-shard proxy.
The header's behavior (drives shard routing) is asserted via the routing tests:

• routing-byte-source.feature — 6 scenarios pinning the byte source (data[0], not data[31]) of the routing helper that derives the shard from the StateID
• bft-shard-routing.feature — 8 @bft-shard-only scenarios that exercise routing end-to-end against the live 16-shard topology (mints, cross-shard rejection, full-coverage check)

When run against the bft-shard proxy, every successful mint/transfer in the suite (~270 scenarios) implicitly proves the X-State-ID header is correctly populated — otherwise the
proxy would return 400: "JSON-RPC requests must include either stateId or shardId" (which is exactly what getBlockHeight() does, since it's the only call without state context —
caught by aggregator-connectivity.feature).

8. Negative scope — UnicityIdToken mint-only invariants (forward contracts)

• token-nametag-negative.feature — 5 @pending-src-cleanup scenarios encoding the option-1 mint-only scope:
  • A1 — no token may be addressed to UnicityIdPredicate(@alice) (option-2 predicate must not exist)
  • A2 — BuiltInPredicateType enum contains only PayToPublicKey (no UnicityId variant)
  • B1 — UnicityIdToken.fromCBOR rejects non-empty transfer list (mint-only structural invariant)
  • B2 — latest-transaction read on a nametag token is impossible (no public transactions getter)
  • B3 — UnicityIdToken's public shape matches mint-only scope (no transfer method)

These are future contracts — they will turn green when the SDK author removes the legacy option-2 trio (src/predicate/builtin/UnicityIdPredicate.*). Skipped by default; mirrors
TS-side @pending-src-cleanup exactly. No additional BDD work is needed here: the contracts are already encoded.

What's NOT in BDD (and why that's correct)

• X-State-ID HTTP header value inspection — wire-format detail; testing it directly would couple BDD to HTTP transport internals. Routing outcomes are tested via
  routing-byte-source.feature and bft-shard-routing.feature.
• UnicityId.toTokenId() deterministic-hash function — pure utility; covered by SDK-level unit tests. Indirectly exercised by every nametag scenario, which depends on the
  determinism for round-trip.
• Option-2 predicate path (legacy UnicityIdPredicate) — intentionally not exercised; the BDD contracts in token-nametag-negative.feature encode the requirement that this path
  doesn't exist. Will turn green when the SDK author removes the trio.

Moving task to done.