Skip to content

Conversation

@martti007
Copy link
Collaborator

@martti007 martti007 commented Oct 9, 2025

  • Moved commons library functionality into SDK

@martti007 martti007 changed the title DRAFT: Update SDK to latest state Update SDK to latest state Oct 17, 2025
@martti007 martti007 requested a review from MastaP October 17, 2025 19:50
@MastaP MastaP requested review from Copilot and igmahl October 20, 2025 12:15
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull Request Overview

This PR migrates functionality previously provided by the external commons library into the SDK, refactors token/transaction models and verification flows, and updates tests accordingly.

  • Replaces commons APIs with internal CBOR, hashing, SMT/SMST, signing, and predicate implementations
  • Refactors Token, Transactions (mint/transfer), Commitments, and verification pipeline; adjusts JSON/CBOR formats
  • Updates unit/functional/e2e tests and utilities to the new SDK interfaces

Reviewed Changes

Copilot reviewed 181 out of 183 changed files in this pull request and generated 7 comments.

Show a summary per file
File Description
tests/unit/utils/UnicityCertificateFixture.ts Adds fixture to create UnicityCertificate for tests using internal hasher/serializer/signing.
tests/unit/utils/RootTrustBaseFixture.ts Adds RootTrustBase test fixture using SDK types.
tests/unit/utils/BitStringTest.ts Adds unit tests for BitString conversions.
tests/unit/token/fungible/TokenCoinDataTest.ts Updates tests to expect InvalidJsonStructureError and new JSON shapes.
tests/unit/token/TokenUsageExampleTest.ts Removes outdated unit example using old commons-based flow.
tests/unit/smt/SparseMerkleTreeUtilsTest.ts Adds tests for SMT path utility.
tests/unit/smt/SparseMerkleTreeTest.ts Adds SMT behavior tests (calc root, paths, concurrency).
tests/unit/smt/SparseMerkleTreePathTest.ts Adds SMTree path (encode/decode/verify) tests.
tests/unit/smst/SparseMerkleSumTreeTest.ts Adds SMST behavior tests (numeric sums, concurrency).
tests/unit/signing/SigningServiceTest.ts Adds signing service tests (sign/verify/recover).
tests/unit/signing/SignatureTest.ts Adds signature encode/decode tests.
tests/unit/serializer/token/TokenSerializerTest.ts Removes old serializer tests tied to commons.
tests/unit/hash/DataHasherFactoryTest.ts Adds DataHasher factory tests.
tests/unit/hash/DataHashTest.ts Adds DataHash encode/decode tests.
tests/unit/api/SubmitCommitmentResponseTest.ts Adds SubmitCommitmentResponse tests for JSON encode/decode/verify.
tests/unit/api/SubmitCommitmentRequestTest.ts Adds SubmitCommitmentRequest tests for JSON and validation.
tests/unit/api/RequestIdTest.ts Adds RequestId serialization tests.
tests/unit/api/InclusionProofTest.ts Adds InclusionProof end-to-end verification tests.
tests/unit/api/AuthenticatorTest.ts Adds Authenticator serialization and verification tests.
tests/unit/TestAggregatorClient.ts Replaces commons types; provides in-memory aggregator client and inclusion proof response wrapper.
tests/token/CommonTestFlow.ts Updates the end-to-end token flows (mint, transfer, offline transfer, split) to new SDK API.
tests/integration/token/TokenUsageExampleTest.ts Replaces with placeholder integration test; comments out docker-based example.
tests/functional/token/TokenUsageExampleTest.ts Adds functional tests using TestAggregatorClient and new flows.
tests/e2e/token/trust-base.json Adds E2E trust base JSON for aggregator verification.
tests/e2e/token/TokenUsageExampleTest.ts Updates E2E to use RootTrustBase and new StateTransitionClient flow.
tests/TestTokenData.ts Ports TestTokenData to SDK utils (HexConverter); throws InvalidJsonStructureError on bad JSON.
tests/MintTokenUtils.ts Ports mint/send helpers to new APIs (Mint/Transfer commitments, waitInclusionProof).
src/verification/VerificationRule.ts Adds base class for rule chaining.
src/verification/VerificationResultCode.ts Adds enum for verification status.
src/verification/VerificationResult.ts Adds composite result with helpers and printers.
src/verification/VerificationError.ts Adds error type to propagate verification failures.
src/verification/IVerificationContext.ts Adds empty marker interface for verification contexts.
src/verification/CompositeVerificationRule.ts Adds composite rule runner.
src/util/TypedArrayUtils.ts Adds Uint8Array equality and compare helpers.
src/util/StringUtils.ts Adds dedent template utility.
src/util/InclusionProofUtils.ts Updates to new InclusionProof and client APIs; verifies via trust base.
src/util/HexConverter.ts Adds hex encoder/decoder with 0x support.
src/util/BitString.ts Adds bitstring wrapper with conversions.
src/util/BigintConverter.ts Adds BigInt <-> bytes conversion.
src/transaction/split/TokenSplitBuilder.ts Reimplements token split workflow (burn + split mints) using SMT/SUM trees.
src/transaction/split/SplitTokenBuilder.ts Removes old split-token builder tied to commons.
src/transaction/split/SplitToken.ts Removes old split-token model.
src/transaction/split/SplitResult.ts Removes old split result holder.
src/transaction/TransferTransactionData.ts Adds new transfer transaction data (CBOR/JSON, hashing).
src/transaction/TransferTransaction.ts Adds transfer transaction with verification pipeline.
src/transaction/TransferCommitment.ts Adds transfer commitment builder and conversion to transaction.
src/transaction/TransactionData.ts Removes old transfer data tied to commons.
src/transaction/Transaction.ts Refactors base Transaction and recipient-data helpers.
src/transaction/MintTransactionState.ts Adds derived mint source state from tokenId.
src/transaction/MintTransactionData.ts Refactors mint data (CBOR/JSON, hashing, reasons).
src/transaction/MintTransaction.ts Adds mint transaction verification and serialization.
src/transaction/MintCommitment.ts Adds mint commitment builder (minter secret) and conversion.
src/transaction/InclusionProof.ts Replaces inclusion proof with SDK types and verification.
src/transaction/IMintTransactionReason.ts Adds mint reason interface.
src/transaction/Commitment.ts Makes Commitment abstract with toTransaction.
src/token/fungible/TokenCoinData.ts Ports coin data; adds from/to CBOR/JSON and helpers.
src/token/fungible/SplitMintReasonProof.ts Ports split proof to SDK SMT/SMST paths and CBOR/JSON.
src/token/fungible/SplitMintReason.ts Ports split mint reason; verifies burn and proofs.
src/token/fungible/CoinId.ts Ports coin ID to SDK CBOR/JSON.
src/token/TokenType.ts Ports token type; adds equals and CBOR/JSON.
src/token/TokenState.ts Refactors token state with EncodedPredicate and CBOR/JSON.
src/token/TokenId.ts Ports token ID; adds fromNameTag, equals, CBOR/JSON.
src/token/TokenFactory.ts Removes old token factory tied to commons.
src/token/Token.ts Refactors token model, serialization, and verification flow.
src/token/NameTagTokenData.ts Removes placeholder nametag type.
src/token/NameTagToken.ts Removes old nametag alias.
src/sign/SigningService.ts Adds secp256k1 signing/verification service.
src/sign/Signature.ts Adds signature type with CBOR/JSON.
src/sign/ISigningService.ts Adds signing service interface.
src/sign/ISignature.ts Adds signature interface.
src/serializer/token/ITokenSerializer.ts Removes old JSON token serializer interface.
src/serializer/json/transaction/TransactionJsonSerializer.ts Removes old JSON transaction serializer.
src/serializer/json/transaction/TransactionDataJsonSerializer.ts Removes old JSON transaction data serializer.
src/serializer/json/transaction/MintTransactionJsonSerializer.ts Removes old mint JSON serializer.
src/serializer/json/transaction/MintTransactionDataJsonSerializer.ts Removes old mint data JSON serializer.
src/serializer/json/transaction/ITransactionJson.ts Removes old transaction JSON interface.
src/serializer/json/transaction/CommitmentJsonSerializer.ts Removes old commitment JSON serializer.
src/serializer/json/token/TokenStateJsonSerializer.ts Removes old token state JSON serializer.
src/serializer/json/token/TokenJsonSerializer.ts Removes old token JSON serializer.
src/serializer/cbor/transaction/TransactionDataCborSerializer.ts Removes old CBOR transaction data serializer.
src/serializer/cbor/transaction/TransactionCborSerializer.ts Removes old CBOR transaction serializer.
src/serializer/cbor/transaction/MintTransactionDataCborSerializer.ts Removes old CBOR mint data serializer.
src/serializer/cbor/transaction/MintTransactionCborSerializer.ts Removes old CBOR mint transaction serializer.
src/serializer/cbor/transaction/CommitmentCborSerializer.ts Removes old CBOR commitment serializer.
src/serializer/cbor/token/TokenStateCborSerializer.ts Removes old CBOR token state serializer.
src/serializer/cbor/token/TokenCborSerializer.ts Removes old CBOR token serializer.
src/serializer/cbor/MajorType.ts Adds CBOR major type enum.
src/serializer/cbor/CborSerializer.ts Adds CBOR encoder.
src/serializer/cbor/CborReader.ts Adds CBOR reader for raw items.
src/serializer/cbor/CborMapEntry.ts Adds CBOR map entry type.
src/serializer/cbor/CborMap.ts Adds CBOR canonical map helper.
src/serializer/cbor/CborError.ts Adds CBOR error type.
src/serializer/cbor/CborDeserializer.ts Adds CBOR decoder.
src/predicate/embedded/UnmaskedPredicateReference.ts Adds unmasked predicate reference and address conversion.
src/predicate/embedded/UnmaskedPredicate.ts Adds unmasked predicate with verification and reference.
src/predicate/embedded/MaskedPredicateReference.ts Adds masked predicate reference and address conversion.
src/predicate/embedded/MaskedPredicate.ts Adds masked predicate and reference derivation.

Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.


public toCBOR(): Uint8Array {
return CborEncoder.encodeArray([this.aggregationPath.toCBOR(), this.coinTreePath.toCBOR()]);
return CborSerializer.encodeArray(this.aggregationPath.toCBOR(), this.coinTreePath.toCBOR());
Copy link

Copilot AI Oct 20, 2025

Choose a reason for hiding this comment

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

toCBOR omits the coinId, but fromCBOR expects the tuple [coinId, aggregationPath, coinTreePath]. This breaks round‑trip serialization and downstream verification. Serialize coinId as the first element.

Suggested change
return CborSerializer.encodeArray(this.aggregationPath.toCBOR(), this.coinTreePath.toCBOR());
return CborSerializer.encodeArray(
this.coinId.toCBOR(),
this.aggregationPath.toCBOR(),
this.coinTreePath.toCBOR()
);

Copilot uses AI. Check for mistakes.
const data = CborDeserializer.readArray(bytes);

if (CborDeserializer.readTextString(data[0]) !== TOKEN_VERSION) {
throw new Error(`Unsupported token version: ${CborDeserializer.readTextString(data[4])}`);
Copy link

Copilot AI Oct 20, 2025

Choose a reason for hiding this comment

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

The error references data[4] instead of the actual version at data[0], producing a misleading message. Capture the version from data[0] and report it.

Suggested change
throw new Error(`Unsupported token version: ${CborDeserializer.readTextString(data[4])}`);
throw new Error(`Unsupported token version: ${CborDeserializer.readTextString(data[0])}`);

Copilot uses AI. Check for mistakes.
}

public async verify(context: C): Promise<VerificationResult> {
let rule: VerificationRule<IVerificationContext> | null = this.firstRule;
Copy link

Copilot AI Oct 20, 2025

Choose a reason for hiding this comment

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

Use the generic parameter C for the rule type to preserve type safety and avoid needless widening to IVerificationContext. Replace VerificationRule with VerificationRule.

Suggested change
let rule: VerificationRule<IVerificationContext> | null = this.firstRule;
let rule: VerificationRule<C> | null = this.firstRule;

Copilot uses AI. Check for mistakes.
Comment on lines 20 to 22
* Mint transaction.
*
* @param <R> mint reason
Copy link

Copilot AI Oct 20, 2025

Choose a reason for hiding this comment

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

The class docstring refers to 'Mint transaction' and a generic mint reason, but this class models a transfer transaction and has no type parameter. Update the comment to accurately describe a transfer transaction.

Suggested change
* Mint transaction.
*
* @param <R> mint reason
* Represents a transfer transaction, including its data and inclusion proof.

Copilot uses AI. Check for mistakes.
public toString(): string {
return dedent`
VerificationResult:
isSuccessful: ${this.status}
Copy link

Copilot AI Oct 20, 2025

Choose a reason for hiding this comment

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

toString labels the field as 'isSuccessful' but prints the numeric status code. Print this.isSuccessful (boolean) and, optionally, include status on a separate line.

Suggested change
isSuccessful: ${this.status}
isSuccessful: ${this.isSuccessful}
status: ${this.status}

Copilot uses AI. Check for mistakes.
Comment on lines 120 to 122
* Convert predicate to CBOR bytes.
*
* @return CBOR bytes
Copy link

Copilot AI Oct 20, 2025

Choose a reason for hiding this comment

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

The JSDoc does not match the method behavior. getReference returns a predicate reference, not raw CBOR bytes. Update the summary and @return to reflect that it returns UnmaskedPredicateReference.

Suggested change
* Convert predicate to CBOR bytes.
*
* @return CBOR bytes
* Returns a reference to this predicate for use in transactions.
*
* @return Promise resolving to an UnmaskedPredicateReference

Copilot uses AI. Check for mistakes.
const token = await mintToken(client, mintTokenData);
const token = await mintToken(trustBase, client, mintTokenData);

// Perfrom 1st split
Copy link

Copilot AI Oct 20, 2025

Choose a reason for hiding this comment

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

Corrected spelling.

Suggested change
// Perfrom 1st split
// Perform 1st split

Copilot uses AI. Check for mistakes.
igmahl
igmahl previously approved these changes Oct 21, 2025
/** The public key as a hex string. */
readonly publicKey: string;
/** The signature algorithm used. */
readonly algorithm: string;
Copy link
Member

Choose a reason for hiding this comment

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

could be a link to an enum, unclear which values are acceptable

@MastaP MastaP added this to Unicity Oct 21, 2025
@MastaP MastaP moved this to In Dev in Unicity Oct 21, 2025
@martti007 martti007 merged commit 8ae2944 into main Oct 21, 2025
1 check passed
@martti007 martti007 deleted the update-to-09-10-25 branch October 21, 2025 20:56
@github-project-automation github-project-automation bot moved this from In Dev to Done in Unicity Oct 21, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

Support Unicity Certificates in inclusion proofs Use CBOR encoding for hashing Inclusion proof response has changed

4 participants