PLT-9368: Strict mode for runtime-lifecycle

changelog.d/20240126_162752_bjorn.wilhelm.kihlberg_PLT_9368.md

@@ -0,0 +1,16 @@
+### @marlowe.io/runtime-rest-client
+
+- `mkRestClient` provides optional `strict` parameter for performing dynamic type checking in `RestClient` methods. ([PR-180](https://github.com/input-output-hk/marlowe-ts-sdk/pull/180))
+- The following `RestClient` methods uses keyword argument object instead of positional arguments. ([PR-180](https://github.com/input-output-hk/marlowe-ts-sdk/pull/180))
+  - `createContractSources`
+  - `getContractById`
+  - `submitContract`
+  - `getTransactionsForContract`
+  - `submitContractTransaction`
+  - `getContractTransactionById`
+  - `getWithdrawalById`
+  - `submitWithdrawal`
+
+### @marlowe.io/runtime-lifecycle
+
+- `mkRuntimeLifecycle` provides optional `strict` parameter for performing dynamic type checking in `RestClient` methods. ([PR-180](https://github.com/input-output-hk/marlowe-ts-sdk/pull/180))

examples/nodejs/src/experimental-features/applicable-inputs.ts

@@ -122,7 +122,7 @@ export async function getApplicableActions(
   contractId: ContractId,
   environment?: Environment
 ): Promise<ApplicableAction[]> {
-  const contractDetails = await restClient.getContractById(contractId);
+  const contractDetails = await restClient.getContractById({ contractId });
   const currentContract = contractDetails.currentContract
     ? contractDetails.currentContract
     : contractDetails.initialContract;

examples/nodejs/src/marlowe-object-flow.ts

@@ -588,8 +588,9 @@ async function validateExistingContract(
   contractId: ContractId
 ): Promise<ValidationResults> {
   // First we try to fetch the contract details and the required tags
-  const contractDetails =
-    await lifecycle.restClient.getContractById(contractId);
+  const contractDetails = await lifecycle.restClient.getContractById({
+    contractId,
+  });
 
   const scheme = extractSchemeFromTags(contractDetails.tags);
 
@@ -609,8 +610,9 @@ async function validateExistingContract(
   //      Or this option which doesn't require runtime to runtime communication, and just requires
   //      the dapp to be able to recreate the same sources.
   const contractBundle = mkDelayPayment(scheme);
-  const { contractSourceId } =
-    await lifecycle.restClient.createContractSources(contractBundle);
+  const { contractSourceId } = await lifecycle.restClient.createContractSources(
+    { bundle: contractBundle }
+  );
   const initialContract = await lifecycle.restClient.getContractSourceById({
     contractSourceId,
   });

examples/survey-workshop/custodian/index.js

@@ -22,7 +22,9 @@ async function loadContract() {
   log("Loading contract");
   const contractId = document.getElementById("contract-id").value;
   const restClient = await H.getRestClient();
-  const paginatedTxs = await restClient.getTransactionsForContract(contractId);
+  const paginatedTxs = await restClient.getTransactionsForContract({
+    contractId,
+  });
   if (paginatedTxs.transactions.length !== 1) {
     log(
       "Expected 1 transaction for contract, got " +
@@ -33,10 +35,10 @@ async function loadContract() {
   }
   logJSON("txId", paginatedTxs.transactions[0].transactionId);
   const txId = paginatedTxs.transactions[0].transactionId;
-  const answerTx = await restClient.getContractTransactionById(
+  const answerTx = await restClient.getContractTransactionById({
     contractId,
-    txId
-  );
+    txId,
+  });
 
   const answers = await getAnswers(answerTx);
   logJSON("answers", answers);

examples/vesting-flow/index.html

@@ -140,21 +140,21 @@ <h2>Console</h2>
       const contractIdsAndDetails = await Promise.all(
         contractIds.map((contractId) =>
           restClient
-            .getContractById(contractId)
+            .getContractById({ contractId })
             .then((details) => [contractId, details])
         )
       );
       const contractIdsAndDetailsAndInputHistory = await Promise.all(
         contractIdsAndDetails.map(([contractId, details]) =>
           restClient
-            .getTransactionsForContract(contractId)
+            .getTransactionsForContract({ contractId })
             .then((result) =>
               Promise.all(
                 result.transactions.map((transaction) =>
-                  restClient.getContractTransactionById(
+                  restClient.getContractTransactionById({
                     contractId,
-                    transaction.transactionId
-                  )
+                    txId: transaction.transactionId,
+                  })
                 )
               )
             )

jsdelivr-npm-importmap.js

@@ -76,6 +76,8 @@ const importMap = {
       "https://cdn.jsdelivr.net/npm/@marlowe.io/marlowe-object@0.3.0-beta/dist/bundled/esm/marlowe-object.js",
     "@marlowe.io/marlowe-object/guards":
       "https://cdn.jsdelivr.net/npm/@marlowe.io/marlowe-object@0.3.0-beta/dist/bundled/esm/guards.js",
+    "@marlowe.io/marlowe-object/object":
+      "https://cdn.jsdelivr.net/npm/@marlowe.io/marlowe-object@0.3.0-beta/dist/bundled/esm/object.js",
     "@marlowe.io/testing-kit":
       "https://cdn.jsdelivr.net/npm/@marlowe.io/testing-kit@0.3.0-beta/dist/bundled/esm/testing-kit.js",
     "lucid-cardano": "https://unpkg.com/lucid-cardano@0.10.7/web/mod.js",

packages/adapter/src/io-ts.ts

@@ -1,6 +1,7 @@
 import * as t from "io-ts/lib/index.js";
 import { withValidate } from "io-ts-types";
 import { MarloweJSON } from "./codec.js";
+import { Errors } from "io-ts/lib/index.js";
 /**
  * In the TS-SDK we duplicate the type and guard definition for each type as the
  * inferred type from io-ts does not produce a good type export when used with
@@ -91,3 +92,20 @@ export function expectType<T>(guard: t.Type<T>, aValue: unknown): T {
     } but got ${MarloweJSON.stringify(aValue, null, 4)} `;
   }
 }
+
+/**
+ * A mechanism for validating the type of a strict in a dynamically type context.
+ * @param strict Whether to perform runtime checking to provide helpful error messages. May have a slight negative performance impact.
+ */
+export function strictDynamicTypeCheck(strict: unknown): strict is boolean {
+  return typeof strict === "boolean";
+}
+
+export class InvalidTypeError extends Error {
+  constructor(
+    public readonly errors: Errors,
+    message?: string
+  ) {
+    super(message);
+  }
+}

packages/marlowe-object/package.json

@@ -34,6 +34,11 @@
       "import": "./dist/esm/guards.js",
       "require": "./dist/bundled/cjs/guards.cjs",
       "types": "./dist/esm/guards.d.ts"
+    },
+    "./object": {
+      "import": "./dist/esm/object.js",
+      "require": "./dist/bundled/cjs/object.cjs",
+      "types": "./dist/esm/object.d.ts"
     }
   },
   "dependencies": {

packages/runtime/client/rest/src/contract/endpoints/collection.ts

@@ -5,7 +5,6 @@ import * as TE from "fp-ts/lib/TaskEither.js";
 import { pipe } from "fp-ts/lib/function.js";
 import * as E from "fp-ts/lib/Either.js";
 import * as A from "fp-ts/lib/Array.js";
-import * as O from "fp-ts/lib/Option.js";
 import { formatValidationErrors } from "jsonbigint-io-ts-reporters";
 import { stringify } from "qs";
 import { assertGuardEqual, proxy } from "@marlowe.io/adapter/io-ts";
@@ -32,6 +31,7 @@ import {
   unStakeAddressBech32,
   SourceId,
   SourceIdGuard,
+  AddressBech32Guard,
 } from "@marlowe.io/runtime-core";
 
 import { ContractHeader, ContractHeaderGuard } from "../header.js";
@@ -41,7 +41,12 @@ import {
 } from "../rolesConfigurations.js";
 
 import { ContractId, ContractIdGuard } from "@marlowe.io/runtime-core";
-import { ItemRange, Page, PageGuard } from "../../pagination.js";
+import {
+  ItemRange,
+  ItemRangeGuard,
+  Page,
+  PageGuard,
+} from "../../pagination.js";
 
 /**
  * Request options for the {@link index.RestClient#getContracts | Get contracts } endpoint
@@ -69,6 +74,16 @@ export interface GetContractsRequest {
   partyRoles?: AssetId[];
 }
 
+export const GetContractsRequestGuard = assertGuardEqual(
+  proxy<GetContractsRequest>(),
+  t.partial({
+    range: ItemRangeGuard,
+    tags: t.array(Tag),
+    partyAddresses: t.array(AddressBech32Guard),
+    partyRoles: t.array(AssetId),
+  })
+);
+
 export type GETHeadersByRange = (
   range?: ItemRange
 ) => (kwargs: {
@@ -194,6 +209,31 @@ export type BuildCreateContractTxRequestWithContract = {
   contract: Contract;
 } & BuildCreateContractTxRequestOptions;
 
+export const BuildCreateContractTxRequestOptionsGuard = assertGuardEqual(
+  proxy<BuildCreateContractTxRequestOptions>(),
+  t.intersection([
+    t.type({ changeAddress: AddressBech32Guard, version: MarloweVersion }),
+    t.partial({
+      roles: RolesConfigurationGuard,
+      threadRoleName: G.RoleName,
+      minimumLovelaceUTxODeposit: t.number,
+      metadata: Metadata,
+      tags: TagsGuard,
+      collateralUTxOs: t.array(TxOutRef),
+      usedAddresses: t.array(AddressBech32Guard),
+      stakeAddress: StakeAddressBech32,
+    }),
+  ])
+);
+
+export const BuildCreateContractTxRequestWithContractGuard = assertGuardEqual(
+  proxy<BuildCreateContractTxRequestWithContract>(),
+  t.intersection([
+    t.type({ contract: G.Contract }),
+    BuildCreateContractTxRequestOptionsGuard,
+  ])
+);
+
 /**
  * Request for the {@link index.RestClient#buildCreateContractTx | Build Create Contract Tx } endpoint using a contract
  * @category Endpoint : Build Create Contract Tx
@@ -206,6 +246,14 @@ export type BuildCreateContractTxRequestWithSourceId = {
   sourceId: SourceId;
 } & BuildCreateContractTxRequestOptions;
 
+export const BuildCreateContractTxRequestWithSourceIdGuard = assertGuardEqual(
+  proxy<BuildCreateContractTxRequestWithSourceId>(),
+  t.intersection([
+    t.type({ sourceId: SourceIdGuard }),
+    BuildCreateContractTxRequestOptionsGuard,
+  ])
+);
+
 /**
  * Request options for the {@link index.RestClient#buildCreateContractTx | Build Create Contract Tx } endpoint
  * @category Endpoint : Build Create Contract Tx
@@ -249,6 +297,14 @@ export type BuildCreateContractTxRequest =
   | BuildCreateContractTxRequestWithContract
   | BuildCreateContractTxRequestWithSourceId;
 
+export const BuildCreateContractTxRequestGuard = assertGuardEqual(
+  proxy<BuildCreateContractTxRequest>(),
+  t.union([
+    BuildCreateContractTxRequestWithContractGuard,
+    BuildCreateContractTxRequestWithSourceIdGuard,
+  ])
+);
+
 /**
  * Request options for the {@link index.RestClient#buildCreateContractTx | Build Create Contract Tx } endpoint
  * @category Endpoint : Build Create Contract Tx

packages/runtime/client/rest/src/contract/endpoints/singleton.ts

@@ -11,14 +11,17 @@ import * as HTTP from "@marlowe.io/adapter/http";
 import { DecodingError } from "@marlowe.io/adapter/codec";
 
 import {
+  ContractIdGuard,
   HexTransactionWitnessSet,
   TextEnvelope,
+  TextEnvelopeGuard,
   transactionWitnessSetTextEnvelope,
 } from "@marlowe.io/runtime-core";
 
 import { ContractDetails, ContractDetailsGuard } from "../details.js";
 import { ContractId } from "@marlowe.io/runtime-core";
 import { unsafeEither, unsafeTaskEither } from "@marlowe.io/adapter/fp-ts";
+import { assertGuardEqual, proxy } from "@marlowe.io/adapter/io-ts";
 
 export type GET = (
   contractId: ContractId
@@ -30,6 +33,14 @@ const GETPayload = t.type({
   resource: ContractDetailsGuard,
 });
 
+/**
+ * Request options for the {@link index.RestClient#getContractById | Get contracts by ID } endpoint
+ */
+export type GetContractByIdRequest = t.TypeOf<typeof GetContractByIdRequest>;
+export const GetContractByIdRequest = t.type({
+  contractId: ContractIdGuard,
+});
+
 /**
  * @see {@link https://docs.marlowe.iohk.io/api/get-contract-by-id}
  */
@@ -56,7 +67,24 @@ export type PUT = (
   hexTransactionWitnessSet: HexTransactionWitnessSet
 ) => TE.TaskEither<Error, void>;
 
-export const submitContractViaAxios =
+/**
+ * Request options for the {@link index.RestClient#submitContract | Submit contract } endpoint
+ * @category Endpoint : Submit contract
+ */
+export interface SubmitContractRequest {
+  contractId: ContractId;
+  txEnvelope: TextEnvelope;
+}
+
+export const SubmitContractRequestGuard = assertGuardEqual(
+  proxy<SubmitContractRequest>(),
+  t.type({
+    contractId: ContractIdGuard,
+    txEnvelope: TextEnvelopeGuard,
+  })
+);
+
+export const submitContract =
   (axiosInstance: AxiosInstance) =>
   (contractId: ContractId, envelope: TextEnvelope) =>
     axiosInstance

packages/runtime/client/rest/src/contract/endpoints/sources.ts

@@ -10,8 +10,22 @@ import {
   Label,
   ContractSourceId,
   ContractSourceIdGuard,
+  ContractBundle,
 } from "@marlowe.io/marlowe-object";
 import { AxiosInstance } from "axios";
+import { ContractBundleGuard } from "@marlowe.io/marlowe-object/object";
+import { assertGuardEqual, proxy } from "@marlowe.io/adapter/io-ts";
+
+/**
+ * Request options for the {@link index.RestClient#createContractSources | Create contract sources } endpoint
+ * @category Endpoint : Create contract sources
+ */
+export interface CreateContractSourcesRequest {
+  bundle: ContractBundle;
+}
+
+export const CreateContractSourcesRequestGuard: t.Type<CreateContractSourcesRequest> =
+  t.type({ bundle: ContractBundleGuard });
 
 export interface CreateContractSourcesResponse {
   contractSourceId: ContractSourceId;
@@ -51,6 +65,14 @@ export interface GetContractBySourceIdRequest {
   expand?: boolean;
 }
 
+export const GetContractBySourceIdRequestGuard = assertGuardEqual(
+  proxy<GetContractBySourceIdRequest>(),
+  t.intersection([
+    t.type({ contractSourceId: ContractSourceIdGuard }),
+    t.partial({ expand: t.boolean }),
+  ])
+);
+
 export type GetContractBySourceIdResponse = Contract;
 
 const GetContractBySourceIdResponseGuard: t.Type<GetContractBySourceIdResponse> =
@@ -81,6 +103,9 @@ export interface GetContractSourceAdjacencyRequest {
   contractSourceId: ContractSourceId;
 }
 
+export const GetContractSourceAdjacencyRequestGuard: t.Type<GetContractSourceAdjacencyRequest> =
+  t.type({ contractSourceId: ContractSourceIdGuard });
+
 export interface GetContractSourceAdjacencyResponse {
   results: ContractSourceId[];
 }
@@ -111,6 +136,9 @@ export interface GetContractSourceClosureRequest {
   contractSourceId: ContractSourceId;
 }
 
+export const GetContractSourceClosureRequestGuard: t.Type<GetContractSourceClosureRequest> =
+  t.type({ contractSourceId: ContractSourceIdGuard });
+
 export interface GetContractSourceClosureResponse {
   results: ContractSourceId[];
 }