Simplify txbuilder output addition

rust/pkg/cardano_serialization_lib.js.flow

@@ -5114,44 +5114,6 @@ declare export class TransactionBuilder {
     amount: Value
   ): BigNum;
 
-  /**
-   * Add output by specifying the Address and Value
-   * @param {Address} address
-   * @param {Value} amount
-   */
-  add_output_amount(address: Address, amount: Value): void;
-
-  /**
-   * Add output by specifying the Address and Coin (BigNum)
-   * Output will have no additional assets
-   * @param {Address} address
-   * @param {BigNum} coin
-   */
-  add_output_coin(address: Address, coin: BigNum): void;
-
-  /**
-   * Add output by specifying the Address, the Coin (BigNum), and the MultiAsset
-   * @param {Address} address
-   * @param {BigNum} coin
-   * @param {MultiAsset} multiasset
-   */
-  add_output_coin_and_asset(
-    address: Address,
-    coin: BigNum,
-    multiasset: MultiAsset
-  ): void;
-
-  /**
-   * Add output by specifying the Address and the MultiAsset
-   * The output will be set to contain the minimum required amount of Coin
-   * @param {Address} address
-   * @param {MultiAsset} multiasset
-   */
-  add_output_asset_and_min_required_coin(
-    address: Address,
-    multiasset: MultiAsset
-  ): void;
-
   /**
    * Add explicit output via a TransactionOutput object
    * @param {TransactionOutput} output
@@ -5290,14 +5252,14 @@ declare export class TransactionBuilder {
    * @param {NativeScript} policy_script
    * @param {AssetName} asset_name
    * @param {Int} amount
-   * @param {Address} address
+   * @param {TransactionOutputAmountBuilder} output_builder
    * @param {BigNum} output_coin
    */
   add_mint_asset_and_output(
     policy_script: NativeScript,
     asset_name: AssetName,
     amount: Int,
-    address: Address,
+    output_builder: TransactionOutputAmountBuilder,
     output_coin: BigNum
   ): void;
 
@@ -5310,13 +5272,13 @@ declare export class TransactionBuilder {
    * @param {NativeScript} policy_script
    * @param {AssetName} asset_name
    * @param {Int} amount
-   * @param {Address} address
+   * @param {TransactionOutputAmountBuilder} output_builder
    */
   add_mint_asset_and_output_min_required_coin(
     policy_script: NativeScript,
     asset_name: AssetName,
     amount: Int,
-    address: Address
+    output_builder: TransactionOutputAmountBuilder
   ): void;
 
   /**
@@ -5717,6 +5679,80 @@ declare export class TransactionOutput {
    */
   static new(address: Address, amount: Value): TransactionOutput;
 }
+/**
+ */
+declare export class TransactionOutputAmountBuilder {
+  free(): void;
+
+  /**
+   * @param {Value} amount
+   * @returns {TransactionOutputAmountBuilder}
+   */
+  with_value(amount: Value): TransactionOutputAmountBuilder;
+
+  /**
+   * @param {BigNum} coin
+   * @returns {TransactionOutputAmountBuilder}
+   */
+  with_coin(coin: BigNum): TransactionOutputAmountBuilder;
+
+  /**
+   * @param {BigNum} coin
+   * @param {MultiAsset} multiasset
+   * @returns {TransactionOutputAmountBuilder}
+   */
+  with_coin_and_asset(
+    coin: BigNum,
+    multiasset: MultiAsset
+  ): TransactionOutputAmountBuilder;
+
+  /**
+   * @param {BigNum} coins_per_utxo_word
+   * @param {MultiAsset} multiasset
+   * @returns {TransactionOutputAmountBuilder}
+   */
+  with_asset_and_min_required_coin(
+    coins_per_utxo_word: BigNum,
+    multiasset: MultiAsset
+  ): TransactionOutputAmountBuilder;
+
+  /**
+   * @returns {TransactionOutput}
+   */
+  build(): TransactionOutput;
+}
+/**
+ * We introduce a builder-pattern format for creating transaction outputs
+ * This is because:
+ * 1. Some fields (i.e. data hash) are optional, and we can't easily expose Option<> in WASM
+ * 2. Some fields like amounts have many ways it could be set (some depending on other field values being known)
+ * 3. Easier to adapt as the output format gets more complicated in future Cardano releases
+ */
+declare export class TransactionOutputBuilder {
+  free(): void;
+
+  /**
+   * @returns {TransactionOutputBuilder}
+   */
+  static new(): TransactionOutputBuilder;
+
+  /**
+   * @param {Address} address
+   * @returns {TransactionOutputBuilder}
+   */
+  with_address(address: Address): TransactionOutputBuilder;
+
+  /**
+   * @param {DataHash} data_hash
+   * @returns {TransactionOutputBuilder}
+   */
+  with_data_hash(data_hash: DataHash): TransactionOutputBuilder;
+
+  /**
+   * @returns {TransactionOutputAmountBuilder}
+   */
+  next(): TransactionOutputAmountBuilder;
+}
 /**
  */
 declare export class TransactionOutputs {

rust/src/fees.rs

@@ -38,6 +38,7 @@ mod tests {
     use super::*;
     use crypto::*;
     use address::*;
+    use super::output_builder::TransactionOutputBuilder;
 
     // based off tx test vectors (https://gist.github.com/KtorZ/5a2089df0915f21aca368d12545ab230)
 
@@ -54,13 +55,16 @@ mod tests {
         ));
         let mut outputs = TransactionOutputs::new();
 
-        outputs.add(&TransactionOutput::new(
-            &Address::from_bytes(
-                hex::decode("611c616f1acb460668a9b2f123c80372c2adad3583b9c6cd2b1deeed1c").unwrap(),
-            )
-            .unwrap(),
-            &Value::new(&to_bignum(1)),
-        ));
+        outputs.add(
+            &TransactionOutputBuilder::new()
+                .with_address(
+                    &Address::from_bytes(
+                        hex::decode("611c616f1acb460668a9b2f123c80372c2adad3583b9c6cd2b1deeed1c").unwrap(),
+                    ).unwrap())
+                .next().unwrap()
+                .with_coin(&to_bignum(1))
+                .build().unwrap()
+            );
         let body = TransactionBody::new(&inputs, &outputs, &to_bignum(94002), Some(10));
 
         let mut w = TransactionWitnessSet::new();
@@ -99,13 +103,16 @@ mod tests {
         ));
         let mut outputs = TransactionOutputs::new();
 
-        outputs.add(&TransactionOutput::new(
-            &Address::from_bytes(
-                hex::decode("611c616f1acb460668a9b2f123c80372c2adad3583b9c6cd2b1deeed1c").unwrap(),
-            )
-            .unwrap(),
-            &Value::new(&to_bignum(1)),
-        ));
+        outputs.add(
+            &TransactionOutputBuilder::new()
+                .with_address(
+                    &Address::from_bytes(
+                        hex::decode("611c616f1acb460668a9b2f123c80372c2adad3583b9c6cd2b1deeed1c").unwrap(),
+                    ).unwrap())
+                .next().unwrap()
+                .with_coin(&to_bignum(1))
+                .build().unwrap()
+            );
         let body = TransactionBody::new(&inputs, &outputs, &to_bignum(112002), Some(10));
 
         let mut w = TransactionWitnessSet::new();
@@ -157,20 +164,27 @@ mod tests {
             7,
         ));
         let mut outputs = TransactionOutputs::new();
-        outputs.add(&TransactionOutput::new(
-            &Address::from_bytes(
-                hex::decode("611c616f1acb460668a9b2f123c80372c2adad3583b9c6cd2b1deeed1c").unwrap(),
-            )
-            .unwrap(),
-            &Value::new(&to_bignum(289)),
-        ));
-        outputs.add(&TransactionOutput::new(
-            &Address::from_bytes(
-                hex::decode("61bcd18fcffa797c16c007014e2b8553b8b9b1e94c507688726243d611").unwrap(),
-            )
-            .unwrap(),
-            &Value::new(&to_bignum(874551452)),
-        ));
+
+        outputs.add(
+            &TransactionOutputBuilder::new()
+                .with_address(
+                    &Address::from_bytes(
+                        hex::decode("611c616f1acb460668a9b2f123c80372c2adad3583b9c6cd2b1deeed1c").unwrap(),
+                    ).unwrap())
+                .next().unwrap()
+                .with_coin(&to_bignum(289))
+                .build().unwrap()
+            );
+        outputs.add(
+            &TransactionOutputBuilder::new()
+                .with_address(
+                    &Address::from_bytes(
+                        hex::decode("61bcd18fcffa797c16c007014e2b8553b8b9b1e94c507688726243d611").unwrap(),
+                    ).unwrap())
+                .next().unwrap()
+                .with_coin(&to_bignum(874551452))
+                .build().unwrap()
+            );
         let body = TransactionBody::new(&inputs, &outputs, &to_bignum(183502), Some(999));
 
         let mut w = TransactionWitnessSet::new();
@@ -216,12 +230,16 @@ mod tests {
         ));
         let mut outputs = TransactionOutputs::new();
 
-        outputs.add(&TransactionOutput::new(
-            &Address::from_bytes(
-                hex::decode("611c616f1acb460668a9b2f123c80372c2adad3583b9c6cd2b1deeed1c").unwrap()
-            ).unwrap(),
-            &Value::new(&to_bignum(1))
-        ));
+        outputs.add(
+            &TransactionOutputBuilder::new()
+                .with_address(
+                    &Address::from_bytes(
+                        hex::decode("611c616f1acb460668a9b2f123c80372c2adad3583b9c6cd2b1deeed1c").unwrap(),
+                    ).unwrap())
+                .next().unwrap()
+                .with_coin(&to_bignum(1))
+                .build().unwrap()
+            );
         let mut body = TransactionBody::new(&inputs, &outputs, &to_bignum(266002), Some(10));
 
         let mut certs = Certificates::new();
@@ -445,12 +463,16 @@ mod tests {
         ));
         let mut outputs = TransactionOutputs::new();
 
-        outputs.add(&TransactionOutput::new(
-            &Address::from_bytes(
-                hex::decode("611c616f1acb460668a9b2f123c80372c2adad3583b9c6cd2b1deeed1c").unwrap()
-            ).unwrap(),
-            &Value::new(&to_bignum(1))
-        ));
+        outputs.add(
+            &TransactionOutputBuilder::new()
+                .with_address(
+                    &Address::from_bytes(
+                        hex::decode("611c616f1acb460668a9b2f123c80372c2adad3583b9c6cd2b1deeed1c").unwrap(),
+                    ).unwrap())
+                .next().unwrap()
+                .with_coin(&to_bignum(1))
+                .build().unwrap()
+            );
         let mut body = TransactionBody::new(&inputs, &outputs, &to_bignum(162502), Some(10));
         let mut withdrawals = Withdrawals::new();
         withdrawals.insert(

rust/src/lib.rs

@@ -44,6 +44,7 @@ pub mod fees;
 pub mod impl_mockchain;
 pub mod legacy_address;
 pub mod metadata;
+pub mod output_builder;
 pub mod plutus;
 pub mod serialization;
 pub mod tx_builder;