Merge pull request #231 from Emurgo/ruslan/add-mint-and-metadata

Mint and simpler metadata in tx-builder

Author: vsubhuman

.github/workflows/pr-checks.yml

@@ -41,3 +41,30 @@ jobs:
       - name: rust:build-browser
         run: |
           npm run rust:build-browser
+  check-warns:
+    if: github.event.review && (github.event.review.state == 'approved' || contains(github.event.review.body, '/check'))
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          submodules: 'recursive'
+      - uses: actions/setup-node@v1
+        with:
+          node-version: '12.18.1'
+      - name: Cache node modules
+        uses: actions/cache@v1
+        with:
+          path: ~/.npm # npm cache files are stored in `~/.npm` on Linux/macOS
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-build-${{ env.cache-name }}-
+            ${{ runner.os }}-build-
+            ${{ runner.os }}-
+      - name: prepare-rust
+        run: |
+          rustup install stable
+          rustup target add wasm32-unknown-unknown --toolchain stable
+          curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
+      - name: rust:check-warnings
+        run: |
+          npm run rust:check-warnings

package.json

@@ -9,12 +9,16 @@
     "rust:build-asm": "(rimraf ./rust/pkg && cd rust; wasm-pack build --target=browser; wasm-pack pack) && npm run asm:build && npm run js:flowgen",
     "rust:publish": "cd rust && cargo publish && cd ../",
     "asm:build": "./binaryen/bin/wasm2js ./rust/pkg/cardano_serialization_lib_bg.wasm --output ./rust/pkg/cardano_serialization_lib.asm.js && node ./scripts/wasm-to-asm",
+    "rust:check-warnings": "(cd rust; RUSTFLAGS=\"-D warnings\" cargo +stable build)",
     "rust:test": "(cd rust; cargo test)",
     "js:flowgen": "flowgen ./rust/pkg/cardano_serialization_lib.d.ts -o ./rust/pkg/cardano_serialization_lib.js.flow --add-flow-header",
     "js:prepublish": "npm run rust:test && rimraf ./publish && cp -r ./rust/pkg ./publish && cp README.md publish/ && cp LICENSE publish/",
-    "js:publish-nodejs": "npm run rust:build-nodejs && npm run js:prepublish && node ./scripts/publish-helper -nodejs && cd publish && npm publish --access public",
-    "js:publish-browser": "npm run rust:build-browser && npm run js:prepublish && node ./scripts/publish-helper -browser && cd publish && npm publish --access public",
-    "js:publish-asm": "npm run rust:build-asm && npm run js:prepublish && node ./scripts/publish-helper -asmjs && cd publish && npm publish --access public",
+    "js:publish-nodejs:prod": "npm run rust:build-nodejs && npm run js:prepublish && node ./scripts/publish-helper -nodejs && cd publish && npm publish --access public",
+    "js:publish-nodejs:beta": "npm run rust:build-nodejs && npm run js:prepublish && node ./scripts/publish-helper -nodejs && cd publish && npm publish --tag beta --access public",
+    "js:publish-browser:prod": "npm run rust:build-browser && npm run js:prepublish && node ./scripts/publish-helper -browser && cd publish && npm publish --access public",
+    "js:publish-browser:beta": "npm run rust:build-browser && npm run js:prepublish && node ./scripts/publish-helper -browser && cd publish && npm publish --tag beta --access public",
+    "js:publish-asm:prod": "npm run rust:build-asm && npm run js:prepublish && node ./scripts/publish-helper -asmjs && cd publish && npm publish --access public",
+    "js:publish-asm:beta": "npm run rust:build-asm && npm run js:prepublish && node ./scripts/publish-helper -asmjs && cd publish && npm publish --tag beta --access public",
     "postinstall": "git submodule update --init --recursive && cd binaryen; cmake . && make"
   },
   "husky": {

rust/pkg/cardano_serialization_lib.js.flow

@@ -293,6 +293,14 @@ declare export var RedeemerTagKind: {|
   +Reward: 3, // 3
 |};
 
+/**
+ */
+
+declare export var CoinSelectionStrategyCIP2: {|
+  +LargestFirst: 0, // 0
+  +RandomImprove: 1, // 1
+|};
+
 /**
  * Used to choosed the schema for a script JSON string
  */
@@ -322,14 +330,6 @@ declare export var MetadataJsonSchema: {|
   +DetailedSchema: 2, // 2
 |};
 
-/**
- */
-
-declare export var CoinSelectionStrategyCIP2: {|
-  +LargestFirst: 0, // 0
-  +RandomImprove: 1, // 1
-|};
-
 /**
  */
 
@@ -2434,6 +2434,13 @@ declare export class Mint {
    */
   static new(): Mint;
 
+  /**
+   * @param {ScriptHash} key
+   * @param {MintAssets} value
+   * @returns {Mint}
+   */
+  static new_from_entry(key: ScriptHash, value: MintAssets): Mint;
+
   /**
    * @returns {number}
    */
@@ -2456,6 +2463,18 @@ declare export class Mint {
    * @returns {ScriptHashes}
    */
   keys(): ScriptHashes;
+
+  /**
+   * Returns the multiasset where only positive (minting) entries are present
+   * @returns {MultiAsset}
+   */
+  as_positive_multiasset(): MultiAsset;
+
+  /**
+   * Returns the multiasset where only negative (burning) entries are present
+   * @returns {MultiAsset}
+   */
+  as_negative_multiasset(): MultiAsset;
 }
 /**
  */
@@ -2467,6 +2486,13 @@ declare export class MintAssets {
    */
   static new(): MintAssets;
 
+  /**
+   * @param {AssetName} key
+   * @param {Int} value
+   * @returns {MintAssets}
+   */
+  static new_from_entry(key: AssetName, value: Int): MintAssets;
+
   /**
    * @returns {number}
    */
@@ -5027,6 +5053,45 @@ declare export class TransactionBuilder {
   ): 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
    */
   add_output(output: TransactionOutput): void;
@@ -5064,11 +5129,123 @@ declare export class TransactionBuilder {
   set_withdrawals(withdrawals: Withdrawals): void;
 
   /**
+   * @returns {AuxiliaryData | void}
+   */
+  get_auxiliary_data(): AuxiliaryData | void;
+
+  /**
+   * Set explicit auxiliary data via an AuxiliaryData object
+   * It might contain some metadata plus native or Plutus scripts
    * @param {AuxiliaryData} auxiliary_data
    */
   set_auxiliary_data(auxiliary_data: AuxiliaryData): void;
 
   /**
+   * Set metadata using a GeneralTransactionMetadata object
+   * It will be set to the existing or new auxiliary data in this builder
+   * @param {GeneralTransactionMetadata} metadata
+   */
+  set_metadata(metadata: GeneralTransactionMetadata): void;
+
+  /**
+   * Add a single metadatum using TransactionMetadatumLabel and TransactionMetadatum objects
+   * It will be securely added to existing or new metadata in this builder
+   * @param {BigNum} key
+   * @param {TransactionMetadatum} val
+   */
+  add_metadatum(key: BigNum, val: TransactionMetadatum): void;
+
+  /**
+   * Add a single JSON metadatum using a TransactionMetadatumLabel and a String
+   * It will be securely added to existing or new metadata in this builder
+   * @param {BigNum} key
+   * @param {string} val
+   */
+  add_json_metadatum(key: BigNum, val: string): void;
+
+  /**
+   * Add a single JSON metadatum using a TransactionMetadatumLabel, a String, and a MetadataJsonSchema object
+   * It will be securely added to existing or new metadata in this builder
+   * @param {BigNum} key
+   * @param {string} val
+   * @param {number} schema
+   */
+  add_json_metadatum_with_schema(
+    key: BigNum,
+    val: string,
+    schema: number
+  ): void;
+
+  /**
+   * Set explicit Mint object to this builder
+   * it will replace any previously existing mint
+   * @param {Mint} mint
+   */
+  set_mint(mint: Mint): void;
+
+  /**
+   * Add a mint entry to this builder using a PolicyID and MintAssets object
+   * It will be securely added to existing or new Mint in this builder
+   * It will replace any existing mint assets with the same PolicyID
+   * @param {ScriptHash} policy_id
+   * @param {MintAssets} mint_assets
+   */
+  set_mint_asset(policy_id: ScriptHash, mint_assets: MintAssets): void;
+
+  /**
+   * Add a mint entry to this builder using a PolicyID, AssetName, and Int object for amount
+   * It will be securely added to existing or new Mint in this builder
+   * It will replace any previous existing amount same PolicyID and AssetName
+   * @param {ScriptHash} policy_id
+   * @param {AssetName} asset_name
+   * @param {Int} amount
+   */
+  add_mint_asset(
+    policy_id: ScriptHash,
+    asset_name: AssetName,
+    amount: Int
+  ): void;
+
+  /**
+   * Add a mint entry together with an output to this builder
+   * Using a PolicyID, AssetName, Int for amount, Address, and Coin (BigNum) objects
+   * The asset will be securely added to existing or new Mint in this builder
+   * A new output will be added with the specified Address, the Coin value, and the minted asset
+   * @param {ScriptHash} policy_id
+   * @param {AssetName} asset_name
+   * @param {Int} amount
+   * @param {Address} address
+   * @param {BigNum} output_coin
+   */
+  add_mint_asset_and_output(
+    policy_id: ScriptHash,
+    asset_name: AssetName,
+    amount: Int,
+    address: Address,
+    output_coin: BigNum
+  ): void;
+
+  /**
+   * Add a mint entry together with an output to this builder
+   * Using a PolicyID, AssetName, Int for amount, and Address objects
+   * The asset will be securely added to existing or new Mint in this builder
+   * A new output will be added with the specified Address and the minted asset
+   * The output will be set to contain the minimum required amount of Coin
+   * @param {ScriptHash} policy_id
+   * @param {AssetName} asset_name
+   * @param {Int} amount
+   * @param {Address} address
+   */
+  add_mint_asset_and_output_min_required_coin(
+    policy_id: ScriptHash,
+    asset_name: AssetName,
+    amount: Int,
+    address: Address
+  ): void;
+
+  /**
+   * If set to true, add_change_if_needed will try
+   * to put pure Coin in a separate output from assets
    * @param {boolean} prefer_pure_change
    */
   set_prefer_pure_change(prefer_pure_change: boolean): void;
@@ -5121,6 +5298,9 @@ declare export class TransactionBuilder {
 
   /**
    * Warning: this function will mutate the /fee/ field
+   * Make sure to call this function last after setting all other tx-body properties
+   * Editing inputs, outputs, mint, etc. after change been calculated
+   * might cause a mismatch in calculated fee versus the required fee
    * @param {Address} address
    * @returns {boolean}
    */
@@ -5137,10 +5317,21 @@ declare export class TransactionBuilder {
   output_sizes(): Uint32Array;
 
   /**
+   * Returns object the body of the new transaction
+   * Auxiliary data itself is not included
+   * You can use `get_auxiliary_date` or `build_tx`
    * @returns {TransactionBody}
    */
   build(): TransactionBody;
 
+  /**
+   * Returns full Transaction object with the body and the auxiliary data
+   * NOTE: witness_set is set to just empty set
+   * NOTE: is_valid set to true
+   * @returns {Transaction}
+   */
+  build_tx(): Transaction;
+
   /**
    * warning: sum of all parts of a transaction must equal 0. You cannot just set the fee to the min value and forget about it
    * warning: min_fee may be slightly larger than the actual minimum fee (ex: a few lovelaces)
@@ -5827,6 +6018,12 @@ declare export class Value {
    */
   static new(coin: BigNum): Value;
 
+  /**
+   * @param {MultiAsset} multiasset
+   * @returns {Value}
+   */
+  static new_from_assets(multiasset: MultiAsset): Value;
+
   /**
    * @returns {Value}
    */