Docs update without plutus (#345)

* Docs update Update docs to new crate structure. Adds CBOR and JSON explanations General updates as the docs were very outdated Replaces #307 (same without plutus + messed up git rebase/merges) * expose canonical bytes to WASM + SubCoin::from_base10_f32
dcSpark · Aug 22, 2024 · 3b6899c · 3b6899c
1 parent 0f9f49c
commit 3b6899c
Show file tree

Hide file tree

Showing 13 changed files with 343 additions and 93 deletions.
diff --git a/chain/rust/src/utils.rs b/chain/rust/src/utils.rs
@@ -12,7 +12,7 @@ use std::iter::IntoIterator;
 use crate::{
     crypto::hash::{hash_script, ScriptHashNamespace},
     plutus::{Language, PlutusScript, PlutusV1Script, PlutusV2Script, PlutusV3Script},
-    NativeScript, Script,
+    NativeScript, Script, SubCoin,
 };
 
 impl Script {
@@ -627,6 +627,20 @@ impl Deserialize for NetworkId {
     }
 }
 
+impl SubCoin {
+    /// Converts base 10 floats to SubCoin.
+    /// This is the format used by blockfrost for ex units
+    /// Warning: If the passed in float was not meant to be base 10
+    /// this might result in a slightly inaccurate fraction.
+    pub fn from_base10_f32(f: f32) -> Self {
+        let mut denom = 1u64;
+        while (f * (denom as f32)).fract().abs() > f32::EPSILON {
+            denom *= 10;
+        }
+        Self::new((f * (denom as f32)).ceil() as u64, denom)
+    }
+}
+
 // Represents the cddl: #6.258([+ T]) / [* T]
 // it DOES NOT and CAN NOT have any encoding detials per element!
 // so you can NOT use it on any primitives so must be serializable directly

diff --git a/chain/wasm/src/utils.rs b/chain/wasm/src/utils.rs
@@ -1,3 +1,5 @@
+use crate::SubCoin;
+
 use super::{Int, Script, ScriptHash};
 use cml_chain::plutus::Language;
 use wasm_bindgen::prelude::{wasm_bindgen, JsError};
@@ -86,6 +88,17 @@ impl NetworkId {
     }
 }
 
+#[wasm_bindgen]
+impl SubCoin {
+    /// Converts base 10 floats to SubCoin.
+    /// This is the format used by blockfrost for ex units
+    /// Warning: If the passed in float was not meant to be base 10
+    /// this might result in a slightly inaccurate fraction.
+    pub fn from_base10_f32(f: f32) -> Self {
+        cml_chain::SubCoin::from_base10_f32(f).into()
+    }
+}
+
 // we provide direct From/Into conversions between NonemptySet<T> and TList
 // to allow the auto-generated code to work directly without changes
 macro_rules! impl_wasm_conversions_into {

diff --git a/core/wasm/src/wasm_wrappers.rs b/core/wasm/src/wasm_wrappers.rs
@@ -417,6 +417,13 @@ macro_rules! impl_wasm_cbor_api {
                 cml_core::serialization::Serialize::to_cbor_bytes(&self.0)
             }
 
+            /**
+             * Serialize this type to CBOR bytes using canonical CBOR encodings
+             */
+            pub fn to_canonical_cbor_bytes(&self) -> Vec<u8> {
+                cml_core::serialization::Serialize::to_canonical_cbor_bytes(&self.0)
+            }
+
             /**
              * Create this type from CBOR bytes
              */
@@ -440,6 +447,13 @@ macro_rules! impl_wasm_cbor_api {
                 hex::encode(self.to_cbor_bytes())
             }
 
+            /**
+             * Serialize this type to CBOR bytes using canonical CBOR encodings as hex bytes
+             */
+            pub fn to_canonical_cbor_hex(&self) -> String {
+                hex::encode(self.to_canonical_cbor_bytes())
+            }
+
             /**
              * Create this type from the CBOR bytes encoded as a hex string.
              * This is useful for interfacing with CIP30

diff --git a/docs/docs/index.md b/docs/docs/index.md
@@ -13,16 +13,26 @@ This is a library, written in Rust, that can be deployed to multiple platforms (
 
 ##### NPM packages
 
-TODO: update these once we publish new versions:
 - browser: [link](https://www.npmjs.com/package/@dcspark/cardano-multiplatform-lib-browser)
 - nodejs: [link](https://www.npmjs.com/package/@dcspark/cardano-multiplatform-lib-nodejs)
+
+There is also an outdated asm.js . It is strongly discouraged from using this as it is out of date and asm.js results in incredibly slow cryptographic operations.
 - asm.js (strongly discouraged): [link](https://www.npmjs.com/package/@dcspark/cardano-multiplatform-lib-asmjs)
 
 Note: If you are using WebPack, you must use version 5 or later for CML to work.
 
 ##### Rust crates
 
-- crates: [link](https://crates.io/crates/cardano-multiplatform-lib)
+The rust crates are split up by functionality.
+
+- core: [link](https://crates.io/crates/cml-core)
+- crypto: [link](https://crates.io/crates/cml-crypto)
+- chain: [link](https://crates.io/crates/cml-chain)
+- multi-era: [link](https://crates.io/crates/cml-multi-era)
+- cip25: [link](https://crates.io/crates/cml-cip25)
+- cip36: [link](https://crates.io/crates/cml-cip36)
+
+Most users will likely be using primarily `cml-chain` for general uses, `cml-multi-era` if they need historical (pre-babbage eras) chain-parsing and `cip25` or `cip36` if they need those specific metadata standards.
 
 ##### Mobile bindings
 

diff --git a/docs/docs/modules/CIP25.mdx b/docs/docs/modules/CIP25.mdx
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 3
 ---
 
 # CIP25

diff --git a/docs/docs/modules/builders/generating_transactions.mdx b/docs/docs/modules/builders/generating_transactions.mdx
@@ -2,21 +2,6 @@
 sidebar_position: 4
 ---
 
-# TransactionBuilder
-
-In order to simplify transaction creation, we provide a `TransactionBuilder` struct that manages witnesses, fee calculation, change addresses and such. Assume we have instantiated an instance under the variable `builder` for this explanation. The `TransactionBuilder` requires several protocol parameters governing Cardano to be created which is shown in the following section. These are specified initially in the genesis file for Cardano nodes.
-
-The minimum required for a valid transaction is to add inputs, outputs, time-to-live and either set the fee explicitly with `builder.set_fee(fee)`, or calculate it implicitly using `builder.add_change_if_needed(address)`.
-Optionally a transaction can also have certificates, reward withdrawals, and metadata added to it.
-Any change made to the builder can impact the size and thus the fee so the fee should be the last thing set.
-If implicitly setting the fee any extra ADA (`inputs + withdrawals - outputs + refund - deposit - min fee`) is sent to the provided change address.
-Fees must be sufficient, i.e. `inputs + withdrawals + refund >= outputs + deposit + fee` which must be manually ensured if you explicitly set the fee. Any extra fee is not necessary and the extra ADA beyond that will be burned.
-Once the transaction is ready, `const body = builder.build()` can be called to return a ready `TransactionBody`.
-
-Withdrawals are ADA withdrawn as part of the rewards generated by staking and deposits are refundable ADA locked while resources such as stake certificates or pool registrations exist on the blockchain. They are returned as refunds when these resources are deregistered/retired.
-
-To get to a transaction ready to post on the blockchain, we must create a `Transaction` from that, which consists of the `TransactionBody`, a matching `TransactionWitnessSet` and optionally a `TransactionMetadata`.
-The witnesses and optional metadata must match those provided to the builder. The witnesses must sign the hash of the transaction body returned by `hash_transaction(body)`. In addition to the witnesses for inputs, withdrawals and some certificates require witnesses as well. For example, staking address registration does not require a witness while stake address de-registration requires one. For any questions or doubts about the rules governing fees, deposits, rewards, certificates or which witness types are required refer to the [shelley specs](https://github.com/input-output-hk/cardano-ledger-specs#cardano-ledger), specifically the Shelley design specification for general design. The formal specification could be useful for specific details as well. The design spec contains details about which certificates require which type of witnesses in the Certificates and Registrations section.
 
 ## Example code
 
@@ -27,95 +12,50 @@ Fees are automatically calculated and sent to a change address in the example.
 
 ```javascript
 // instantiate the tx builder with the Cardano protocol parameters - these may change later on
-const linearFee = CardanoWasm.LinearFee.new(
-    CardanoWasm.BigNum.from_str('44'),
-    CardanoWasm.BigNum.from_str('155381')
-);
-const txBuilderCfg = CardanoWasm.TransactionBuilderConfigBuilder.new()
-    .fee_algo(linearFee)
-    .pool_deposit(CardanoWasm.BigNum.from_str('500000000'))
-    .key_deposit(CardanoWasm.BigNum.from_str('2000000'))
-    .max_value_size(4000)
-    .max_tx_size(8000)
-    .coins_per_utxo_word(CardanoWasm.BigNum.from_str('34482'))
-    .build();
-const txBuilder = CardanoWasm.TransactionBuilder.new(txBuilderCfg);
-
+const txBuilder = makeTxBuilder();
+const testnetId = 0;
 // add a keyhash input - for ADA held in a Shelley-era normal address (Base, Enterprise, Pointer)
-const prvKey = CardanoWasm.PrivateKey.from_bech32("ed25519e_sk16rl5fqqf4mg27syjzjrq8h3vq44jnnv52mvyzdttldszjj7a64xtmjwgjtfy25lu0xmv40306lj9pcqpa6slry9eh3mtlqvfjz93vuq0grl80");
-txBuilder.add_key_input(
-    prvKey.to_public().hash(),
-    CardanoWasm.TransactionInput.new(
-        CardanoWasm.TransactionHash.from_bytes(
-            Buffer.from("8561258e210352fba2ac0488afed67b3427a27ccf1d41ec030c98a8199bc22ec", "hex")
-        ), // tx hash
+const prvKey = CML.PrivateKey.from_bech32("ed25519e_sk16rl5fqqf4mg27syjzjrq8h3vq44jnnv52mvyzdttldszjj7a64xtmjwgjtfy25lu0xmv40306lj9pcqpa6slry9eh3mtlqvfjz93vuq0grl80");
+const inputAddr = CML.EnterpriseAddress.new(testnetId, CML.StakeCredential.new_key(prvKey.to_public().hash())).to_address();
+txBuilder.add_input(CML.SingleInputBuilder.new(
+    CML.TransactionInput.new(
+        CML.TransactionHash.from_hex("8561258e210352fba2ac0488afed67b3427a27ccf1d41ec030c98a8199bc22ec"), // tx hash
         0, // index
     ),
-    CardanoWasm.Value.new(CardanoWasm.BigNum.from_str('3000000'))
-);
-
-// add a bootstrap input - for ADA held in a Byron-era address
-const byronAddress = CardanoWasm.ByronAddress.from_base58("Ae2tdPwUPEZLs4HtbuNey7tK4hTKrwNwYtGqp7bDfCy2WdR3P6735W5Yfpe");
-txBuilder.add_bootstrap_input(
-    byronAddress,
-    CardanoWasm.TransactionInput.new(
-    CardanoWasm.TransactionHash.from_bytes(
-        Buffer.from("488afed67b342d41ec08561258e210352fba2ac030c98a8199bc22ec7a27ccf1", "hex"),
-    ), // tx hash
-    0, // index
-    ),
-    CardanoWasm.Value.new(CardanoWasm.BigNum.from_str('3000000'))
+    CML.TransactionOutput.new(
+        inputAddr,
+        CML.Value.from_coin(BigInt(6000000)),
+    )
 );
 
 // base address
-const shelleyOutputAddress = CardanoWasm.Address.from_bech32("addr_test1qpu5vlrf4xkxv2qpwngf6cjhtw542ayty80v8dyr49rf5ewvxwdrt70qlcpeeagscasafhffqsxy36t90ldv06wqrk2qum8x5w");
+const outputAddress = CML.Address.from_bech32("addr_test1qpu5vlrf4xkxv2qpwngf6cjhtw542ayty80v8dyr49rf5ewvxwdrt70qlcpeeagscasafhffqsxy36t90ldv06wqrk2qum8x5w");
 // pointer address
-const shelleyChangeAddress = CardanoWasm.Address.from_bech32("addr_test1gz2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzerspqgpsqe70et");
+const changeAddress = CML.Address.from_bech32("addr_test1gz2fxv2umyhttkxyxp8x0dlpdt3k6cwng5pxj3jhsydzerspqgpsqe70et");
 
 // add output to the tx
 txBuilder.add_output(
-    CardanoWasm.TransactionOutput.new(
-    shelleyOutputAddress,
-    CardanoWasm.Value.new(CardanoWasm.BigNum.from_str('1000000'))    
-    ),
+    CML.TransactionOutputBuilder()
+        .with_address(outputAddress)
+        .next()
+        .with_value(CML.Value.from_coin(BigInt(1000000)))
+        .build()
 );
 
-// set the time to live - the absolute slot value before the tx becomes invalid
-txBuilder.set_ttl(410021);
-
 // calculate the min fee required and send any change to an address
-txBuilder.add_change_if_needed(shelleyChangeAddress);
-
-// once the transaction is ready, we build it to get the tx body without witnesses
-const txBody = txBuilder.build();
-const txHash = CardanoWasm.hash_transaction(txBody);
-const witnesses = CardanoWasm.TransactionWitnessSet.new();
-
-// add keyhash witnesses
-const vkeyWitnesses = CardanoWasm.Vkeywitnesses.new();
-const vkeyWitness = CardanoWasm.make_vkey_witness(txHash, prvKey);
-vkeyWitnesses.add(vkeyWitness);
-witnesses.set_vkeys(vkeyWitnesses);
-
-// add bootstrap (Byron-era) witnesses
-const cip1852Account = CardanoWasm.Bip32PrivateKey.from_bech32('xprv1hretan5mml3tq2p0twkhq4tz4jvka7m2l94kfr6yghkyfar6m9wppc7h9unw6p65y23kakzct3695rs32z7vaw3r2lg9scmfj8ec5du3ufydu5yuquxcz24jlkjhsc9vsa4ufzge9s00fn398svhacse5su2awrw');
-const bootstrapWitnesses = CardanoWasm.BootstrapWitnesses.new();
-const bootstrapWitness = CardanoWasm.make_icarus_bootstrap_witness(
-    txHash,
-    byronAddress,
-    cip1852Account,
+// this moves onto the next step of building the transaction: providing witnesses
+const signedTxBuilder = tx_builder.build(
+    changeAddress,
+    CML.ChangeSelectionAlgo.Default
 );
-bootstrapWitnesses.add(bootstrapWitness);
-witnesses.set_bootstraps(bootstrapWitnesses);
 
-// create the finalized transaction with witnesses
-const transaction = CardanoWasm.Transaction.new(
-    txBody,
-    witnesses,
-    undefined, // transaction metadata
-);
+// sign with the key that owns the input used
+signedTxBuilder.add_vkey(CML.make_vkey_witness(txHash, prvKey));
+
+const tx = signedTxBuilder.build_checked();
+// ready to submit, can be converted to CBOR via tx.to_cbor_bytes() or to_cbor_hex() for hex
 ```
 
 ## A note on fees
 
-Fees is Cardano Shelley are based directly on the size of the final encoded transaction. It is important to note that a transaction created by this library potentially can vary in size compared to one built with other tools. This is because transactions, as well as other Cardano Shelley structures, are encoded using [CBOR](https://cbor.io/) a binary JSON-like encoding. Due to arrays and maps allowing both definite or indefinite length encoding in the encoded transaction created by the library, the size can vary. This is because definite encoding consists of a tag containing the size of the array/map which can be 1 or more bytes long depending on the number of elements the size of the encoded structure, while indefinite length encoding consists of a 1 byte starting tag and after all elements are listed, a 1 byte ending tag. These variances should should only be a couple bytes and cardano-multiplatform-lib uses definite encoding which is the same length or smaller for any reasonable sized transaction.
+Fees in Cardano are based directly on the size of the final encoded transaction. It is important to note that a transaction created by this library potentially can vary in size compared to one built with other tools. This is because transactions, as well as other Cardano structures, are encoded using [CBOR](https://cbor.io/) a binary JSON-like encoding. Due to arrays and maps allowing both definite or indefinite length encoding in the encoded transaction created by the library, the size can vary. This is because definite encoding consists of a tag containing the size of the array/map which can be 1 or more bytes long depending on the number of elements the size of the encoded structure, while indefinite length encoding consists of a 1 byte starting tag and after all elements are listed, a 1 byte ending tag. These variances should should only be a couple bytes and cardano-multiplatform-lib uses definite encoding by default which is the same length or smaller for any reasonable sized transaction.