Merge pull request #1240 from IntersectMBO/add-stake-signing-primitives

cardano-wasm: add stake-key witnessing (signWithStakeKey / alsoSignWithStakeKey)

Author: palas

.changes/20260701_001339_cardano-wasm_pablo.lamela_add_stake_signing_primitives.yml

@@ -0,0 +1,8 @@
+description: Added `signWithStakeKey` and `alsoSignWithStakeKey` to the `cardano-wasm`
+  API (on `UnsignedTx` and `SignedTx`), allowing transactions to be witnessed with
+  a stake key. This makes stake delegation and (de)registration transactions submittable,
+  as they require a witness from the stake credential.
+kind:
+- feature
+pr: 1240
+project: cardano-wasm

cardano-wasm/cardano-wasm.cabal

@@ -80,7 +80,7 @@ executable cardano-wasi
   if arch(wasm32)
     ghc-options:
       -no-hs-main
-      "-optl-Wl,--strip-all,--export=hs_init,--export=newTx,--export=newUpcomingEraTx,--export=addTxInput,--export=addSimpleTxOut,--export=appendCertificateToTx,--export=setFee,--export=estimateMinFee,--export=signWithPaymentKey,--export=alsoSignWithPaymentKey,--export=toCbor,--export=makeStakeAddressStakeDelegationCertificate,--export=makeStakeAddressStakeDelegationCertificateUpcomingEra,--export=makeStakeAddressRegistrationCertificate,--export=makeStakeAddressRegistrationCertificateUpcomingEra,--export=makeStakeAddressUnregistrationCertificate,--export=makeStakeAddressUnregistrationCertificateUpcomingEra,--export=generatePaymentWallet,--export=generateStakeWallet,--export=restorePaymentWalletFromSigningKeyBech32,--export=restoreStakeWalletFromSigningKeyBech32,--export=generateTestnetPaymentWallet,--export=generateTestnetStakeWallet,--export=restoreTestnetPaymentWalletFromSigningKeyBech32,--export=restoreTestnetStakeWalletFromSigningKeyBech32,--export=getAddressBech32,--export=getBech32ForPaymentVerificationKey,--export=getBech32ForPaymentSigningKey,--export=getBech32ForStakeVerificationKey,--export=getBech32ForStakeSigningKey,--export=getBase16ForPaymentVerificationKeyHash,--export=getBase16ForStakeVerificationKeyHash,--export=mallocNBytes,--export=getStrLen,--export=freeMemory"
+      "-optl-Wl,--strip-all,--export=hs_init,--export=newTx,--export=newUpcomingEraTx,--export=addTxInput,--export=addSimpleTxOut,--export=appendCertificateToTx,--export=setFee,--export=estimateMinFee,--export=signWithPaymentKey,--export=signWithStakeKey,--export=alsoSignWithPaymentKey,--export=alsoSignWithStakeKey,--export=toCbor,--export=makeStakeAddressStakeDelegationCertificate,--export=makeStakeAddressStakeDelegationCertificateUpcomingEra,--export=makeStakeAddressRegistrationCertificate,--export=makeStakeAddressRegistrationCertificateUpcomingEra,--export=makeStakeAddressUnregistrationCertificate,--export=makeStakeAddressUnregistrationCertificateUpcomingEra,--export=generatePaymentWallet,--export=generateStakeWallet,--export=restorePaymentWalletFromSigningKeyBech32,--export=restoreStakeWalletFromSigningKeyBech32,--export=generateTestnetPaymentWallet,--export=generateTestnetStakeWallet,--export=restoreTestnetPaymentWalletFromSigningKeyBech32,--export=restoreTestnetStakeWalletFromSigningKeyBech32,--export=getAddressBech32,--export=getBech32ForPaymentVerificationKey,--export=getBech32ForPaymentSigningKey,--export=getBech32ForStakeVerificationKey,--export=getBech32ForStakeSigningKey,--export=getBase16ForPaymentVerificationKeyHash,--export=getBase16ForStakeVerificationKeyHash,--export=mallocNBytes,--export=getStrLen,--export=freeMemory"
   other-modules:
     Cardano.Wasi.Internal.Api.Certificate.StakeCertificate
     Cardano.Wasi.Internal.Api.GRPC

cardano-wasm/js-test/basic-test.golden

@@ -17,13 +17,15 @@
     setFee: function (lovelaceAmount) 
     estimateMinFee: function (protocolParams,numKeyWitnesses,numByronKeyWitnesses,totalRefScriptSize) 
     signWithPaymentKey: function (signingKey) 
+    signWithStakeKey: function (signingKey) 
   }
 > "Estimated fee:"
 > 164005n
 > "SignedTx object:"
 > [object] {
     objectType: SignedTx
     alsoSignWithPaymentKey: function (signingKey) 
+    alsoSignWithStakeKey: function (signingKey) 
     txToCbor: function () 
   }
 > "Tx CBOR:"

cardano-wasm/lib-wrapper/signed-tx.d.ts

@@ -18,6 +18,13 @@ declare interface SignedTx {
      */
     alsoSignWithPaymentKey(signingKey: string): SignedTx;
 
+    /**
+     * Adds an extra signature to the transaction with a stake key.
+     * @param signingKey The signing key to witness the transaction.
+     * @returns The `SignedTx` object with the additional signature.
+     */
+    alsoSignWithStakeKey(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.

cardano-wasm/lib-wrapper/unsigned-tx.d.ts

@@ -59,6 +59,13 @@ declare interface UnsignedTx {
      * @returns A promise that resolves to a `SignedTx` object.
      */
     signWithPaymentKey(signingKey: string): Promise<SignedTx>;
+
+    /**
+     * Signs the transaction with a stake key.
+     * @param signingKey The signing key to witness the transaction.
+     * @returns A promise that resolves to a `SignedTx` object.
+     */
+    signWithStakeKey(signingKey: string): Promise<SignedTx>;
 }
 
 export default UnsignedTx;

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

@@ -46,4 +46,78 @@ describe('Cardano API', () => {
         expect(txCbor).toBe("84a300d9010281825820be6efd42a3d7b9a00d09d77a5d41e55ceaf0bd093a8aa8a893ce70d9caafd97800018182581d6082935e44937e8b530f32ce672b5d600d0a286b4e8a52c6555f659b871a0098968002192710a100d9010281825820adfc1c30385916da87db1ba3328f0690a57ebb2a6ac9f6f86b2d97f943adae0058400b19a00593e659ad0f10951f0f7d1e8a8b93112c60f67277529f91340581639e92ed4d0042ff92a0076cd69deb7e708acfdb73bb4ae79cf4bc06fd6d15efa208f5f6");
     });
 
+    // Delegation requires a witness from the stake credential, added with the stake key.
+    it('should build a delegation transaction signed with a payment key and a stake key', async () => {
+        // Test constants
+        const PREVIEW_MAGIC_NUMBER = 2;
+        const paymentSecretKey = "addr_sk1648253w4tf6fv5fk28dc7crsjsaw7d9ymhztd4favg3cwkhz7x8sl5u3ms";
+        const stakeSecretKey = "stake_sk10pu8s7rc0pu8s7rc0pu8s7rc0pu8s7rc0pu8s7rc0pu8s7rc0puqawrffl";
+        const poolId = "b".repeat(56);
+        const txInputHash = "be6efd42a3d7b9a00d09d77a5d41e55ceaf0bd093a8aa8a893ce70d9caafd978";
+        const outputAddress = "addr_test1vzpfxhjyjdlgk5c0xt8xw26avqxs52rtf69993j4tajehpcue4v2v";
+
+        // Restore a stake wallet (holds both a payment and a stake key)
+        const wallet = await api.wallet.testnet.restoreStakeWalletFromSigningKeyBech32(
+            PREVIEW_MAGIC_NUMBER, paymentSecretKey, stakeSecretKey);
+        const stakeKeyHash = await wallet.getBase16ForStakeVerificationKeyHash();
+
+        // Delegate the stake credential to a pool
+        const delegationCert = await api.certificate.mainnetEra
+            .makeStakeAddressStakeDelegationCertificate(stakeKeyHash, poolId);
+
+        // Build a transaction that includes the delegation certificate
+        const tx = (await api.tx.newTx())
+            .addTxInput(txInputHash, 0)
+            .addSimpleTxOut(outputAddress, 5_000_000n)
+            .appendCertificateToTx(delegationCert)
+            .setFee(10_000n);
+
+        // Sign with the payment key, then add a witness from the stake key
+        const signedTx = (await tx.signWithPaymentKey(paymentSecretKey))
+            .alsoSignWithStakeKey(stakeSecretKey);
+        expect(signedTx).toBeDefined();
+
+        const txCbor = await signedTx.txToCbor();
+
+        expect(txCbor).toBe("84a400d9010281825820be6efd42a3d7b9a00d09d77a5d41e55ceaf0bd093a8aa8a893ce70d9caafd97800018182581d6082935e44937e8b530f32ce672b5d600d0a286b4e8a52c6555f659b871a004c4b400219271004d901028183028200581ca9461e687627cddc5f54ffc988bc44321189538c601f1ad1b7979d9b581cbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbba100d9010282825820adfc1c30385916da87db1ba3328f0690a57ebb2a6ac9f6f86b2d97f943adae005840b5df44de4b1302d1b031363cfb9636be2f395561dcf083d1192656677506bfa401d988d745f2ee2d11ed9e563f35cc2dfbb605c7cd58a613e42377e5e2a8da01825820ee31f83c88a71219a6fcf9bee0da9bc22620588f5a15a6145553504df9649e5c58402a2a37f2391bdf3a1ff52a7ed2103473f35b43022ed101bddcb18a557f7e9f9eac75c3562b142cc15dc9ebd006da34f4076ff413914ec90e4359d757d73bfc06f5f6");
+    });
+
+    // The stake key can also be the first signer, with the payment witness added afterwards.
+    // Witnesses live in a set, so the resulting transaction is identical regardless of signing order.
+    it('should build a delegation transaction signed with a stake key and then a payment key', async () => {
+        // Test constants
+        const PREVIEW_MAGIC_NUMBER = 2;
+        const paymentSecretKey = "addr_sk1648253w4tf6fv5fk28dc7crsjsaw7d9ymhztd4favg3cwkhz7x8sl5u3ms";
+        const stakeSecretKey = "stake_sk10pu8s7rc0pu8s7rc0pu8s7rc0pu8s7rc0pu8s7rc0pu8s7rc0puqawrffl";
+        const poolId = "b".repeat(56);
+        const txInputHash = "be6efd42a3d7b9a00d09d77a5d41e55ceaf0bd093a8aa8a893ce70d9caafd978";
+        const outputAddress = "addr_test1vzpfxhjyjdlgk5c0xt8xw26avqxs52rtf69993j4tajehpcue4v2v";
+
+        // Restore a stake wallet (holds both a payment and a stake key)
+        const wallet = await api.wallet.testnet.restoreStakeWalletFromSigningKeyBech32(
+            PREVIEW_MAGIC_NUMBER, paymentSecretKey, stakeSecretKey);
+        const stakeKeyHash = await wallet.getBase16ForStakeVerificationKeyHash();
+
+        // Delegate the stake credential to a pool
+        const delegationCert = await api.certificate.mainnetEra
+            .makeStakeAddressStakeDelegationCertificate(stakeKeyHash, poolId);
+
+        // Build a transaction that includes the delegation certificate
+        const tx = (await api.tx.newTx())
+            .addTxInput(txInputHash, 0)
+            .addSimpleTxOut(outputAddress, 5_000_000n)
+            .appendCertificateToTx(delegationCert)
+            .setFee(10_000n);
+
+        // Sign with the stake key first, then add a witness from the payment key
+        const signedTx = (await tx.signWithStakeKey(stakeSecretKey))
+            .alsoSignWithPaymentKey(paymentSecretKey);
+        expect(signedTx).toBeDefined();
+
+        const txCbor = await signedTx.txToCbor();
+
+        // Identical to the payment-key-first delegation transaction above
+        expect(txCbor).toBe("84a400d9010281825820be6efd42a3d7b9a00d09d77a5d41e55ceaf0bd093a8aa8a893ce70d9caafd97800018182581d6082935e44937e8b530f32ce672b5d600d0a286b4e8a52c6555f659b871a004c4b400219271004d901028183028200581ca9461e687627cddc5f54ffc988bc44321189538c601f1ad1b7979d9b581cbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbba100d9010282825820adfc1c30385916da87db1ba3328f0690a57ebb2a6ac9f6f86b2d97f943adae005840b5df44de4b1302d1b031363cfb9636be2f395561dcf083d1192656677506bfa401d988d745f2ee2d11ed9e563f35cc2dfbb605c7cd58a613e42377e5e2a8da01825820ee31f83c88a71219a6fcf9bee0da9bc22620588f5a15a6145553504df9649e5c58402a2a37f2391bdf3a1ff52a7ed2103473f35b43022ed101bddcb18a557f7e9f9eac75c3562b142cc15dc9ebd006da34f4076ff413914ec90e4359d757d73bfc06f5f6");
+    });
+
 });

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

@@ -365,6 +365,15 @@ apiInfo =
                     , methodReturnType = NewObject (virtualObjectName signedTxObj)
                     , methodReturnDoc = "A promise that resolves to a `SignedTx` object."
                     }
+              , MethodInfoEntry $
+                  MethodInfo
+                    { methodName = "signWithStakeKey"
+                    , methodSimpleName = Nothing
+                    , methodDoc = "Signs the transaction with a stake key."
+                    , methodParams = [ParamInfo "signingKey" TSString "The signing key to witness the transaction."]
+                    , methodReturnType = NewObject (virtualObjectName signedTxObj)
+                    , methodReturnDoc = "A promise that resolves to a `SignedTx` object."
+                    }
               ]
           }
 
@@ -382,6 +391,15 @@ apiInfo =
                     , methodReturnType = Fluent
                     , methodReturnDoc = "The `SignedTx` object with the additional signature."
                     }
+              , MethodInfoEntry $
+                  MethodInfo
+                    { methodName = "alsoSignWithStakeKey"
+                    , methodSimpleName = Nothing
+                    , methodDoc = "Adds an extra signature to the transaction with a stake key."
+                    , methodParams = [ParamInfo "signingKey" TSString "The signing key to witness the transaction."]
+                    , methodReturnType = Fluent
+                    , methodReturnDoc = "The `SignedTx` object with the additional signature."
+                    }
               , MethodInfoEntry $
                   MethodInfo
                     { methodName = "txToCbor"

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

@@ -20,7 +20,9 @@ module Cardano.Wasm.Api.Tx
   , estimateMinFeeImpl
   , setFeeImpl
   , signWithPaymentKeyImpl
+  , signWithStakeKeyImpl
   , alsoSignWithPaymentKeyImpl
+  , alsoSignWithStakeKeyImpl
   , toCborImpl
   )
 where
@@ -149,12 +151,12 @@ setFeeImpl (UnsignedTxObject era (Exp.UnsignedTx tx)) fee =
     let tx' = tx & Ledger.bodyTxL . Ledger.feeTxBodyL .~ fee
      in UnsignedTxObject era $ Exp.UnsignedTx tx'
 
--- | Sign an unsigned transaction using a payment key.
-signWithPaymentKeyImpl
-  :: UnsignedTxObject -> Api.SigningKey Api.PaymentKey -> SignedTxObject
-signWithPaymentKeyImpl (UnsignedTxObject era fullUnsignedTx@(Exp.UnsignedTx tx)) signingKey =
+-- | Sign an unsigned transaction using any witness signing key.
+signWithKeyImpl
+  :: UnsignedTxObject -> Api.ShelleyWitnessSigningKey -> SignedTxObject
+signWithKeyImpl (UnsignedTxObject era fullUnsignedTx@(Exp.UnsignedTx tx)) witnessSigningKey =
   obtainCommonConstraints era $
-    let witness = Exp.makeKeyWitness era fullUnsignedTx . Api.WitnessPaymentKey $ signingKey
+    let witness = Exp.makeKeyWitness era fullUnsignedTx witnessSigningKey
         txWits =
           Ledger.mkBasicTxWits
             & Ledger.addrTxWitsL
@@ -167,6 +169,16 @@ signWithPaymentKeyImpl (UnsignedTxObject era fullUnsignedTx@(Exp.UnsignedTx tx))
           era
           (Exp.SignedTx txWithWits)
 
+-- | Sign an unsigned transaction using a payment key.
+signWithPaymentKeyImpl
+  :: UnsignedTxObject -> Api.SigningKey Api.PaymentKey -> SignedTxObject
+signWithPaymentKeyImpl unsignedTxObject = signWithKeyImpl unsignedTxObject . Api.WitnessPaymentKey
+
+-- | Sign an unsigned transaction using a stake key.
+signWithStakeKeyImpl
+  :: UnsignedTxObject -> Api.SigningKey Api.StakeKey -> SignedTxObject
+signWithStakeKeyImpl unsignedTxObject = signWithKeyImpl unsignedTxObject . Api.WitnessStakeKey
+
 newtype ProtocolParamsJSON = ProtocolParamsJSON String
 
 -- | Estimate min fees for an unsigned transaction object.
@@ -226,12 +238,12 @@ instance FromJSON SignedTxObject where
       return $
         SignedTxObject era decodedTx
 
--- | Add an extra signature to an already signed transaction using a payment key.
-alsoSignWithPaymentKeyImpl
-  :: SignedTxObject -> Api.SigningKey Api.PaymentKey -> SignedTxObject
-alsoSignWithPaymentKeyImpl (SignedTxObject era (Exp.SignedTx tx)) signingKey =
+-- | Add an extra signature to an already signed transaction using any witness signing key.
+alsoSignWithKeyImpl
+  :: SignedTxObject -> Api.ShelleyWitnessSigningKey -> SignedTxObject
+alsoSignWithKeyImpl (SignedTxObject era (Exp.SignedTx tx)) witnessSigningKey =
   obtainCommonConstraints era $
-    let witness = Exp.makeKeyWitness era (Exp.UnsignedTx tx) . Api.WitnessPaymentKey $ signingKey
+    let witness = Exp.makeKeyWitness era (Exp.UnsignedTx tx) witnessSigningKey
         txWits =
           Ledger.mkBasicTxWits
             & Ledger.addrTxWitsL
@@ -244,6 +256,16 @@ alsoSignWithPaymentKeyImpl (SignedTxObject era (Exp.SignedTx tx)) signingKey =
           era
           (Exp.SignedTx txWithWits)
 
+-- | Add an extra signature to an already signed transaction using a payment key.
+alsoSignWithPaymentKeyImpl
+  :: SignedTxObject -> Api.SigningKey Api.PaymentKey -> SignedTxObject
+alsoSignWithPaymentKeyImpl signedTxObject = alsoSignWithKeyImpl signedTxObject . Api.WitnessPaymentKey
+
+-- | Add an extra signature to an already signed transaction using a stake key.
+alsoSignWithStakeKeyImpl
+  :: SignedTxObject -> Api.SigningKey Api.StakeKey -> SignedTxObject
+alsoSignWithStakeKeyImpl signedTxObject = alsoSignWithKeyImpl signedTxObject . Api.WitnessStakeKey
+
 -- | Convert a signed transaction object to a base16 encoded string of its CBOR representation.
 toCborImpl :: SignedTxObject -> String
 toCborImpl (SignedTxObject era signedTx) =

cardano-wasm/src-wasi/Cardano/Wasi/Internal/Api/Tx.hs

@@ -9,7 +9,9 @@ module Cardano.Wasi.Internal.Api.Tx
   , setFee
   , estimateMinFee
   , signWithPaymentKey
+  , signWithStakeKey
   , alsoSignWithPaymentKey
+  , alsoSignWithStakeKey
   , toCbor
   )
 where
@@ -59,6 +61,9 @@ foreign export ccall "estimateMinFee"
 foreign export ccall "signWithPaymentKey"
   signWithPaymentKey :: UnsignedTxObjectJSON -> CString -> IO SignedTxObjectJSON
 
+foreign export ccall "signWithStakeKey"
+  signWithStakeKey :: UnsignedTxObjectJSON -> CString -> IO SignedTxObjectJSON
+
 #endif
 
 type UnsignedTxObjectJSON = CString
@@ -125,13 +130,24 @@ signWithPaymentKey unsignedTxObject signingKeyBech32 =
             <*> stringToSigningKey signingKeyBech32
         )
 
+signWithStakeKey :: UnsignedTxObjectJSON -> CString -> IO SignedTxObjectJSON
+signWithStakeKey unsignedTxObject signingKeyBech32 =
+  toCJSON
+    =<< ( signWithStakeKeyImpl
+            <$> fromCJSON True "UnsignedTx" unsignedTxObject
+            <*> stringToSigningKey signingKeyBech32
+        )
+
 -- * SignedTxObject
 
 #if defined(wasm32_HOST_ARCH)
 
 foreign export ccall "alsoSignWithPaymentKey"
   alsoSignWithPaymentKey :: SignedTxObjectJSON -> CString -> IO SignedTxObjectJSON
 
+foreign export ccall "alsoSignWithStakeKey"
+  alsoSignWithStakeKey :: SignedTxObjectJSON -> CString -> IO SignedTxObjectJSON
+
 foreign export ccall "toCbor"
   toCbor :: SignedTxObjectJSON -> IO CString
 
@@ -147,6 +163,14 @@ alsoSignWithPaymentKey signedTxObject signingKeyBech32 =
             <*> stringToSigningKey signingKeyBech32
         )
 
+alsoSignWithStakeKey :: SignedTxObjectJSON -> CString -> IO SignedTxObjectJSON
+alsoSignWithStakeKey signedTxObject signingKeyBech32 =
+  toCJSON
+    =<< ( alsoSignWithStakeKeyImpl
+            <$> fromCJSON True "SignedTx" signedTxObject
+            <*> stringToSigningKey signingKeyBech32
+        )
+
 toCbor :: SignedTxObjectJSON -> IO CString
 toCbor signedTxObject =
   newCString . toCborImpl

cardano-wasm/src-wasi/Cardano/Wasi/Internal/Conversion.hs

@@ -1,4 +1,5 @@
 {-# LANGUAGE CPP #-}
+{-# LANGUAGE FlexibleContexts #-}
 
 module Cardano.Wasi.Internal.Conversion
   ( toCJSON
@@ -55,7 +56,8 @@ txIdToString txIdCString = do
   txId <- peekCString txIdCString
   rightOrError $ Api.deserialiseFromRawBytesHex (fromString txId)
 
-stringToSigningKey :: CString -> IO (Api.SigningKey Api.PaymentKey)
+stringToSigningKey
+  :: Api.SerialiseAsBech32 (Api.SigningKey keyrole) => CString -> IO (Api.SigningKey keyrole)
 stringToSigningKey signingKeyCString = do
   string <- peekCString signingKeyCString
   rightOrError $ Api.deserialiseFromBech32 (Text.pack string)