Merge pull request #953 from IntersectMBO/newtx-and-newexperimentaleratx

Add `newTx` and `newExperimentalEraTx` functions to `cardano-wasm` API

Author: palas

cardano-wasm/examples/basic/example.js

@@ -54,7 +54,7 @@ async function do_async_work() {
     log("Bech32 of address:");
     log(bech32Address);
 
-    let emptyTx = await api.newConwayTx();
+    let emptyTx = await api.newTx();
     log("UnsignedTx object:");
     log(emptyTx);
 

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

@@ -34,7 +34,7 @@ async function do_async_work() {
   }
 
   async function makeTransaction() {
-    let tx = await api.newConwayTx();
+    let tx = await api.newTx();
     for (let input of transactionInputs) {
       tx = tx.addTxInput(input.txId, input.txIndex);
     }

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    newConwayTx: async function(...args)    newGrpcConnection: async function(...args)    generatePaymentWallet: async function(...args)    restorePaymentWalletFromSigningKeyBech32: async function(...args)    generateTestnetPaymentWallet: async function(...args)    restoreTestnetPaymentWalletFromSigningKeyBech32: 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    newTx: async function(...args)    newExperimentalEraTx: async function(...args)    newConwayTx: async function(...args)    newGrpcConnection: async function(...args)    generatePaymentWallet: async function(...args)    restorePaymentWalletFromSigningKeyBech32: async function(...args)    generateTestnetPaymentWallet: async function(...args)    restoreTestnetPaymentWalletFromSigningKeyBech32: 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\"");
 });

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

@@ -16,7 +16,19 @@ declare interface CardanoApi {
     objectType: string;
 
     /**
-     * Creates a new Conway-era transaction.
+     * 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>;

cardano-wasm/src/Cardano/Wasm/Internal/Api/Info.hs

@@ -12,6 +12,10 @@ module Cardano.Wasm.Internal.Api.Info
   )
 where
 
+import Cardano.Api (pretty)
+
+import Cardano.Wasm.Internal.Api.Tx (UnsignedTxObject (..), newExperimentalEraTxImpl, newTxImpl)
+
 import Data.Aeson qualified as Aeson
 import Data.Text qualified as Text
 import Text.Casing (fromHumps, toKebab)
@@ -150,6 +154,13 @@ instance Aeson.ToJSON ApiInfo where
       , "initialiseFunctionReturnDoc" Aeson..= initRetDoc
       ]
 
+-- | Get a comment about the era for unsigned transaction creation methods.
+getEraCommentForUnsignedTx :: Maybe UnsignedTxObject -> String
+getEraCommentForUnsignedTx utxMonad =
+  case utxMonad of
+    Just (UnsignedTxObject era _) -> "(currently " ++ show (pretty era) ++ ")"
+    Nothing -> "(currently unavailable)"
+
 -- | Provides metadata about the "virtual objects" and their methods.
 -- This is intended to help generate JavaScript wrappers.
 apiInfo :: ApiInfo
@@ -327,8 +338,28 @@ apiInfo =
               , virtualObjectDoc = "The main Cardano API object with static methods."
               , virtualObjectMethods =
                   [ MethodInfo
+                      { methodName = "newTx"
+                      , methodDoc =
+                          "Create a new unsigned transaction in the current era "
+                            ++ getEraCommentForUnsignedTx (Just newTxImpl)
+                            ++ "."
+                      , methodParams = []
+                      , methodReturnType = NewObject (virtualObjectName unsignedTxObj)
+                      , methodReturnDoc = "A promise that resolves to a new `UnsignedTx` object."
+                      }
+                  , MethodInfo
+                      { methodName = "newExperimentalEraTx"
+                      , methodDoc =
+                          "Create a new unsigned transaction in the current experimental era "
+                            ++ getEraCommentForUnsignedTx newExperimentalEraTxImpl
+                            ++ "."
+                      , methodParams = []
+                      , methodReturnType = NewObject (virtualObjectName unsignedTxObj)
+                      , methodReturnDoc = "A promise that resolves to a new `UnsignedTx` object."
+                      }
+                  , MethodInfo
                       { methodName = "newConwayTx"
-                      , methodDoc = "Creates a new Conway-era transaction."
+                      , methodDoc = "Create a new unsigned transaction in the Conway era."
                       , methodParams = []
                       , methodReturnType = NewObject (virtualObjectName unsignedTxObj)
                       , methodReturnDoc = "A promise that resolves to a new `UnsignedTx` object."

cardano-wasm/src/Cardano/Wasm/Internal/Api/Tx.hs

@@ -10,6 +10,8 @@
 module Cardano.Wasm.Internal.Api.Tx
   ( UnsignedTxObject (..)
   , ProtocolParamsJSON (..)
+  , newTxImpl
+  , newExperimentalEraTxImpl
   , newConwayTxImpl
   , addTxInputImpl
   , addSimpleTxOutImpl
@@ -30,7 +32,7 @@ import Cardano.Api.Plutus qualified as Shelley
 import Cardano.Api.Tx qualified as TxBody
 
 import Cardano.Ledger.Api qualified as Ledger
-import Cardano.Wasm.Internal.ExceptionHandling (justOrError, rightOrError, toMonadFail)
+import Cardano.Wasm.Internal.ExceptionHandling (justOrError, rightOrError, throwError, toMonadFail)
 
 import Control.Monad.Catch (MonadThrow)
 import Data.Aeson (ToJSON (toJSON), (.=))
@@ -75,6 +77,14 @@ instance FromJSON UnsignedTxObject where
         era
         <$> toMonadFail (rightOrError $ Api.deserialiseFromRawBytesHex $ Text.encodeUtf8 tx)
 
+-- | Create a new unsigned transaction object for making a transaction in the current era.
+newTxImpl :: UnsignedTxObject
+newTxImpl = newConwayTxImpl
+
+-- | Create a new unsigned transaction object for making a transaction in the current experimental era.
+newExperimentalEraTxImpl :: (HasCallStack, MonadThrow m) => m UnsignedTxObject
+newExperimentalEraTxImpl = throwError "newExperimentalEraTxImpl: No experimental era available"
+
 -- | Create a new unsigned transaction object for making a Conway era transaction.
 newConwayTxImpl :: UnsignedTxObject
 newConwayTxImpl = UnsignedTxObject Exp.ConwayEra (Exp.UnsignedTx (Ledger.mkBasicTx Ledger.mkBasicTxBody))

cardano-wasm/src/Cardano/Wasm/Internal/ExceptionHandling.hs

@@ -5,31 +5,42 @@ module Cardano.Wasm.Internal.ExceptionHandling where
 
 import Control.Exception (Exception, displayException)
 import Control.Monad.Catch (MonadThrow (..))
-import GHC.Exception (CallStack, prettyCallStack)
+import GHC.Exception (prettyCallStack)
 import GHC.Stack (HasCallStack, callStack, withFrozenCallStack)
 
-data ExpectedJustException = HasCallStack => ExpectedJustException CallStack String
+data ExpectedJustException = HasCallStack => ExpectedJustException String
 
 instance Show ExpectedJustException where
   show :: ExpectedJustException -> String
-  show (ExpectedJustException cs msg) = "Expected Just, got Nothing: " ++ msg ++ "\n" ++ prettyCallStack cs
+  show (ExpectedJustException msg) = "Expected Just, got Nothing: " ++ msg ++ "\n" ++ prettyCallStack callStack
 
 instance Exception ExpectedJustException
 
-data ExpectedRightException = HasCallStack => ExpectedRightException CallStack String
+data ExpectedRightException = HasCallStack => ExpectedRightException String
 
 instance Show ExpectedRightException where
   show :: ExpectedRightException -> String
-  show (ExpectedRightException cs msg) = "Expected Right, got Left: " ++ msg ++ "\n" ++ prettyCallStack cs
+  show (ExpectedRightException msg) = "Expected Right, got Left: " ++ msg ++ "\n" ++ prettyCallStack callStack
 
 instance Exception ExpectedRightException
 
+data CustomException = HasCallStack => CustomException String
+
+instance Show CustomException where
+  show :: CustomException -> String
+  show (CustomException msg) = "Custom exception: " ++ msg ++ "\n" ++ prettyCallStack callStack
+
+instance Exception CustomException
+
+throwError :: (HasCallStack, MonadThrow m) => String -> m a
+throwError e = withFrozenCallStack $ throwM $ CustomException e
+
 justOrError :: (HasCallStack, MonadThrow m) => String -> Maybe a -> m a
-justOrError e Nothing = withFrozenCallStack $ throwM $ ExpectedJustException callStack e
+justOrError e Nothing = withFrozenCallStack $ throwM $ ExpectedJustException e
 justOrError _ (Just a) = return a
 
 rightOrError :: (HasCallStack, MonadThrow m, Show e) => Either e a -> m a
-rightOrError (Left e) = withFrozenCallStack $ throwM $ ExpectedRightException callStack $ show e
+rightOrError (Left e) = withFrozenCallStack $ throwM $ ExpectedRightException $ show e
 rightOrError (Right a) = return a
 
 -- | Convert an 'Either' value to a 'MonadFail' monad. This can be useful for converting

cardano-wasm/src/Cardano/Wasm/Internal/JavaScript/Bridge.hs

@@ -272,6 +272,12 @@ getBase16ForVerificationKeyHash jsWallet =
 
 -- * UnsignedTxObject
 
+foreign export javascript "newTx"
+  newTx :: IO JSUnsignedTx
+
+foreign export javascript "newExperimentalEraTx"
+  newExperimentalEraTx :: IO JSUnsignedTx
+
 foreign export javascript "newConwayTx"
   newConwayTx :: IO JSUnsignedTx
 
@@ -290,6 +296,14 @@ foreign export javascript "estimateMinFee"
 foreign export javascript "signWithPaymentKey"
   signWithPaymentKey :: JSUnsignedTx -> JSSigningKey -> IO JSSignedTx
 
+-- | Create a new unsigned transaction.
+newTx :: HasCallStack => IO JSUnsignedTx
+newTx = toJSVal Wasm.newTxImpl
+
+-- | Create a new experimental era unsigned transaction.
+newExperimentalEraTx :: HasCallStack => IO JSUnsignedTx
+newExperimentalEraTx = toJSVal =<< Wasm.newExperimentalEraTxImpl
+
 -- | Create a new Conway era unsigned transaction.
 newConwayTx :: HasCallStack => IO JSUnsignedTx
 newConwayTx = toJSVal Wasm.newConwayTxImpl