Add typescript declarations for cardano-wasm API and generate it automatically from ApiInfo

cabal.project

@@ -29,6 +29,10 @@ if impl(ghc < 9.8)
 
 constraints: process >= 1.6.26.1
 
+-- this slows down the build plan preparation, but it seems that without it
+-- cabal has problems with resolving dependencies
+max-backjumps: 50000
+
 program-options
   ghc-options: -Werror
 

cardano-wasm/app/Main.hs

@@ -1,4 +1,8 @@
-module Main (main) where
+module Main where
+
+import Cardano.Wasm.Internal.Api.Info (apiInfo)
+import Cardano.Wasm.Internal.Api.InfoToTypeScript (apiInfoToTypeScriptFile)
+import Cardano.Wasm.Internal.Api.TypeScriptDefs (printTypeScriptFile)
 
 main :: IO ()
-main = pure ()
+main = printTypeScriptFile (apiInfoToTypeScriptFile apiInfo)

cardano-wasm/cardano-wasm.cabal

@@ -40,7 +40,9 @@ executable cardano-wasm
       "-optl-Wl,--strip-all,--export=getApiInfo,--export=newConwayTx,--export=addTxInput,--export=addSimpleTxOut,--export=setFee,--export=estimateMinFee,--export=signWithPaymentKey,--export=alsoSignWithPaymentKey,--export=txToCbor"
   other-modules:
     Cardano.Wasm.Internal.Api.Info
+    Cardano.Wasm.Internal.Api.InfoToTypeScript
     Cardano.Wasm.Internal.Api.Tx
+    Cardano.Wasm.Internal.Api.TypeScriptDefs
     Cardano.Wasm.Internal.ExceptionHandling
     Cardano.Wasm.Internal.JavaScript.Bridge
 
@@ -59,3 +61,31 @@ executable cardano-wasm
     build-depends:
       ghc-experimental,
       utf8-string,
+
+test-suite cardano-wasm-golden
+  type: exitcode-stdio-1.0
+  main-is: cardano-wasm-golden.hs
+  hs-source-dirs: test
+
+  if !arch(wasm32)
+    import: project-config
+    build-depends:
+      hedgehog >=1.1,
+      hedgehog-extras ^>=0.8,
+      tasty,
+      tasty-hedgehog,
+
+    ghc-options:
+      -threaded
+      -rtsopts
+      "-with-rtsopts=-N -T"
+
+    build-tool-depends:
+      cardano-wasm:cardano-wasm,
+      tasty-discover:tasty-discover,
+
+    other-modules:
+      Test.Golden.Cardano.Wasm.TypeScript
+  else
+    build-depends:
+      base

cardano-wasm/example/cardano-api.d.ts

@@ -0,0 +1,99 @@
+// cardano-api.d.ts
+
+export default initialise;
+
+/**
+ * Initialises the Cardano API.
+ * @returns A promise that resolves to the main `CardanoAPI` object.
+ */
+declare function initialise(): Promise<CardanoAPI>;
+
+/**
+ * Represents an unsigned transaction.
+ */
+declare interface UnsignedTx {
+    /**
+     * The type of the object, used for identification (the "UnsignedTx" string).
+     */
+    objectType: string;
+
+    /**
+     * Adds a simple transaction input to the transaction.
+     * @param txId The transaction ID of the input UTxO.
+     * @param txIx The index of the input within the UTxO.
+     * @returns The `UnsignedTx` object with the added input.
+     */
+    addTxInput(txId: string, txIx: number): UnsignedTx;
+
+    /**
+     * Adds a simple transaction output to the transaction.
+     * @param destAddr The destination address.
+     * @param lovelaceAmount The amount in lovelaces to output.
+     * @returns The `UnsignedTx` object with the added output.
+     */
+    addSimpleTxOut(destAddr: string, lovelaceAmount: bigint): UnsignedTx;
+
+    /**
+     * Sets the fee for the transaction.
+     * @param lovelaceAmount The fee amount in lovelaces.
+     * @returns The `UnsignedTx` object with the set fee.
+     */
+    setFee(lovelaceAmount: bigint): UnsignedTx;
+
+    /**
+     * Estimates the minimum fee for the transaction.
+     * @param protocolParams The protocol parameters.
+     * @param numKeyWitnesses The number of key witnesses.
+     * @param numByronKeyWitnesses The number of Byron key witnesses.
+     * @param totalRefScriptSize The total size of reference scripts in bytes.
+     * @returns A promise that resolves to the estimated minimum fee in lovelaces.
+     */
+    estimateMinFee(protocolParams: any, numKeyWitnesses: number, numByronKeyWitnesses: number, totalRefScriptSize: number): Promise<BigInt>;
+
+    /**
+     * Signs the transaction with a payment key.
+     * @param signingKey The signing key to witness the transaction.
+     * @returns A promise that resolves to a `SignedTx` object.
+     */
+    signWithPaymentKey(signingKey: string): Promise<SignedTx>;
+}
+
+/**
+ * Represents a signed transaction.
+ */
+declare interface SignedTx {
+    /**
+     * The type of the object, used for identification (the "SignedTx" string).
+     */
+    objectType: string;
+
+    /**
+     * Adds an extra signature to the transaction with a payment key.
+     * @param signingKey The signing key to witness the transaction.
+     * @returns The `SignedTx` object with the additional signature.
+     */
+    alsoSignWithPaymentKey(signingKey: string): SignedTx;
+
+    /**
+     * Converts the signed transaction to its CBOR representation.
+     * @returns A promise that resolves to the CBOR representation of the transaction as a hex string.
+     */
+    txToCbor(): Promise<string>;
+}
+
+/**
+ * The main Cardano API object with static methods.
+ */
+declare interface CardanoAPI {
+    /**
+     * The type of the object, used for identification (the "CardanoAPI" string).
+     */
+    objectType: string;
+
+    /**
+     * Creates a new Conway-era transaction.
+     * @returns A promise that resolves to a new `UnsignedTx` object.
+     */
+    newConwayTx(): Promise<UnsignedTx>;
+}
+

cardano-wasm/example/cardano-api.js

@@ -1,8 +1,10 @@
+/// <reference path="./cardano-api.d.ts" />
+
 import { WASI } from "https://unpkg.com/@bjorn3/[email protected]/dist/index.js";
 import ghc_wasm_jsffi from "./cardano-wasm.js";
 const __exports = {};
 const wasi = new WASI([], [], []);
-async function initialize() {
+async function initialise() {
   let { instance } = await WebAssembly.instantiateStreaming(fetch("./cardano-wasm.wasm"), {
     ghc_wasm_jsffi: ghc_wasm_jsffi(__exports),
     wasi_snapshot_preview1: wasi.wasiImport,
@@ -12,7 +14,7 @@ async function initialize() {
 
   // Wrap a function with variable arguments to make the parameters inspectable
   function fixateArgs(params, func) {
-    const paramString = params.join(',');
+    const paramString = params.map(p => p.name).join(',');
     // Dynamically create a function that captures 'func' from the closure.
     // 'this' and 'arguments' are passed through from the wrapper to 'func'.
     // Using eval allows the returned function to have named parameters for inspectability.
@@ -26,7 +28,7 @@ async function initialize() {
 
   // Same as fixateArgs but for async functions
   async function fixateArgsAsync(params, func) {
-    const paramString = params.join(',');
+    const paramString = params.map(p => p.name).join(',');
     // Dynamically create an async function.
     const wrapper = eval(`
       (async function(${paramString}) {
@@ -80,7 +82,7 @@ async function initialize() {
   });
 
   // Populate the main API object with static methods
-  apiInfo.staticMethods.forEach(method => {
+  apiInfo.mainObject.methods.forEach(method => {
     cardanoAPI[method.name] = async function (...args) {
       const resultPromise = instance.exports[method.name](...args);
 
@@ -93,4 +95,4 @@ async function initialize() {
   });
   return cardanoAPI;
 }
-export default initialize;
+export default initialise;

cardano-wasm/example/example.js

@@ -0,0 +1,38 @@
+import cardano_api from "./cardano-api.js";
+
+let promise = cardano_api();
+
+async function get_protocol_params() {
+    const response = await fetch("./preview_pparams.json");
+    return (await response.json());
+}
+
+let protocolParams = await get_protocol_params();
+
+async function do_async_work() {
+    let api = await promise;
+    console.log("Api object:");
+    console.log(api);
+
+    let emptyTx = await api.newConwayTx();
+    console.log("UnsignedTx object:");
+    console.log(emptyTx);
+
+    let tx = await emptyTx.addTxInput("be6efd42a3d7b9a00d09d77a5d41e55ceaf0bd093a8aa8a893ce70d9caafd978", 0)
+        .addSimpleTxOut("addr_test1vzpfxhjyjdlgk5c0xt8xw26avqxs52rtf69993j4tajehpcue4v2v", 10_000_000n)
+
+    let feeEstimate = await tx.estimateMinFee(protocolParams, 1, 0, 0);
+    console.log("Estimated fee:");
+    console.log(feeEstimate);
+
+    let signedTx = await tx.setFee(feeEstimate)
+        .signWithPaymentKey("addr_sk1648253w4tf6fv5fk28dc7crsjsaw7d9ymhztd4favg3cwkhz7x8sl5u3ms");
+    console.log("SignedTx object:");
+    console.log(signedTx);
+
+    let txCbor = await signedTx.txToCbor();
+    console.log("Tx CBOR:");
+    console.log(txCbor);
+}
+
+do_async_work().then(() => { });

cardano-wasm/example/index.html

@@ -1,41 +1,7 @@
 <html>
 
 <body>
-  <script type="module">
-    import cardano_api from "./cardano-api.js";
-    let promise = cardano_api();
-    async function get_protocol_params() {
-      const response = await fetch("./preview_pparams.json");
-      return (await response.json());
-    }
-    let protocolParams = await get_protocol_params();
-    async function do_async_work() {
-      let api = await promise;
-      console.log("Api object:");
-      console.log(api);
-
-      let emptyTx = await api.newConwayTx();
-      console.log("UnsignedTx object:");
-      console.log(emptyTx);
-
-      let tx = await emptyTx.addTxInput("be6efd42a3d7b9a00d09d77a5d41e55ceaf0bd093a8aa8a893ce70d9caafd978", 0)
-        .addSimpleTxOut("addr_test1vzpfxhjyjdlgk5c0xt8xw26avqxs52rtf69993j4tajehpcue4v2v", 10_000_000n)
-
-      let feeEstimate = await tx.estimateMinFee(protocolParams, 1, 0, 0);
-      console.log("Estimated fee:");
-      console.log(feeEstimate);
-
-      let signedTx = await tx.setFee(feeEstimate)
-        .signWithPaymentKey("addr_sk1648253w4tf6fv5fk28dc7crsjsaw7d9ymhztd4favg3cwkhz7x8sl5u3ms");
-      console.log("SignedTx object:");
-      console.log(signedTx);
-
-      let txCbor = await signedTx.txToCbor();
-      console.log("Tx CBOR:");
-      console.log(txCbor);
-    }
-    do_async_work().then(() => { });
-  </script>
+  <script type="module" src="./example.js"></script>
 </body>
 
 </html>