feat/add tx metadata #113
feat/add tx metadata #113
Conversation
There was a problem hiding this comment.
Pull request overview
This PR adds transaction metadata support to the TransactionBuilder, implementing the CIP-10 standard for metadata labels. The changes include a significant refactoring of the TransactionMetadatum type from class-based to simpler union types and adds the attachMetadata() builder method.
Key changes:
- Added
attachMetadata()method for attaching metadata with custom labels - Refactored TransactionMetadatum from tagged classes to simple union types (string | bigint | Uint8Array | Map | Array)
- Changed MetadataLabel from Uint8 (0-255) to NonNegativeInteger (unbounded bigint)
- Implemented automatic auxiliaryDataHash computation and proper fee calculation
Reviewed changes
Copilot reviewed 123 out of 123 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
packages/evolution/src/sdk/builders/operations/AttachMetadata.ts |
New operation implementing metadata attachment logic with duplicate label validation |
packages/evolution/src/sdk/builders/operations/Operations.ts |
Added AttachMetadataParams interface definition |
packages/evolution/src/sdk/builders/TransactionBuilder.ts |
Added attachMetadata method, auxiliaryData field to state |
packages/evolution/src/sdk/builders/TxBuilderImpl.ts |
Integrated auxiliaryDataHash computation in assembly and fee calculation |
packages/evolution/src/core/TransactionMetadatum.ts |
Major refactor from class-based to union type representation |
packages/evolution/src/core/Metadata.ts |
Updated MetadataLabel from Uint8 to NonNegativeInteger |
packages/evolution/src/core/Numeric.ts |
Added NonNegativeInteger schema |
packages/evolution/src/core/AuxiliaryData.ts |
Updated to work with refactored metadata types |
packages/evolution-devnet/test/TxBuilder.Metadata.test.ts |
Comprehensive tests for metadata attachment functionality |
| Documentation files | Updated nav_order values for new module insertion |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| * const tx = await builder | ||
| * .payToAddress({ address, assets: { lovelace: 2_000_000n } }) | ||
| * .attachMetadata({ | ||
| * label: 674n, | ||
| * metadata: TransactionMetadatum.makeTransactionMetadatumMap( | ||
| * new Map([[0n, TransactionMetadatum.makeTransactionMetadatumText("Hello, Cardano!")]]) | ||
| * ) | ||
| * }) | ||
| * .build() | ||
| * | ||
| * // Attach NFT metadata (CIP-25) | ||
| * const nftMetadata = TransactionMetadatum.makeTransactionMetadatumMap( | ||
| * new Map([ | ||
| * [TransactionMetadatum.makeTransactionMetadatumText("name"), | ||
| * TransactionMetadatum.makeTransactionMetadatumText("My NFT #42")], | ||
| * [TransactionMetadatum.makeTransactionMetadatumText("image"), | ||
| * TransactionMetadatum.makeTransactionMetadatumText("ipfs://Qm...")], | ||
| * ]) | ||
| * ) | ||
| * const tx = await builder | ||
| * .mintAssets({ assets: { [policyId + assetName]: 1n } }) | ||
| * .attachMetadata({ label: 721n, metadata: nftMetadata }) | ||
| * .build() |
There was a problem hiding this comment.
The example code references non-existent functions like TransactionMetadatum.makeTransactionMetadatumMap, TransactionMetadatum.makeTransactionMetadatumText. After the refactoring, TransactionMetadatum is now a simple union type (string | bigint | Uint8Array | Map | Array), so the examples should use plain JavaScript values directly. For example: metadata: new Map([[0n, "Hello, Cardano!"]]) instead of the makeTransactionMetadatumMap wrapper.
| if (existingMetadata && existingMetadata.has(params.label)) { | ||
| throw new TransactionBuilderError({ | ||
| message: `Metadata label ${params.label} already exists. Each metadata label can only be used once per transaction.` | ||
| }) |
There was a problem hiding this comment.
The error is thrown synchronously within a Ref.update callback, which may not properly propagate through the Effect system. This should use Effect.fail or return an Either to properly handle the error in the Effect context.
| } | ||
|
|
||
| // Create new metadata map with the new entry | ||
| const newMetadata: Map<bigint, any> = new Map(existingMetadata) |
There was a problem hiding this comment.
Using any type defeats type safety. This should be typed as Map<bigint, TransactionMetadatum.TransactionMetadatum> to ensure type correctness.
| * Each metadata entry is identified by a label (0-2^64-1) following CIP-10 standard. | ||
| * | ||
| * Common labels: | ||
| * - 674n: Message/comment metadata (CIP-20) | ||
| * - 721n: NFT metadata (CIP-25) | ||
| * - 777n: Royalty metadata (CIP-27) | ||
| * | ||
| * @since 2.0.0 | ||
| * @category metadata | ||
| */ | ||
| export interface AttachMetadataParams { | ||
| /** Metadata label (bigint 0-2^64-1). See CIP-10 for standard labels. */ |
There was a problem hiding this comment.
The documentation states labels are "(0-2^64-1)" but the implementation uses NonNegativeInteger which is unbounded. This inconsistency should be resolved. Either document it as unbounded or add validation to enforce the 2^64-1 limit.
| /** | ||
| * Attach metadata to the transaction. | ||
| * | ||
| * Metadata is stored in the auxiliary data section and identified by labels (0-255) |
There was a problem hiding this comment.
The documentation states that metadata labels are "(0-255)" which is incorrect. According to the implementation and CIP-10, metadata labels are unbounded non-negative integers (0-2^64-1 in the code comment, but actually unbounded as bigint). The documentation should be updated to match the actual implementation.
No description provided.