Add docs

vacuumlabs · Nov 25, 2020 · efd815b · efd815b
1 parent d5fce00
commit efd815b
Show file tree

Hide file tree

Showing 4 changed files with 381 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -1,5 +1,88 @@
-# cardano-hw-cli
-Cardano CLI tool for hardware wallets
+# Cardano HW cli tool
+Cardano HW CLI tool for signing transaction
 
-# Docs
-https://github.com/vacuumlabs/cardano-hw-cli/tree/docs/docs
+# Installation
+Check:
+- releases https://github.com/vacuumlabs/cardano-hw-cli/releases
+- installation instructions https://github.com/vacuumlabs/cardano-hw-cli/blob/develop/docs/installation.md
+
+# Usage
+For running commands with ledger, you might need to use `sudo`
+
+## Generate public verification key and hardware wallet signing file
+```
+cardano-hw-cli shelley address key-gen
+--path PATH                     Derivation path to the key we want to sign with.
+--verification-key-file FILE    Output filepath of the verification key.
+--hw-signing-file FILE          Output filepath of the hardware wallet signing file.
+```
+
+## Generate public verification key
+```
+cardano-hw-cli shelley key verification-key
+--hw-signing-file FILE          Input filepath of the hardware wallet signing file.
+--verification-key-file FILE    Output filepath of the verification key.
+```
+
+## Sign transaction
+```
+cardano-hw-cli shelley transaction sign
+--tx-body-file FILE                    Input filepath of the TxBody.
+--hw-signing-file FILE                 Input filepath of the hardware wallet signing file (one or more).
+--change-output-key-file FILE          Input filepath of the hardware wallet signing file.
+--mainnet | --testnet-magic NATURAL    Use the mainnet magic id or specify testnet magic id.
+--out-file FILE                        Output filepath of the Tx.
+```
+
+## Witness transaction
+```
+cardano-hw-cli shelley transaction sign
+--tx-body-file FILE                    Input filepath of the TxBody.
+--hw-signing-file FILE                 Input filepath of the hardware wallet signing file.
+--change-output-key-file File          Input filepath of the hardware wallet signing file.
+--mainnet | --testnet-magic NATURAL    Use the mainnet magic id or specify testnet magic id.
+--out-file FILE                        Output filepath of the Tx.
+```
+
+# Show address on device
+```
+cardano-hw-cli shelley address show 
+  --payment-path PAYMENTPATH    Payment derivation path.
+  --staking-path STAKINGPATH    Stake derivation path.
+  --address-file ADDRESS        Input filepath of the address.
+```
+
+## Check device version
+```
+cardano-hw-cli device version
+```
+
+## Examples
+- https://github.com/vacuumlabs/cardano-hw-cli/blob/develop/docs/delegation-example.md
+- https://github.com/vacuumlabs/cardano-hw-cli/blob/develop/docs/transaction-example.md
+
+# Compiling from source
+Install node version v12.16.2
+```
+nvm i v12.16.2
+```
+
+Install yarn:
+```
+npm install -g yarn
+```
+
+Install dependencies:
+```
+yarn install
+```
+
+Run unit test
+```
+yarn test-unit
+```
+
+Run application with
+```
+yarn dev ...
+```
diff --git a/docs/delegation-example.md b/docs/delegation-example.md
@@ -0,0 +1,131 @@
+# Delegation example
+
+## Prepare HW wallet
+Connect your HW wallet to your computer.
+
+## Get protocol parameters
+```
+cardano-cli shelley query protocol-parameters \
+--mainnet \
+--out-file protocol.json
+```
+should create `protocol.json` file.
+
+### Verification payment key and hardware wallet signing file
+```
+cardano-hw-cli shelley address key-gen \
+--path 1852H/1815H/0H/0/0 \
+--verification-key-file payment.vkey \
+--hw-signing-file payment.hwsfile
+```
+should create `payment.vkey` and `payment.hwsfile` files.
+
+## Verification stake key and hardware wallet signing file
+```
+cardano-hw-cli shelley address key-gen \
+--path 1852H/1815H/0H/2/0 \
+--verification-key-file stake.vkey \
+--hw-signing-file stake.hwsfile
+```
+should create `stake.vkey` and `stake.hwsfile` files.
+
+## Payment address
+```
+cardano-cli shelley address build \
+--payment-verification-key-file payment.vkey \
+--stake-verification-key-file stake.vkey \
+--out-file payment.addr \
+--mainnet
+```
+should create `payment.addr` file.
+
+## Create delegation certificate
+```
+cardano-cli shelley stake-address delegation-certificate \
+--staking-verification-key-file stake.vkey \
+--stake-pool-verification-key-file cold.vkey \
+--out-file delegation.cert
+```
+should create `delegation.cert` file.
+
+## Get the transaction hash and index of the UTXO to spend
+```
+cardano-cli shelley query utxo \
+--address $(cat payment.addr) \
+--mainnet
+```
+example return:
+```
+                           TxHash                                 TxIx        Lovelace
+----------------------------------------------------------------------------------------
+2a602e9ad218967602b4ca7be48648224e07f34fb0059f164ea3f99dbbfee1cb     0           1983692
+```
+
+## Draft the transaction
+```
+cardano-cli shelley transaction build-raw \
+--tx-in 2a602e9ad218967602b4ca7be48648224e07f34fb0059f164ea3f99dbbfee1cb#0 \
+--tx-out $(cat payment.addr)+0 \
+--ttl 0 \
+--fee 0 \
+--certificate-file delegation.cert \
+--out-file tx.draft
+```
+should create `tx.draft` file.
+
+## Calculate the fee
+```
+cardano-cli shelley transaction calculate-min-fee \
+--tx-body-file tx.draft \
+--tx-in-count 1 \
+--tx-out-count 1 \
+--witness-count 2 \
+--byron-witness-count 0 \
+--mainnet \
+--protocol-params-file protocol.json
+```
+example return:
+```
+199845 Lovelace
+```
+
+## Determine the TTL for the transaction
+```
+cardano-cli shelley query tip --mainnet
+```
+
+## Build the transaction
+```
+cardano-cli shelley transaction build-raw \
+--tx-in 2a602e9ad218967602b4ca7be48648224e07f34fb0059f164ea3f99dbbfee1cb#0 \
+--tx-out $(cat payment.addr)+1783847 \
+--ttl 13909233 \
+--fee 199845 \
+--certificate-file delegation.cert \
+--out-file tx.raw
+```
+
+## Sign the transaction
+```
+cardano-hw-cli shelley transaction sign \
+--tx-body-file tx.raw \
+--hw-signing-file payment.hwsfile \
+--hw-signing-file stake.hwsfile \
+--mainnet \
+--out-file tx.signed
+```
+should return `tx.signed` file.
+
+## Submit the transaction
+```
+cardano-cli shelley transaction submit \
+--tx-file tx.signed \
+--mainnet
+```
+
+## Check the balances
+```
+cardano-cli shelley query utxo \
+--address $(cat payment.addr) \
+--mainnet
+```
diff --git a/docs/installation.md b/docs/installation.md
@@ -0,0 +1,32 @@
+# Linux
+
+## Option 1: install from `.deb` package:
+To install from `.deb` package, open file from file explorer of your choice or run in command line:
+```
+sudo dpkg --install ./cardano-hw-cli_<VERSION>.deb
+```
+This will create necessary files under `/user/share/cardano-hw-cli/` and create soft link under `/usr/bin/`, so `cardano-hw-cli` command is callable in command line from everywhere.
+
+If you wish to uninstall `cardano-hw-cli`, run:
+```
+sudo dpkg --remove cardano-hw-cli
+```
+
+## Option 2: uncompress `.tar.gz` archive:
+if `.deb` package is not working for some reason you can uncompress the `.tar.gz` archive and create soft link to `cardano-hw-cli` manually:
+
+Uncompress:
+```
+tar -zxvf cardano-hw-cli.tar.gz
+```
+
+Create soft link:
+```
+sudo ln -s /<PATH_TO_UNCOMPRESSED_DIRECTORY>/cardano-hw-cli /usr/bin
+```
+
+
+# Windows
+Unzip `cardano-hw-cli.zip` and add directory location to your PATH.
+
+How to add to PATH: https://www.architectryan.com/2018/03/17/add-to-the-path-on-windows-10/
diff --git a/docs/transaction-example.md b/docs/transaction-example.md
@@ -0,0 +1,131 @@
+# Transaction example
+This example is modified example found in cardano docs, to work with HW wallets:
+- https://docs.cardano.org/projects/cardano-node/en/latest/stake-pool-operations/keys_and_addresses.html
+- https://docs.cardano.org/projects/cardano-node/en/latest/stake-pool-operations/simple_transaction.html
+
+## Prepare HW wallet
+Connect your HW wallet to your computer.
+
+## Get protocol parameters
+```
+cardano-cli shelley query protocol-parameters \
+--mainnet \
+--out-file protocol.json
+```
+should create `protocol.json` file.
+
+### Verification payment key and hardware wallet signing file
+```
+cardano-hw-cli shelley address key-gen \
+--path 1852H/1815H/0H/0/0 \
+--verification-key-file payment.vkey \
+--hw-signing-file payment.hwsfile
+```
+should create `payment.vkey` and `payment.hwsfile` files.
+
+## Verification stake key and hardware wallet signing file
+```
+cardano-hw-cli shelley address key-gen \
+--path 1852H/1815H/0H/2/0 \
+--verification-key-file stake.vkey \
+--hw-signing-file stake.hwsfile
+```
+should create `stake.vkey` and `stake.hwsfile` files.
+
+## Payment address
+```
+cardano-cli shelley address build \
+--payment-verification-key-file payment.vkey \
+--stake-verification-key-file stake.vkey \
+--out-file payment.addr \
+--mainnet
+```
+should create `payment.addr` file.
+
+## Get the transaction hash and index of the UTXO to spend
+```
+cardano-cli shelley query utxo \
+--address $(cat payment.addr) \
+--mainnet
+```
+example return:
+```
+                           TxHash                                 TxIx        Lovelace
+----------------------------------------------------------------------------------------
+bc8bf52ea894fb8e442fe3eea628be87d0c9a37baef185b70eb00a5c8a849d3b     0           2487217
+```
+
+## Draft the transaction
+```
+cardano-cli shelley transaction build-raw \
+--tx-in bc8bf52ea894fb8e442fe3eea628be87d0c9a37baef185b70eb00a5c8a849d3b#0 \
+--tx-out $(cat payment.addr)+0 \
+--ttl 0 \
+--fee 0 \
+--out-file tx.draft
+```
+should create `tx.draft` file.
+
+## Calculate the fee
+```
+cardano-cli shelley transaction calculate-min-fee \
+--tx-body-file tx.draft \
+--tx-in-count 1 \
+--tx-out-count 1 \
+--witness-count 1 \
+--byron-witness-count 0 \
+--mainnet \
+--protocol-params-file protocol.json
+```
+example return:
+```
+170869 Lovelace
+```
+
+## Determine the TTL for the transaction
+```
+cardano-cli shelley query tip --mainnet
+```
+example return:
+```
+{
+  "blockNo": 4818137,
+  "headerHash": "b567ac1a111822d006c61ba955a24167215b1207cab15aed53d68d51244da904",
+  "slotNo": 11122006
+}
+```
+
+## Build the transaction
+TTL: Add 1000 to `slotNo` from previous call
+```
+cardano-cli shelley transaction build-raw \
+--tx-in bc8bf52ea894fb8e442fe3eea628be87d0c9a37baef185b70eb00a5c8a849d3b#0 \
+--tx-out $(cat payment.addr)+2316348 \
+--ttl 11123006 \
+--fee 170869 \
+--out-file tx.raw
+```
+
+## Sign the transaction
+```
+cardano-hw-cli shelley transaction sign \
+--tx-body-file tx.raw \
+--hw-signing-file payment.hwsfile \
+--mainnet \
+--out-file tx.signed
+```
+should return `tx.signed` file.
+
+## Submit the transaction
+```
+cardano-cli shelley transaction submit \
+--tx-file tx.signed \
+--mainnet
+```
+
+## Check the balances
+```
+cardano-cli shelley query utxo \
+--address $(cat payment.addr) \
+--mainnet
+```