From da9a2ccf3670013697cf4ffcfac3f3bc8c3ba8ce Mon Sep 17 00:00:00 2001 From: Piotr Stachyra Date: Tue, 18 Oct 2022 10:07:19 +0200 Subject: [PATCH 1/3] User guides updates --- docs/user-guide/common-use-cases/assets.md | 19 ++++++---- .../user-guide/common-use-cases/delegation.md | 7 ++-- .../how-to-make-a-transaction.md | 2 +- .../how-to-start-wallet-server.md | 36 +++++++++++++------ 4 files changed, 43 insertions(+), 21 deletions(-) diff --git a/docs/user-guide/common-use-cases/assets.md b/docs/user-guide/common-use-cases/assets.md index d45df1ffcfd..0fdf2d73681 100644 --- a/docs/user-guide/common-use-cases/assets.md +++ b/docs/user-guide/common-use-cases/assets.md @@ -7,7 +7,7 @@ title: Managing native assets - [[how-to-start-wallet-server]] - [[how-to-create-a-wallet]] - - In order to be able to send transactions we need funds on the wallet. In case of [Testnet](https://testnets.cardano.org/en/testnets/cardano/overview/) we can request tADA from the [faucet](https://testnets.cardano.org/en/testnets/cardano/tools/faucet/). + - In order to be able to send transactions we need funds on the wallet. In case of `preview` and `preprod` [testnets](https://testnets.cardano.org/en/testnets/cardano/overview/) we can request tADA from the [faucet](https://testnets.cardano.org/en/testnets/cardano/tools/faucet/). ## Overview @@ -62,18 +62,23 @@ You can also list assets that were ever associated with the wallet. ## Assets off-chain metadata -Issuers of native assets may put some metadata about them in the off-chain metadata server, like **Cardano Token Registry**. +Issuers of native assets may put some off-chain metadata about them in the **Cardano Token Registry**. There are separate instances of token registry for `mainnet` and testnets (e.g. `preview` or `preprod`). Users can submit metadata to the repository which will be then served via corresponding server. + +| | Mainnet | Testnets | +|--|--|--| +| **Repository** | https://github.com/cardano-foundation/cardano-token-registry | https://github.com/input-output-hk/metadata-registry-testnet | +| **Server** | https://tokens.cardano.org | https://metadata.cardano-testnet.iohkdev.io | > :information_source: Read more: [Cardano Token Registry](https://developers.cardano.org/docs/native-tokens/token-registry/cardano-token-registry), [CIP26](https://cips.cardano.org/cips/cip26). -Cardano-wallet is capable of reading that metadata and serving it along while listing assets. All you have to do is to start wallet with `--token-metadata-server` parameter pointing to an off-chain metadata server. +Cardano-wallet is capable of reading that metadata and serving it along while listing assets. All you have to do is to start wallet with `--token-metadata-server` parameter pointing to an off-chain metadata server corresponding to your network. -For example on testnet that would be: +For example on `preview` or `preprod` that would be: ```bash $ cardano-wallet serve --port 8090 \ --node-socket /path/to/node.socket \ - --testnet testnet-byron-genesis.json \ + --testnet byron-genesis.json \ --database ./wallet-db \ --token-metadata-server https://metadata.cardano-testnet.iohkdev.io/ ``` @@ -142,7 +147,7 @@ $ curl -X POST http://localhost:8091/v2/wallets/73d38c71e4b8b5d71769622ab4f5bfde "policy_vk12d0gdel9u6px8wf3uv4z6m4h447n9qsad24gztaku8dzzdqfajzqfm3rr0" ``` -Once we sort it out we are all set and we can proceed into minting an NFT from our wallet! +Once we sort it out we are all set and we can proceed into minting NFT from our wallet! #### CIP-25 metadata @@ -271,7 +276,7 @@ $ curl -X POST http://localhost:8090/v2/wallets/73d38c71e4b8b5d71769622ab4f5bfde ``` That's it! I should now receive CBOR-encoded `transaction`, `fee` and `coin_selection` details in response. I can now **sign** and **submit** such a transaction just like in [[how-to-make-a-transaction]]. -Once submitted my freshly minted NFT should be added to my wallet balance! +Once transaction submitted your freshly minted NFT should be added to the wallet balance! ### Burning an NFT diff --git a/docs/user-guide/common-use-cases/delegation.md b/docs/user-guide/common-use-cases/delegation.md index 0cf2535c7ee..f4072fe67d4 100644 --- a/docs/user-guide/common-use-cases/delegation.md +++ b/docs/user-guide/common-use-cases/delegation.md @@ -7,7 +7,7 @@ title: Delegation - [[how-to-start-wallet-server]] - [[how-to-create-a-wallet]] - - In order to be able to send transactions we need funds on the wallet. In case of [Testnet](https://testnets.cardano.org/en/testnets/cardano/overview/) we can request tADA from the [faucet](https://testnets.cardano.org/en/testnets/cardano/tools/faucet/). + - In order to be able to send transactions we need funds on the wallet. In case of `preview` and `preprod` [testnets](https://testnets.cardano.org/en/testnets/cardano/overview/) we can request tADA from the [faucet](https://testnets.cardano.org/en/testnets/cardano/tools/faucet/). ## Overview @@ -135,6 +135,7 @@ $ curl -X POST http://localhost:8090/v2/wallets/1b0aa24994b4181e79116c131510f2ab -H "Content-Type: application/json" ``` -> :information_source: Note that all rewards will be withdrawn only if you add {"withdrawal":"self"} to the payload. You can do it in a single transaction though as above. +After constructing delegation quit transaction I should receive CBOR-encoded `transaction`, `fee` and `coin_selection` details in response. +I can now **sign** and **submit** such a transaction just like in [[how-to-make-a-transaction]]. -> :information_source: Refer to [[how-to-make-a-transaction]] for details on signing and submitting it to the network. +> :information_source: Note that all rewards will be withdrawn only if you add {"withdrawal":"self"} to the payload. You can do it in a single transaction though as above. diff --git a/docs/user-guide/common-use-cases/how-to-make-a-transaction.md b/docs/user-guide/common-use-cases/how-to-make-a-transaction.md index 1f247387e15..7b206e97309 100644 --- a/docs/user-guide/common-use-cases/how-to-make-a-transaction.md +++ b/docs/user-guide/common-use-cases/how-to-make-a-transaction.md @@ -7,7 +7,7 @@ title: How to make a transaction - [[how-to-start-wallet-server]] - [[how-to-create-a-wallet]] - - In order to be able to send transactions we need funds on the wallet. In case of [Testnet](https://testnets.cardano.org/en/testnets/cardano/overview/) we can request tADA from the [faucet](https://testnets.cardano.org/en/testnets/cardano/tools/faucet/). + - In order to be able to send transactions we need funds on the wallet. In case of `preview` and `preprod` [testnets](https://testnets.cardano.org/en/testnets/cardano/overview/) we can request tADA from the [faucet](https://testnets.cardano.org/en/testnets/cardano/tools/faucet/). ## Old transaction workflow diff --git a/docs/user-guide/common-use-cases/how-to-start-wallet-server.md b/docs/user-guide/common-use-cases/how-to-start-wallet-server.md index 7efdcec9e6a..5517f1f29cf 100644 --- a/docs/user-guide/common-use-cases/how-to-start-wallet-server.md +++ b/docs/user-guide/common-use-cases/how-to-start-wallet-server.md @@ -10,33 +10,49 @@ The easiest and most common way of managing your funds on the Cardano blockchain Here we are going to start `cardano-wallet` in full node mode, meaning that we need to have also `cardano-node` running on the same machine. We can get binaries of `cardano-wallet` and compatible version of `cardano-node` from [cardano wallet release page](https://github.com/input-output-hk/cardano-wallet/releases). `Cardano-wallet` archives published for each release, besides `cardano-wallet` itself, include all the relevant tools like `cardano-node`, `cardano-cli`, `cardano-addresses` or `bech32`. -> :information_source: Alternatively one can use handy [docker-compose](https://github.com/input-output-hk/cardano-wallet#getting-started) to start wallet and the node. -> `$ NETWORK=testnet docker-compose up` +> :information_source: Alternatively one can use handy [docker-compose](https://github.com/input-output-hk/cardano-wallet#getting-started) to start wallet and the node on different networks: +> `$ NETWORK=mainnet docker-compose up` +> `$ NETWORK=preprod docker-compose up` +> `$ NETWORK=preview docker-compose up` #### Pre-requisites - Install cardano-wallet from [cardano wallet release page](https://github.com/input-output-hk/cardano-wallet/releases). - Install cardano-node from [cardano wallet release page](https://github.com/input-output-hk/cardano-wallet/releases). -- Download up-to-date configuration files from [Cardano configurations](https://hydra.iohk.io/job/Cardano/iohk-nix/cardano-deployment/latest/download/1). +- Download up-to-date configuration files from [Cardano Book](https://book.world.dev.cardano.org/environments.html). #### Start `cardano-wallet` in full node mode -We are going to use `testnet` configuration in this example. +> :information_source: Configuration files for all Cardano networks can be found in [Cardano Book](https://book.world.dev.cardano.org/environments.html). 1. Start node: ```bash $ cardano-node run \ - --config testnet-config.json \ - --topology testnet-topology.json \ + --config config.json \ + --topology topology.json \ --database-path ./db \ --socket-path /path/to/node.socket ``` 2. Start wallet: + +When starting wallet against any testnet environment like `preview` or `preprod` we need to feed wallet with `byron-genesis.json` file: + +```bash +$ cardano-wallet serve --port 8090 \ + --node-socket /path/to/node.socket \ + --testnet byron-genesis.json \ + --database ./wallet-db \ + --token-metadata-server https://metadata.cardano-testnet.iohkdev.io +``` +In case of `mainnet` we simply replace `--testnet byron-genesis.json` with option `--mainnet`. + ```bash $ cardano-wallet serve --port 8090 \ --node-socket /path/to/node.socket \ - --testnet testnet-byron-genesis.json \ + --mainnet \ --database ./wallet-db \ - --token-metadata-server https://metadata.cardano-testnet.iohkdev.io/ + --token-metadata-server https://tokens.cardano.org ``` +> :information_source: Notice that we use different urls for `mainnet` and `testnet` `--token-metadata-server` option. These are links to [Cardano Token Registry](https://developers.cardano.org/docs/native-tokens/token-registry/cardano-token-registry) servers. See [[assets]] for more information. + That's it! We can basically start managing our wallets from this point onwards. See [[how-to-create-a-wallet]] and [[how-to-manage-wallets]]. However, in order to be able to make transactions, we still need to wait until `cardano-node` is synced fully with the Cardano blockchain. In case of `mainnet` it may take several hours, in case of `testnet` a bit less. @@ -52,7 +68,7 @@ $ curl -X GET http://localhost:8090/v2/network/information | jq .sync_progress ## Light mode -> :warning: This mode is currently **under development**. Please note that some parts may be available only in `master` branch. +> :warning: This mode is currently **under development**. Please note that some parts may not work. You can start your cardano-wallet server also in **light mode**. As opposed to full-node mode, in light-mode your wallet is not connected to a locally running instance of `cardano-node`. Instead it relays on external source of blockchain data. This significantly improves synchronization speed of the wallet and also removes the need to spend time synchronizing the node itself. The downside is that external source of data is obviously less trusted than the local one provided by your own `cardano-node` instance. @@ -75,7 +91,7 @@ $ cardano-wallet serve \ --port 8091 \ --light \ --blockfrost-token-file blockfrost-testnet.key \ - --testnet testnet-byron-genesis.json \ + --testnet byron-genesis.json \ --database ./wallet-testnet-db-light \ ``` ##### Mainnet From f8b2da3651ceea6adbe1e7dcf972c7ff75bd349f Mon Sep 17 00:00:00 2001 From: Piotr Stachyra Date: Tue, 18 Oct 2022 14:45:27 +0200 Subject: [PATCH 2/3] Address review remarks --- docs/user-guide/common-use-cases/TxMetadata.md | 2 +- docs/user-guide/common-use-cases/assets.md | 11 +++++------ docs/user-guide/common-use-cases/delegation.md | 6 +++--- .../common-use-cases/how-to-make-a-transaction.md | 2 +- .../common-use-cases/how-to-start-wallet-server.md | 4 ++-- 5 files changed, 12 insertions(+), 13 deletions(-) diff --git a/docs/user-guide/common-use-cases/TxMetadata.md b/docs/user-guide/common-use-cases/TxMetadata.md index af9af35b178..50a4d17d714 100644 --- a/docs/user-guide/common-use-cases/TxMetadata.md +++ b/docs/user-guide/common-use-cases/TxMetadata.md @@ -6,7 +6,7 @@ order: 8 - [[how-to-start-wallet-server]] - [[how-to-create-a-wallet]] - - In order to be able to send transactions we need funds on the wallet. In case of [Testnet](https://testnets.cardano.org/en/testnets/cardano/overview/) we can request tADA from the [faucet](https://testnets.cardano.org/en/testnets/cardano/tools/faucet/). + - In order to be able to send transactions, our wallet must have funds. In case of `preview` and `preprod` [testnets](https://testnets.cardano.org/en/testnets/cardano/overview/) we can request tADA from the [faucet](https://testnets.cardano.org/en/testnets/cardano/tools/faucet/). ## Transaction Metadata diff --git a/docs/user-guide/common-use-cases/assets.md b/docs/user-guide/common-use-cases/assets.md index 0fdf2d73681..dcb98769eaf 100644 --- a/docs/user-guide/common-use-cases/assets.md +++ b/docs/user-guide/common-use-cases/assets.md @@ -7,7 +7,7 @@ title: Managing native assets - [[how-to-start-wallet-server]] - [[how-to-create-a-wallet]] - - In order to be able to send transactions we need funds on the wallet. In case of `preview` and `preprod` [testnets](https://testnets.cardano.org/en/testnets/cardano/overview/) we can request tADA from the [faucet](https://testnets.cardano.org/en/testnets/cardano/tools/faucet/). + - In order to be able to send transactions, our wallet must have funds. In case of `preview` and `preprod` [testnets](https://testnets.cardano.org/en/testnets/cardano/overview/) we can request tADA from the [faucet](https://testnets.cardano.org/en/testnets/cardano/tools/faucet/). ## Overview @@ -62,7 +62,7 @@ You can also list assets that were ever associated with the wallet. ## Assets off-chain metadata -Issuers of native assets may put some off-chain metadata about them in the **Cardano Token Registry**. There are separate instances of token registry for `mainnet` and testnets (e.g. `preview` or `preprod`). Users can submit metadata to the repository which will be then served via corresponding server. +Issuers of native assets may submit off-chain metadata relating to those assets to the **Cardano Token Registry**. There are separate instances of the token registry for `mainnet` and for each test network (e.g. `preview` or `preprod`). Metadata submitted to the registry will be then served via the corresponding server. | | Mainnet | Testnets | |--|--|--| @@ -71,7 +71,7 @@ Issuers of native assets may put some off-chain metadata about them in the **Car > :information_source: Read more: [Cardano Token Registry](https://developers.cardano.org/docs/native-tokens/token-registry/cardano-token-registry), [CIP26](https://cips.cardano.org/cips/cip26). -Cardano-wallet is capable of reading that metadata and serving it along while listing assets. All you have to do is to start wallet with `--token-metadata-server` parameter pointing to an off-chain metadata server corresponding to your network. +Cardano-wallet is capable of reading that metadata and serving it when listing assets. All you have to do is to start the wallet with the `--token-metadata-server` option, specifying an off-chain metadata server that corresponds to your network. For example on `preview` or `preprod` that would be: @@ -147,8 +147,7 @@ $ curl -X POST http://localhost:8091/v2/wallets/73d38c71e4b8b5d71769622ab4f5bfde "policy_vk12d0gdel9u6px8wf3uv4z6m4h447n9qsad24gztaku8dzzdqfajzqfm3rr0" ``` -Once we sort it out we are all set and we can proceed into minting NFT from our wallet! - +Once we have finished, we can proceed to minting NFTs from our wallet! #### CIP-25 metadata @@ -276,7 +275,7 @@ $ curl -X POST http://localhost:8090/v2/wallets/73d38c71e4b8b5d71769622ab4f5bfde ``` That's it! I should now receive CBOR-encoded `transaction`, `fee` and `coin_selection` details in response. I can now **sign** and **submit** such a transaction just like in [[how-to-make-a-transaction]]. -Once transaction submitted your freshly minted NFT should be added to the wallet balance! +After the transaction has been submitted, your freshly-minted NFT should appear in your wallet balance! ### Burning an NFT diff --git a/docs/user-guide/common-use-cases/delegation.md b/docs/user-guide/common-use-cases/delegation.md index f4072fe67d4..f8046d6b7fe 100644 --- a/docs/user-guide/common-use-cases/delegation.md +++ b/docs/user-guide/common-use-cases/delegation.md @@ -7,7 +7,7 @@ title: Delegation - [[how-to-start-wallet-server]] - [[how-to-create-a-wallet]] - - In order to be able to send transactions we need funds on the wallet. In case of `preview` and `preprod` [testnets](https://testnets.cardano.org/en/testnets/cardano/overview/) we can request tADA from the [faucet](https://testnets.cardano.org/en/testnets/cardano/tools/faucet/). + - In order to be able to send transactions, our wallet must have funds. In case of `preview` and `preprod` [testnets](https://testnets.cardano.org/en/testnets/cardano/overview/) we can request tADA from the [faucet](https://testnets.cardano.org/en/testnets/cardano/tools/faucet/). ## Overview @@ -135,7 +135,7 @@ $ curl -X POST http://localhost:8090/v2/wallets/1b0aa24994b4181e79116c131510f2ab -H "Content-Type: application/json" ``` -After constructing delegation quit transaction I should receive CBOR-encoded `transaction`, `fee` and `coin_selection` details in response. +After constructing a transaction that undelegates from a stake pool, I should receive a CBOR-encoded `transaction`, `fee`, and `coin_selection` in the response. I can now **sign** and **submit** such a transaction just like in [[how-to-make-a-transaction]]. -> :information_source: Note that all rewards will be withdrawn only if you add {"withdrawal":"self"} to the payload. You can do it in a single transaction though as above. +> :information_source: Note that all rewards will be withdrawn only if you add {"withdrawal":"self"} to the payload. You can achieve this with a single transaction, as shown above. diff --git a/docs/user-guide/common-use-cases/how-to-make-a-transaction.md b/docs/user-guide/common-use-cases/how-to-make-a-transaction.md index 7b206e97309..60c50f932cb 100644 --- a/docs/user-guide/common-use-cases/how-to-make-a-transaction.md +++ b/docs/user-guide/common-use-cases/how-to-make-a-transaction.md @@ -7,7 +7,7 @@ title: How to make a transaction - [[how-to-start-wallet-server]] - [[how-to-create-a-wallet]] - - In order to be able to send transactions we need funds on the wallet. In case of `preview` and `preprod` [testnets](https://testnets.cardano.org/en/testnets/cardano/overview/) we can request tADA from the [faucet](https://testnets.cardano.org/en/testnets/cardano/tools/faucet/). + - In order to be able to send transactions, our wallet must have funds. In case of `preview` and `preprod` [testnets](https://testnets.cardano.org/en/testnets/cardano/overview/) we can request tADA from the [faucet](https://testnets.cardano.org/en/testnets/cardano/tools/faucet/). ## Old transaction workflow diff --git a/docs/user-guide/common-use-cases/how-to-start-wallet-server.md b/docs/user-guide/common-use-cases/how-to-start-wallet-server.md index 5517f1f29cf..1f9035f66d5 100644 --- a/docs/user-guide/common-use-cases/how-to-start-wallet-server.md +++ b/docs/user-guide/common-use-cases/how-to-start-wallet-server.md @@ -33,7 +33,7 @@ $ cardano-node run \ ``` 2. Start wallet: -When starting wallet against any testnet environment like `preview` or `preprod` we need to feed wallet with `byron-genesis.json` file: +When starting a wallet instance that targets a testing environment such as `preview` or `preprod`, we need to provide a `byron-genesis.json` file to the wallet: ```bash $ cardano-wallet serve --port 8090 \ @@ -51,7 +51,7 @@ $ cardano-wallet serve --port 8090 \ --database ./wallet-db \ --token-metadata-server https://tokens.cardano.org ``` -> :information_source: Notice that we use different urls for `mainnet` and `testnet` `--token-metadata-server` option. These are links to [Cardano Token Registry](https://developers.cardano.org/docs/native-tokens/token-registry/cardano-token-registry) servers. See [[assets]] for more information. +> :information_source: Notice that we use different URLs for mainnet and test networks with the --token-metadata-server option. These URLs point to [Cardano Token Registry](https://developers.cardano.org/docs/native-tokens/token-registry/cardano-token-registry) servers. See [[assets]] for more information. That's it! We can basically start managing our wallets from this point onwards. See [[how-to-create-a-wallet]] and [[how-to-manage-wallets]]. From c15f9fdb0affa9705567c596a4b4ea7dfcdb3991 Mon Sep 17 00:00:00 2001 From: Piotr Stachyra Date: Tue, 18 Oct 2022 14:46:17 +0200 Subject: [PATCH 3/3] Bring back cardano icon into API doc (as SVG) --- specifications/api/swagger.yaml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/specifications/api/swagger.yaml b/specifications/api/swagger.yaml index 9b094e551e1..228d30dd46e 100644 --- a/specifications/api/swagger.yaml +++ b/specifications/api/swagger.yaml @@ -6,7 +6,9 @@ info: name: Apache-2.0 url: https://raw.githubusercontent.com/input-output-hk/cardano-wallet/master/LICENSE description: | -

+

+ +

externalDocs: description: Need more? Click here to access our API guide and walkthrough. url: https://input-output-hk.github.io/cardano-wallet/