Merge pull request #1003 from IntersectMBO/group-methods

Group static methods in `cardano-wasm` API

Author: palas

cardano-wasm/README.md

@@ -253,6 +253,16 @@ To work around that, disable build concurrency:
 wasm32-wasi-cabal build cardano-wasm -j1 --ghc-options="-j1" --no-semaphore
 ```
 
+# Documentation
+
+You can find the generated typedoc documentation for the version of `cardano-wasm` in `master` branch [here](https://cardano-api.cardano.intersectmbo.org/cardano-wasm/typedoc/).
+
+Or you can generate it using nix by writing:
+
+```bash
+nix build .#wasm-typedoc
+```
+
 # Examples
 
 You can find examples of how to use the `cardano-wasm` library in the [examples](./examples) subfolder.

cardano-wasm/examples/basic/example.js

@@ -48,13 +48,13 @@ async function do_async_work() {
 
     let PREVIEW_MAGIC_NUMBER = 2;
     let secretKey = "addr_sk1648253w4tf6fv5fk28dc7crsjsaw7d9ymhztd4favg3cwkhz7x8sl5u3ms";
-    let wallet = await api.restoreTestnetPaymentWalletFromSigningKeyBech32(PREVIEW_MAGIC_NUMBER, secretKey);
+    let wallet = await api.wallet.testnet.restoreTestnetPaymentWalletFromSigningKeyBech32(PREVIEW_MAGIC_NUMBER, secretKey);
     let bech32Address = await wallet.getAddressBech32();
 
     log("Bech32 of address:");
     log(bech32Address);
 
-    let emptyTx = await api.newTx();
+    let emptyTx = await api.tx.newTx();
     log("UnsignedTx object:");
     log(emptyTx);
 

cardano-wasm/examples/simple-wallet/example.js

@@ -11,7 +11,7 @@ async function do_async_work() {
 
   // State
   let showPrivateKey = false;
-  let wallet = await api.generateTestnetPaymentWallet(42);
+  let wallet = await api.wallet.testnet.generateTestnetPaymentWallet(42);
   let transactionInputs = [];
   let transactionOutputs = [];
 
@@ -34,7 +34,7 @@ async function do_async_work() {
   }
 
   async function makeTransaction() {
-    let tx = await api.newTx();
+    let tx = await api.tx.newTx();
     for (let input of transactionInputs) {
       tx = tx.addTxInput(input.txId, input.txIndex);
     }
@@ -55,7 +55,7 @@ async function do_async_work() {
     let pki = document.getElementById("private-key-input")
     if (showPrivateKey) {
       // @ts-ignore
-      pki.value = await wallet.getBech32ForSigningKey();
+      pki.value = await wallet.getBech32ForPaymentSigningKey();
       // @ts-ignore
       pki.disabled = false;
       // @ts-ignore
@@ -188,7 +188,7 @@ async function do_async_work() {
 
   // Callbacks
   async function generateAddress() {
-    wallet = await api.generateTestnetPaymentWallet(TESTNET_MAGIC);
+    wallet = await api.wallet.testnet.generateTestnetPaymentWallet(TESTNET_MAGIC);
     await refresh();
   }
 
@@ -239,7 +239,7 @@ async function do_async_work() {
 
   async function submitTransaction() {
     let tx = await makeTransaction();
-    let signingKey = await wallet.getBech32ForSigningKey();
+    let signingKey = await wallet.getBech32ForPaymentSigningKey();
     let signedTx = await tx.signWithPaymentKey(signingKey);
 
     await grpcApi.submitTx(await signedTx.txToCbor()).then((txId) => {

cardano-wasm/js-test/basic-test.spec.ts

@@ -8,5 +8,5 @@ test('test output matches', async ({ page }) => {
   // Wait for the test to finish running (we signal this by creating a tag with id "finish-tag" and text "Finished test!")
   await expect(page.locator('#finish-tag')).toHaveText("Finished test!");
   // Check the output of the test (from the example folder), which is displayed in the code element with id "test-output". The output contains information about the various objects and results of trying some of the functions.
-  await expect(page.locator('#test-output')).toHaveText("> \"Api object:\"> [object] {    objectType: cardano-api    newTx: async function(...args)    newExperimentalEraTx: async function(...args)    newConwayTx: async function(...args)    newGrpcConnection: async function(...args)    generatePaymentWallet: async function(...args)    generateStakeWallet: async function(...args)    restorePaymentWalletFromSigningKeyBech32: async function(...args)    restoreStakeWalletFromSigningKeyBech32: async function(...args)    generateTestnetPaymentWallet: async function(...args)    generateTestnetStakeWallet: async function(...args)    restoreTestnetPaymentWalletFromSigningKeyBech32: async function(...args)    restoreTestnetStakeWalletFromSigningKeyBech32: async function(...args)  }> \"Bech32 of address:\"> \"addr_test1vp93p9em3regvgylxuvet6fgr3e9sn259pcejgrk4ykystcs7v8j6\"> \"UnsignedTx object:\"> [object] {    objectType: UnsignedTx    addTxInput: function (txId,txIx)    addSimpleTxOut: function (destAddr,lovelaceAmount)    setFee: function (lovelaceAmount)    estimateMinFee: function (protocolParams,numKeyWitnesses,numByronKeyWitnesses,totalRefScriptSize)    signWithPaymentKey: function (signingKey)  }> \"Estimated fee:\"> 164005n> \"SignedTx object:\"> [object] {    objectType: SignedTx    alsoSignWithPaymentKey: function (signingKey)    txToCbor: function ()  }> \"Tx CBOR:\"> \"84a300d9010281825820be6efd42a3d7b9a00d09d77a5d41e55ceaf0bd093a8aa8a893ce70d9caafd97800018182581d6082935e44937e8b530f32ce672b5d600d0a286b4e8a52c6555f659b871a00989680021a000280a5a100d9010281825820adfc1c30385916da87db1ba3328f0690a57ebb2a6ac9f6f86b2d97f943adae005840a49259b5977aea523b46f01261fbff93e0899e8700319e11f5ab96b67eb628fca1a233ce2d50ee3227b591b84f27237d920d63974d65728362382f751c4d9400f5f6\"");
+  await expect(page.locator('#test-output')).toHaveText("> \"Api object:\"> [object] {    objectType: cardano-api    tx: [object Object]    newGrpcConnection: async function (...args)    wallet: [object Object]  }> \"Bech32 of address:\"> \"addr_test1vp93p9em3regvgylxuvet6fgr3e9sn259pcejgrk4ykystcs7v8j6\"> \"UnsignedTx object:\"> [object] {    objectType: UnsignedTx    addTxInput: function (txId,txIx)    addSimpleTxOut: function (destAddr,lovelaceAmount)    setFee: function (lovelaceAmount)    estimateMinFee: function (protocolParams,numKeyWitnesses,numByronKeyWitnesses,totalRefScriptSize)    signWithPaymentKey: function (signingKey)  }> \"Estimated fee:\"> 164005n> \"SignedTx object:\"> [object] {    objectType: SignedTx    alsoSignWithPaymentKey: function (signingKey)    txToCbor: function ()  }> \"Tx CBOR:\"> \"84a300d9010281825820be6efd42a3d7b9a00d09d77a5d41e55ceaf0bd093a8aa8a893ce70d9caafd97800018182581d6082935e44937e8b530f32ce672b5d600d0a286b4e8a52c6555f659b871a00989680021a000280a5a100d9010281825820adfc1c30385916da87db1ba3328f0690a57ebb2a6ac9f6f86b2d97f943adae005840a49259b5977aea523b46f01261fbff93e0899e8700319e11f5ab96b67eb628fca1a233ce2d50ee3227b591b84f27237d920d63974d65728362382f751c4d9400f5f6\"");
 });

cardano-wasm/lib-wrapper/cardano-api.d.ts

@@ -16,22 +16,27 @@ declare interface CardanoApi {
     objectType: string;
 
     /**
-     * Create a new unsigned transaction in the current era (currently Conway).
-     * @returns A promise that resolves to a new `UnsignedTx` object.
+     * Methods for creating unsigned transactions.
      */
-    newTx(): Promise<UnsignedTx>;
-
-    /**
-     * Create a new unsigned transaction in the current experimental era (currently unavailable).
-     * @returns A promise that resolves to a new `UnsignedTx` object.
-     */
-    newExperimentalEraTx(): Promise<UnsignedTx>;
-
-    /**
-     * Create a new unsigned transaction in the Conway era.
-     * @returns A promise that resolves to a new `UnsignedTx` object.
-     */
-    newConwayTx(): Promise<UnsignedTx>;
+    tx: {
+        /**
+         * Create a new unsigned transaction in the current era (currently Conway).
+         * @returns A promise that resolves to a new `UnsignedTx` object.
+         */
+        newTx(): Promise<UnsignedTx>;
+
+        /**
+         * Create a new unsigned transaction in the current experimental era (currently unavailable).
+         * @returns A promise that resolves to a new `UnsignedTx` object.
+         */
+        newExperimentalEraTx(): Promise<UnsignedTx>;
+
+        /**
+         * Create a new unsigned transaction in the Conway era.
+         * @returns A promise that resolves to a new `UnsignedTx` object.
+         */
+        newConwayTx(): Promise<UnsignedTx>;
+    }
 
     /**
      * Create a new client connection for communicating with a Cardano node through gRPC-web.
@@ -41,62 +46,77 @@ declare interface CardanoApi {
     newGrpcConnection(webGrpcUrl: string): Promise<GrpcConnection>;
 
     /**
-     * Generate a simple payment wallet for mainnet.
-     * @returns A promise that resolves to a new `Wallet` object.
-     */
-    generatePaymentWallet(): Promise<Wallet>;
-
-    /**
-     * Generate a stake wallet for mainnet.
-     * @returns A promise that resolves to a new `Wallet` object.
-     */
-    generateStakeWallet(): Promise<Wallet>;
-
-    /**
-     * Restore a mainnet payment wallet from a Bech32 encoded signing key.
-     * @param signingKeyBech32 The Bech32 encoded signing key.
-     * @returns A promise that resolves to a new `Wallet` object.
-     */
-    restorePaymentWalletFromSigningKeyBech32(signingKeyBech32: string): Promise<Wallet>;
-
-    /**
-     * Restore a mainnet stake wallet from Bech32 encoded signing keys.
-     * @param paymentSigningKeyBech32 The Bech32 encoded payment signing key.
-     * @param stakeSigningKeyBech32 The Bech32 encoded stake signing key.
-     * @returns A promise that resolves to a new `Wallet` object.
-     */
-    restoreStakeWalletFromSigningKeyBech32(paymentSigningKeyBech32: string, stakeSigningKeyBech32: string): Promise<Wallet>;
-
-    /**
-     * Generate a simple payment wallet for testnet, given the testnet's network magic.
-     * @param networkMagic The network magic for the testnet.
-     * @returns A promise that resolves to a new `Wallet` object.
-     */
-    generateTestnetPaymentWallet(networkMagic: number): Promise<Wallet>;
-
-    /**
-     * Generate a stake wallet for testnet, given the testnet's network magic.
-     * @param networkMagic The network magic for the testnet.
-     * @returns A promise that resolves to a new `Wallet` object.
-     */
-    generateTestnetStakeWallet(networkMagic: number): Promise<Wallet>;
-
-    /**
-     * Restore a testnet payment wallet from a Bech32 encoded signing key.
-     * @param networkMagic The network magic for the testnet.
-     * @param signingKeyBech32 The Bech32 encoded signing key.
-     * @returns A promise that resolves to a new `Wallet` object.
-     */
-    restoreTestnetPaymentWalletFromSigningKeyBech32(networkMagic: number, signingKeyBech32: string): Promise<Wallet>;
-
-    /**
-     * Restore a testnet stake wallet from Bech32 encoded signing keys.
-     * @param networkMagic The network magic for the testnet.
-     * @param paymentSigningKeyBech32 The Bech32 encoded payment signing key.
-     * @param stakeSigningKeyBech32 The Bech32 encoded stake signing key.
-     * @returns A promise that resolves to a new `Wallet` object.
+     * Methods for generating and restoring wallets.
      */
-    restoreTestnetStakeWalletFromSigningKeyBech32(networkMagic: number, paymentSigningKeyBech32: string, stakeSigningKeyBech32: string): Promise<Wallet>;
+    wallet: {
+        /**
+         * Methods for mainnet wallets.
+         */
+        mainnet: {
+            /**
+             * Generate a simple payment wallet for mainnet.
+             * @returns A promise that resolves to a new `Wallet` object.
+             */
+            generatePaymentWallet(): Promise<Wallet>;
+
+            /**
+             * Generate a stake wallet for mainnet.
+             * @returns A promise that resolves to a new `Wallet` object.
+             */
+            generateStakeWallet(): Promise<Wallet>;
+
+            /**
+             * Restore a mainnet payment wallet from a Bech32 encoded signing key.
+             * @param signingKeyBech32 The Bech32 encoded signing key.
+             * @returns A promise that resolves to a new `Wallet` object.
+             */
+            restorePaymentWalletFromSigningKeyBech32(signingKeyBech32: string): Promise<Wallet>;
+
+            /**
+             * Restore a mainnet stake wallet from Bech32 encoded signing keys.
+             * @param paymentSigningKeyBech32 The Bech32 encoded payment signing key.
+             * @param stakeSigningKeyBech32 The Bech32 encoded stake signing key.
+             * @returns A promise that resolves to a new `Wallet` object.
+             */
+            restoreStakeWalletFromSigningKeyBech32(paymentSigningKeyBech32: string, stakeSigningKeyBech32: string): Promise<Wallet>;
+        }
+
+        /**
+         * Methods for wallets in other networks.
+         */
+        testnet: {
+            /**
+             * Generate a simple payment wallet for testnet, given the testnet's network magic.
+             * @param networkMagic The network magic for the testnet.
+             * @returns A promise that resolves to a new `Wallet` object.
+             */
+            generateTestnetPaymentWallet(networkMagic: number): Promise<Wallet>;
+
+            /**
+             * Generate a stake wallet for testnet, given the testnet's network magic.
+             * @param networkMagic The network magic for the testnet.
+             * @returns A promise that resolves to a new `Wallet` object.
+             */
+            generateTestnetStakeWallet(networkMagic: number): Promise<Wallet>;
+
+            /**
+             * Restore a testnet payment wallet from a Bech32 encoded signing key.
+             * @param networkMagic The network magic for the testnet.
+             * @param signingKeyBech32 The Bech32 encoded signing key.
+             * @returns A promise that resolves to a new `Wallet` object.
+             */
+            restoreTestnetPaymentWalletFromSigningKeyBech32(networkMagic: number, signingKeyBech32: string): Promise<Wallet>;
+
+            /**
+             * Restore a testnet stake wallet from Bech32 encoded signing keys.
+             * @param networkMagic The network magic for the testnet.
+             * @param paymentSigningKeyBech32 The Bech32 encoded payment signing key.
+             * @param stakeSigningKeyBech32 The Bech32 encoded stake signing key.
+             * @returns A promise that resolves to a new `Wallet` object.
+             */
+            restoreTestnetStakeWalletFromSigningKeyBech32(networkMagic: number, paymentSigningKeyBech32: string, stakeSigningKeyBech32: string): Promise<Wallet>;
+        }
+    }
 }
 
 /**

cardano-wasm/lib-wrapper/main.js

@@ -22,7 +22,7 @@ export function createInitializer(getWasi, loadWasmModule, createClient) {
     /**
      * Convert Base64 to Base16 encoding
      */
-    base64ToHex: function(base64) {
+    base64ToHex: function (base64) {
       if (typeof atob === 'function') {
         const binary = atob(base64);
         return [...binary].reduce((hex, char) => {
@@ -88,19 +88,32 @@ export function createInitializer(getWasi, loadWasmModule, createClient) {
     const apiInfo = await instance.exports.getApiInfo();
     let makers = {};
     let cardanoApi = { objectType: "cardano-api" };
+
     // Create maker functions for each virtual object type
+
+    function populateMethodOrGroup(methodPopulator, methodOrGroup, target) {
+      if (methodOrGroup.type === "method") {
+        methodPopulator(methodOrGroup.method, target);
+      } else if (methodOrGroup.type === "group") {
+        let group = methodOrGroup.group;
+        target = target[group.name] = {};
+        group.methods.forEach(methodOrGroup =>
+          populateMethodOrGroup(methodPopulator, methodOrGroup, target)
+        );
+      }
+    }
+
     apiInfo.virtualObjects.forEach(vo => {
-      makers[vo.objectName] = function(initialHaskellValuePromise) {
+      makers[vo.objectName] = function (initialHaskellValuePromise) {
         // currentHaskellValueProvider is a function that returns a Promise for the Haskell value
         // It starts with the initial value promise and fluent methods accumulate transformations
         let currentHaskellValueProvider = () => initialHaskellValuePromise;
-        let jsObject = { objectType: vo.objectName };
 
-        vo.methods.forEach(method => {
+        function populateDynamicMethod(method, target) {
           if (method.return.type === "fluent") {
             // Fluent methods are synchronous and update the provider
             // A fluent method is one that returns the same object type
-            jsObject[method.name] = fixateArgs(method.params, function(...args) {
+            target[method.name] = fixateArgs(method.params, function (...args) {
               const previousProvider = currentHaskellValueProvider;
               // We update the provider so that it resolves the previous provider and chains the next call
               currentHaskellValueProvider = async () => {
@@ -111,7 +124,7 @@ export function createInitializer(getWasi, loadWasmModule, createClient) {
             });
           } else {
             // Non-fluent methods (newObject or other) are async and apply the accumulated method calls
-            jsObject[method.name] = fixateArgs(method.params, async function(...args) {
+            target[method.name] = fixateArgs(method.params, async function (...args) {
               const haskellValue = await currentHaskellValueProvider(); // Resolve accumulated method calls
               const resultPromise = instance.exports[method.name](haskellValue, ...args); // Call the non-fluent method
 
@@ -122,14 +135,27 @@ export function createInitializer(getWasi, loadWasmModule, createClient) {
               }
             });
           }
+        }
+
+        let jsObject = { objectType: vo.objectName };
+
+        vo.methods.forEach(method => {
+          populateMethodOrGroup(populateDynamicMethod, method, jsObject);
         });
         return jsObject;
       };
     });
 
     // Populate the main API object with static methods
-    apiInfo.mainObject.methods.forEach(method => {
-      cardanoApi[method.name] = async function(...args) {
+
+    function populateStaticMethod(method, target) {
+      target[method.name] = async function (...args) {
+        if (method.group) {
+          if (!target[method.group]) {
+            target[method.group] = {};
+          }
+          target = target[method.group];
+        }
         const resultPromise = instance.exports[method.name](...args);
 
         if (method.return.type === "newObject") { // Create a new object
@@ -138,6 +164,10 @@ export function createInitializer(getWasi, loadWasmModule, createClient) {
           return resultPromise;
         }
       };
+    }
+
+    apiInfo.mainObject.methods.forEach(methodOrGroup => {
+      populateMethodOrGroup(populateStaticMethod, methodOrGroup, cardanoApi);
     });
 
     return cardanoApi;

cardano-wasm/npm-wrapper/README.md

@@ -39,7 +39,7 @@ Create an `index.js` file:
 
     // 3. Now you can use the API to perform Cardano operations.
     //    For example, let's create a new transaction body.
-    const tx = await api.newTx();
+    const tx = await api.tx.newTx();
     console.log("New Transaction Body Created:", tx);
 
     // You can now build upon the 'tx' object to add inputs, outputs, etc.

cardano-wasm/npm-wrapper/api.test.js

@@ -23,12 +23,13 @@ describe('Cardano API', () => {
         const outputAddress = "addr_test1vzpfxhjyjdlgk5c0xt8xw26avqxs52rtf69993j4tajehpcue4v2v";
 
         // Restore wallet and verify the address
-        const wallet = await api.restoreTestnetPaymentWalletFromSigningKeyBech32(PREVIEW_MAGIC_NUMBER, secretKey);
+        const wallet = await api.wallet.testnet.restoreTestnetPaymentWalletFromSigningKeyBech32(PREVIEW_MAGIC_NUMBER, secretKey);
+        
         const bech32Address = await wallet.getAddressBech32();
         expect(bech32Address).toBe(expectedAddress);
 
         // Create a new transaction
-        const emptyTx = await api.newTx();
+        const emptyTx = await api.tx.newTx();
         expect(emptyTx).toBeDefined();
 
         // Add inputs and outputs