Docusaurus v2 Beta 17 Upgrade

.gitignore

@@ -39,7 +39,9 @@ yarn-error.log*
 .idea
 
 # Auto generated content like CIPs, Rust Library and Token Registry
-/docs/governance/cardano-improvement-proposals/*
-/static/img/cip/*
-/docs/native-tokens/token-registry/*
-/docs/get-started/cardano-serialization-lib/*
+#/docs/governance/cardano-improvement-proposals/*
+#/static/img/cip/*
+#/docs/native-tokens/token-registry/*
+#/docs/get-started/cardano-serialization-lib/*
+# Generated files will now need to be included in the repo to avoid docusaurus build errors
+# CI / CD should not rebuild the docs at deploy time

.nvmrc

@@ -0,0 +1 @@
+v16.14.0

docs/careers.md

@@ -3,7 +3,7 @@ id: careers
 title: Careers on Cardano
 sidebar_label: Careers on Cardano
 description: Are you passionate about Cardano and looking for a job working in the Cardano ecosystem?
-image: ./img/og-developer-portal.png
+image: ../img/og-developer-portal.png
 hide_table_of_contents: false
 ---
 

docs/get-started/blockfrost.md

@@ -3,7 +3,7 @@ id: blockfrost
 title: Get Started with Blockfrost
 sidebar_label: Blockfrost
 description: Get Started with Blockfrost
-image: ./img/og-developer-portal.png
+image: ../img/og-developer-portal.png
 ---
 
 Blockfrost provides API to access and process information stored on the Cardano blockchain. The basic tier is free and allows 50,000 requests per day.

docs/get-started/cardano-components.md

@@ -3,7 +3,7 @@ id: cardano-components
 title: Cardano Components
 sidebar_label: Overview
 description: This article explains all the different Cardano components and their functions.
-image: ./img/og-developer-portal.png
+image: ../img/og-developer-portal.png
 --- 
 
 - [`cardano-node`](https://github.com/input-output-hk/cardano-node#cardano-node-overview) is the core component that is used to participate in a Cardano decentralised blockchain. 

docs/get-started/cardano-developer-community.md

@@ -3,7 +3,7 @@ id: cardano-developer-community
 title: Get Started in the Cardano Developer Community
 sidebar_label: Developer Community
 description: Get Started in the Cardano Developer Community.
-image: ./img/og-developer-portal.png
+image: ../img/og-developer-portal.png
 --- 
 
 Apart from the two leading platforms [Stack Exchange](https://cardano.stackexchange.com) and [Cardano Forum](https://forum.cardano.org/c/developers/29), Cardano developers and stake pool operators spread across different platforms. Each with its niche.

docs/get-started/cardano-serialization-lib/generating-keys.md

@@ -0,0 +1,123 @@
+--- 
+sidebar_label: Generating Keys
+title: generating-keys
+sidebar_position: 3
+--- 
+# Generating Keys and Addresses
+
+## BIP32 Keys
+
+There are two main categories of keys in this library. There are the raw `PublicKey` and `PrivateKey` which are used for cryptographically signing/verifying, and `BIP32PrivateKey`/`BIP32PublicKey` which in addition to this have the ability to derive additional keys from them following the [BIP32 derivation scheme](https://en.bitcoin.it/wiki/BIP_0032) variant called BIP32-Ed25519, which will be referred to as BIP32 for brevity. We use the [BIP44 spec](https://en.bitcoin.it/wiki/BIP_0044) variant for Ed25519 as well for the derivation paths using 1852 or 44 as the purpose consant and 1815 for the coin type depending on address type. See [this doc](https://github.com/input-output-hk/implementation-decisions/pull/18) for more details.
+
+This is demonstrated with the below code
+```javascript
+function harden(num: number): number {
+  return 0x80000000 + num;
+}
+
+
+const rootKey = CardanoWasm.BIP32PrivateKey.from_bech32("xprv17qx9vxm6060qjn5fgazfue9nwyf448w7upk60c3epln82vumg9r9kxzsud9uv5rfscxp382j2aku254zj3qfx9fx39t6hjwtmwq85uunsd8x0st3j66lzf5yn30hwq5n75zeuplepx8vxc502txx09ygjgx06n0p");
+const accountKey = rootKey
+  .derive(harden(1852)) // purpose
+  .derive(harden(1815)) // coin type
+  .derive(harden(0)); // account #0
+
+const utxoPubKey = accountKey
+  .derive(0) // external
+  .derive(0)
+  .to_public();
+
+const stakeKey = accountKey
+  .derive(2) // chimeric
+  .derive(0)
+  .to_public();
+```
+
+## BIP39 Entropy
+
+To generate a `BIP32PrivateKey` from a BIP39 recovery phrase it must be first converted to entropy following the [BIP39 protocol]. This library does not directly handle that, but once entropy is created it is possible to use `Bip32PrivateKey.from_bip39_entropy(entropy, password)`. For more information see the [CIP3](https://github.com/cardano-foundation/CIPs/pull/3) Cardano improvement proposal. The code below uses the `bip39` npm package to generate a root `BIP32PrivateKey` from a BIP39 mnemonic.
+
+```javascript
+import { mnemonicToEntropy } from 'bip39';
+
+const entropy = mnemonicToEntropy(
+  [ "test", "walk", "nut", "penalty", "hip", "pave", "soap", "entry", "language", "right", "filter", "choice" ].join(' ')
+);
+
+const rootKey = CardanoWasm.Bip32PrivateKey.from_bip39_entropy(
+  Buffer.from(entropy, 'hex'),
+  Buffer.from(''),
+);
+```
+
+## Use in Addresses
+
+Once we have reached the desired derivation path, we must convert the `BIP32PrivateKey` or `BIP32PublicKey` to a `PrivateKey` or `PublicKey` by calling `.to_raw_key()` on them with the exception of Byron addresses.
+For example, to create an address using the `utxoPubKey` and `stakeKey` in the first example, we can do:
+```javascript
+// base address with staking key
+const baseAddr = CardanoWasm.BaseAddress.new(
+  CardanoWasm.NetworkInfo.mainnet().network_id(),
+  CardanoWasm.StakeCredential.from_keyhash(utxoPubKey.to_raw_key().hash()),
+  CardanoWasm.StakeCredential.from_keyhash(stakeKey.to_raw_key().hash()),
+);
+
+// enterprise address without staking ability, for use by exchanges/etc
+const enterpriseAddr = CardanoWasm.EnterpriseAddress.new(
+  CardanoWasm.NetworkInfo.mainnet().network_id(),
+  CardanoWasm.StakeCredential.from_keyhash(utxoPubKey.to_raw_key().hash())
+);
+
+// pointer address - similar to Base address but can be shorter, see formal spec for explanation
+const ptrAddr = CardanoWasm.PointerAddress.new(
+  CardanoWasm.NetworkInfo.mainnet().network_id(),
+  CardanoWasm.StakeCredential.from_keyhash(utxoPubKey.to_raw_key().hash()),
+  CardanoWasm.Pointer.new(
+    100, // slot
+    2,   // tx index in slot
+    0    // cert indiex in tx
+  )
+);
+
+// reward address - used for withdrawing accumulated staking rewards
+const rewardAddr = CardanoWasm.RewardAddress.new(
+  CardanoWasm.NetworkInfo.mainnet().network_id(),
+  CardanoWasm.StakeCredential.from_keyhash(stakeKey.to_raw_key().hash())
+);
+
+// bootstrap address - byron-era addresses with no staking rights
+const byronAddr = CardanoWasm.ByronAddress.icarus_from_key(
+  utxoPubKey, // Ae2* style icarus address
+  CardanoWasm.NetworkInfo.mainnet().protocol_magic()
+);
+```
+
+Note that the byron-era address can only be created in this library from icarus-style addresses that start in `Ae2` and that Daedalus-style addresses starting in `Dd` are not directly supported.
+
+These are all address variant types with information specific to its address type. There is also an `Address` type which represents any of those variants, which is the type use in most parts of the library. For example to create a `TransactionOutput` manually we would have to first convert from one of the address variants by doing:
+```javascript
+const address = baseAddress.to_address();
+
+const output = CardanoWasm.TransactionOutput(address, BigNum.from_str("365"));
+```
+If the address is already a Shelley address in raw bytes or a bech32 string we can create it directly via:
+```javascript
+const addr = CardanoWasm.Address.from_bech32("addr1vyt3w9chzut3w9chzut3w9chzut3w9chzut3w9chzut3w9cj43ltf");
+
+```
+
+
+## Other Key Types
+
+Conversion between `cardano-cli` 128-byte `XPrv` keys and `BIP32PrivateKey` is also supported:
+```javascript
+const bip32PrivateKey = CardanoWasm.BIP32PrivateKey.from_128_xprv(xprvBytes);
+assert(xprvBytes == CardanoWasm.BIP32PrivateKey.to_128_xprv());
+```
+96-byte `XPrv` keys are identical to `BIP32PrivateKey`s byte-wise and no conversion is needed.
+For more details see [this document](https://docs.cardano.org/projects/cardano-node/en/latest/stake-pool-operations/keys_and_addresses.html) regarding legacy keys.
+
+There is also `LegacyDaedalusPrivateKey` which is used for creating witnesses for legacy Daedalus `Dd`-type addresses.
+
+## Serialization-Lib Information  
+This page was generated automatically from: [https://github.com/Emurgo/cardano-serialization-lib](https://github.com/Emurgo/cardano-serialization-lib/tree/master/doc/getting-started/generating-keys.md).

docs/get-started/cardano-serialization-lib/generating-transactions.md

@@ -0,0 +1,120 @@
+--- 
+sidebar_label: Generating Transactions
+title: generating-transactions
+sidebar_position: 4
+--- 
+# Generating Transactions
+
+## TransactionBuilder API
+
+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
+
+The example below builds a transaction with all 2 of the 3 input types: key and bootstrap.
+Multisig (script) inputs are essentially identical to key inputs, but using the scripthash instead of the keyhash, however they are not supported for implicit fee calculation yet.
+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 txBuilder = CardanoWasm.TransactionBuilder.new(
+    // all of these are taken from the mainnet genesis settings
+    // linear fee parameters (a*size + b)
+    CardanoWasm.LinearFee.new(CardanoWasm.BigNum.from_str('44'), CardanoWasm.BigNum.from_str('155381')),
+    // minimum utxo value
+    CardanoWasm.BigNum.from_str('1000000'),
+    // pool deposit
+    CardanoWasm.BigNum.from_str('500000000'),
+    // key deposit
+    CardanoWasm.BigNum.from_str('2000000')
+);
+
+// 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
+        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'))
+);
+
+// base address
+const shelleyOutputAddress = CardanoWasm.Address.from_bech32("addr_test1qpu5vlrf4xkxv2qpwngf6cjhtw542ayty80v8dyr49rf5ewvxwdrt70qlcpeeagscasafhffqsxy36t90ldv06wqrk2qum8x5w");
+// pointer address
+const shelleyChangeAddress = CardanoWasm.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'))    
+    ),
+);
+
+// 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 bootstrapWitnesses = CardanoWasm.BootstrapWitnesses.new();
+const bootstrapWitness = CardanoWasm.make_icarus_bootstrap_witness(txHash,byronAddress,getCip1852Account());
+bootstrapWitnesses.add(bootstrapWitness);
+witnesses.set_bootstraps(bootstrapWitnesses);
+
+// create the finalized transaction with witnesses
+const transaction = CardanoWasm.Transaction.new(
+    txBody,
+    witnesses,
+    undefined, // transaction metadata
+);
+```
+
+## 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-serialization-lib uses definite encoding which is the same length or smaller for any reasonable sized transaction.
+
+## Serialization-Lib Information  
+This page was generated automatically from: [https://github.com/Emurgo/cardano-serialization-lib](https://github.com/Emurgo/cardano-serialization-lib/tree/master/doc/getting-started/generating-transactions.md).

docs/get-started/cardano-serialization-lib/overview.md

@@ -4,7 +4,7 @@ sidebar_position: 1
 title: Get Started with Cardano Serialization Lib
 sidebar_label: Overview
 description: Get Started with Cardano Serialization Lib
-image: ./img/og-developer-portal.png
+image: ../img/og-developer-portal.png
 --- 
 
 This is a library for serialization & deserialization of data structures

docs/get-started/cardano-serialization-lib/prerequisite-knowledge.md

@@ -0,0 +1,13 @@
+--- 
+sidebar_label: Prerequisite Knowledge
+title: prerequisite-knowledge
+sidebar_position: 2
+--- 
+# Pre-requisite knowledge
+
+This library assumes a certain amount of knowledge about how Cardano works (want to avoid re-documenting the wheel).
+
+You can find the specifications of Cardano's ledger [here](https://github.com/input-output-hk/cardano-ledger-specs) which we suggest consulting as you use this library. Notably, the `Shelley ledger formal specification` covers the core concepts.
+
+## Serialization-Lib Information  
+This page was generated automatically from: [https://github.com/Emurgo/cardano-serialization-lib](https://github.com/Emurgo/cardano-serialization-lib/tree/master/doc/getting-started/prerequisite-knowledge.md).