From ee4bd093098c37c0b2c4d19411443a1ddb71855c Mon Sep 17 00:00:00 2001 From: Hernan Rajchert Date: Tue, 20 Feb 2024 11:56:36 -0300 Subject: [PATCH] Renamed toMetadata and fromMetadata --- examples/nodejs/src/marlowe-object-flow.ts | 4 ++-- packages/marlowe-template/src/index.ts | 9 +++++---- packages/marlowe-template/src/template.ts | 20 +++++++++---------- .../test/basic-types-template.spec.ts | 8 ++++---- .../test/delayed-payment-template.spec.ts | 6 +++--- 5 files changed, 24 insertions(+), 23 deletions(-) diff --git a/examples/nodejs/src/marlowe-object-flow.ts b/examples/nodejs/src/marlowe-object-flow.ts index e677a8d0..47081f8b 100644 --- a/examples/nodejs/src/marlowe-object-flow.ts +++ b/examples/nodejs/src/marlowe-object-flow.ts @@ -186,7 +186,7 @@ async function createContractMenu( depositDeadline, releaseDeadline, }; - const metadata = delayPaymentTemplate.encode(scheme); + const metadata = delayPaymentTemplate.toMetadata(scheme); const sourceMap = await mkSourceMap(lifecycle, mkDelayPayment(scheme)); const [contractId, txId] = await sourceMap.createContract({ stakeAddress: rewardAddress, @@ -601,7 +601,7 @@ async function validateExistingContract( contractId, }); - const scheme = delayPaymentTemplate.decode(contractDetails.metadata); + const scheme = delayPaymentTemplate.fromMetadata(contractDetails.metadata); if (!scheme) { return "InvalidMarloweTemplate"; diff --git a/packages/marlowe-template/src/index.ts b/packages/marlowe-template/src/index.ts index 222ce8ae..7401fff1 100644 --- a/packages/marlowe-template/src/index.ts +++ b/packages/marlowe-template/src/index.ts @@ -2,9 +2,10 @@ * This is an `experimental` package that helps with the definition and sharing of the parameters of * a Marlowe contract template. * - * We call a contract template to a function that receives a set of parameters and returns a Marlowe contract. - * Manually sharing the contract parameters can be challenging, so this package aims to solve that by {@link MarloweTemplate.encode | encoding} - * and {@link MarloweTemplate.decode | decoding} the parameters as {@link @marlowe.io/runtime-core!index.Metadata}. + * We call a contract template to a function (e.g. `mkContract`) that receives a set of parameters and returns a Marlowe contract. + * Manually sharing the contract parameters can be challenging, so this package aims to solve that by + * serializing the parameters {@link MarloweTemplate.toMetadata | to} and + * {@link MarloweTemplate.fromMetadata | from} {@link @marlowe.io/runtime-core!index.Metadata}. * * ``` * import { mkMarloweTemplate, TemplateParametersOf } from "@marlowe.io/marlowe-template"; @@ -48,7 +49,7 @@ * * runtime.contracts.create({ * contract: mkContract(contractParameters), - * metadata: myTemplate.encode(contractParameters) + * metadata: myTemplate.toMetadata(contractParameters) * }) * ``` * @packageDocumentation diff --git a/packages/marlowe-template/src/template.ts b/packages/marlowe-template/src/template.ts index 6c60ce39..72f70d33 100644 --- a/packages/marlowe-template/src/template.ts +++ b/packages/marlowe-template/src/template.ts @@ -27,8 +27,8 @@ export class DecodingTemplateError extends Error { /** * This class holds information on the parameters required to create a Marlowe contract and - * a way to {@link MarloweTemplate.encode} and {@link MarloweTemplate.decode} the contract parameters as {@link @marlowe.io/runtime-core!index.Metadata}. - * The order of the parameters is important as it is used by the codec to encode and decode. + * a way to serialize them {@link MarloweTemplate.toMetadata | to} and {@link MarloweTemplate.fromMetadata | from} {@link @marlowe.io/runtime-core!index.Metadata}. + * The order of the parameters is important as they drive the serialization. * * The Metadata encoding is as following: * A top level entry with key `9041` and value with an object with two fields: @@ -43,6 +43,11 @@ export class MarloweTemplate { private templateCodec: t.Type; name: string; description?: string; + /** + * Manual constructor for the MarloweTemplate class, you should use {@link mkMarloweTemplate} instead. + * @typeParam ObjectParams - The inferred type of the `options.params` as an object. + * @param options - The {@link MkTemplateOptions | options} to create a new MarloweTemplate. + */ constructor(options: MkTemplateOptions[]>) { const templateParams = options.params; this.name = options.name; @@ -145,7 +150,7 @@ export class MarloweTemplate { * @returns the decoded ObjectParams. * @throws {@link DecodingTemplateError} - if the value is not a valid Metadata. */ - decode(value: Metadata): ObjectParams { + fromMetadata(value: Metadata): ObjectParams { const decoded = this.templateCodec.decode(value); if (decoded._tag === "Right") { return decoded.right; @@ -153,19 +158,14 @@ export class MarloweTemplate { throw new DecodingTemplateError(this, decoded.left); } } - // NOTE: The output of the encode is the output of the Metadata codec, - // which is compatible with its inputs, but it doesn't have the - // branded types. Here we cast to the Metadata type to allow easier - // usability with the rest of the runtime, that expects the Branded - // types. /** * Encodes the given value into a Metadata object. * * @param value The value to be encoded. * @returns The encoded Metadata object. */ - encode(value: ObjectParams): Metadata { - return this.templateCodec.encode(value) as Metadata; + toMetadata(value: ObjectParams) { + return this.templateCodec.encode(value); } } diff --git a/packages/marlowe-template/test/basic-types-template.spec.ts b/packages/marlowe-template/test/basic-types-template.spec.ts index 1f8d11d8..1975b5f1 100644 --- a/packages/marlowe-template/test/basic-types-template.spec.ts +++ b/packages/marlowe-template/test/basic-types-template.spec.ts @@ -44,7 +44,7 @@ describe("Template basic types", () => { it("should encode a valid value", () => { const a: BasicParams = { str: "hello", num: 42, dte: aDate }; - expect(basicTemplate.encode(a)).toEqual({ + expect(basicTemplate.toMetadata(a)).toEqual({ "9041": { v: 1n, params: [["hello"], 42n, aDateMS], @@ -60,7 +60,7 @@ describe("Template basic types", () => { }, }; - expect(basicTemplate.decode(metadata)).toEqual({ + expect(basicTemplate.fromMetadata(metadata)).toEqual({ str: "hello", num: 42n, dte: aDate, @@ -73,7 +73,7 @@ describe("Template basic types", () => { num: 42n, dte: aDate, }; - expect(basicTemplate.encode(a)).toEqual({ + expect(basicTemplate.toMetadata(a)).toEqual({ "9041": { v: 1n, params: [["a".repeat(64), "a"], 42n, aDateMS], @@ -88,7 +88,7 @@ describe("Template basic types", () => { params: [["a".repeat(64), "a"], 42n, aDateMS], }, }; - expect(basicTemplate.decode(metadata)).toEqual({ + expect(basicTemplate.fromMetadata(metadata)).toEqual({ str: "a".repeat(65), num: 42n, dte: aDate, diff --git a/packages/marlowe-template/test/delayed-payment-template.spec.ts b/packages/marlowe-template/test/delayed-payment-template.spec.ts index faa5a4ba..d37ca019 100644 --- a/packages/marlowe-template/test/delayed-payment-template.spec.ts +++ b/packages/marlowe-template/test/delayed-payment-template.spec.ts @@ -95,7 +95,7 @@ describe("Delayed payment Template", () => { depositDeadline: aDepositDate, releaseDeadline: aReleaseDate, }; - expect(delayPaymentTemplate.encode(a)).toEqual({ + expect(delayPaymentTemplate.toMetadata(a)).toEqual({ "9041": { v: 1n, params: [ @@ -134,7 +134,7 @@ describe("Delayed payment Template", () => { }, }; - expect(delayPaymentTemplate.decode(metadata)).toEqual({ + expect(delayPaymentTemplate.fromMetadata(metadata)).toEqual({ payer: addressBech32( "addr_test1qpcucug827nlrmsv7n66hwdfpemwqtv8nxnjc4azacuu807w6l6hgelwsph7clqmauq7h3y9qhhgs0rwu3mu8uf7m4kqckxkry" ), @@ -164,6 +164,6 @@ describe("Delayed payment Template", () => { }, }; // FIXME: Improve the error message checking - expect(() => delayPaymentTemplate.decode(metadata)).toThrow(); + expect(() => delayPaymentTemplate.fromMetadata(metadata)).toThrow(); }); });