Chainweaver User Guide

Chainweaver is available for download in three formats to accommodate users’ preference in operating system; (1) .dmg for Mac, (2) .deb for Linux, (3) and .ova for Windows, Linux, and Mac as a virtual appliance

.dmg for Mac

Compatible with macOS High Sierra 10.13 and above

Navigate to your downloads folder, open the .dmg, and drag the application into your Applications folder.

.deb for Linux

Compatible with Ubuntu 18.04

Navigate to your downloads folder and double click the .deb.

Click the install button on the install window that pops up.

There should be a progress bar that appears and progresses to completion until you see this installed state. Be sure to check that the installed version is the one that you tried to install.

You can now find Chainweaver in the applications menu.

With this icon

.ova for Windows, Linux, and Mac

First, make sure that you have VirtualBox installed as this virtualisation app is required to run the OVA.

Navigate to your downloads folder and double click the .ova.

You should get an import virtual appliance dialog which you can safely accept the defaults and press import.

Once this is imported, you can run the virtual machine by double clicking "Kadena Chainweaver VM" in the list of VMs.

This will start the virtual machine and it will boot like a normal computer. Eventually you should see Chainweaver like this.

Upgrade to the latest version of Chainweaver by double-clicking the “Upgrade Kadena Chainweaver” icon from the desktop

Create a new wallet

Three main steps; (1) set password, (2) record recovery phrase, (3) verify recovery phrase

After creating the wallet you might want to continue creating the account on the blockchain.

Restore existing wallet from recovery phrase

Three main steps; (1) enter recovery phrase, (2) set new password, (3) re-generate keys

Restore existing wallet from wallet export

Two main steps; (1) select file, (2) enter password

​Chainweaver's interface consists of three main elements; (1) Network Display, (2) Sections Menu, (3) Main Viewer

Network Display (top bar) This display bar persists across all screen views within Chainweaver so that you will always know the network with which you are interacting

Sections Menu (left bar) Use this menu to go to different Sections

Main Viewer (center screen) This is where you interact with the section you have chosen from the Sections Menu.

Upgrading Chainweaver is an essential part of keeping your crypto assets safe and enjoying new features for interacting with the Kadena blockchain ecosystem. The latest version of Chainweaver will always be available for download at https://www.kadena.io/chainweaver.

Chainweaver allows you to interact with different networks, including the main network (“Mainnet”) and a test network (“Testnet”)

You can change the network with which you are actively interacting by selecting the drop-down arrows beside the displayed network in the Network Display top bar.

Simply select the desired network from the available list and confirm the selection. The keys displayed in the wallet will persist across networks, while the accounts list will refresh to display those that you have added on the chosen network.

You can add your own custom network by selecting the appropriate option from the Settings section.

To create a new network, you will have to define a network name then enter the addresses for the nodes to which you would like the network to connect. Node status is displayed with a traffic light style indicator.

Note

Custom networks are defined locally and will only be visible within the application that created it. It is recommended that a network connect to at least 3 nodes.

In brief, Keys sign transactions and Accounts may be governed by one or multiple keys.

With most blockchains, accounts are modeled as simply public/private keypairs. This one-to-one model keeps things simple, but runs into problems when account control requires a many-to-many model (such as with jointly owned or majority ruled accounts).

Kadena natively supports multiple keys governing the same account, and thus the distinction between Keys and Accounts becomes important.

Every Account is governed by a keyset which must be defined when creating any Account. Keysets are composed of two parts; (1) a set of keys and (2) a predicate

Summarily, keysets look like the following as JSON data:

When signing a transaction, the list of private keys supplied as signing key pairs will be checked against the keyset and predicate to ensure that not only are all keys that need to be present accounted for but also that the predicate is satisfied.

The first step towards transacting on the Kadena blockchain is to generate a key pair. Chainweaver automatically generates your first key.

Select the “Generate Key” button to add additional keys to your wallet, then continue to Accounts.

Accounts are effectively equivalent to your identity on the blockchain. When you add an Account in Chainweaver, you will be able to view information about it such as its keyset info and balance on each of the known chains.

Select “+ Add Account” to view existing accounts or create a new account.

Optionally, you can add personal notes beside any account. This field is never seen by the blockchain, and only serves as a personal reference to organize a user’s wallet.

To create, and effectively own, an account name on Kadena, there must be a record of it on the blockchain. The recommended method for creating an account is to simply transfer some funds to it. In doing so, you transfer to and create the account in a single transaction.

Before transferring to any account, first check to see whether the account name already exists. Do this by selecting the “Add Account” button and entering the desired account’s name. If the account does not exist, then you will see “Does not exist” as the balance for the corresponding Chain ID row.

There are two ways to perform the “transfer & create” operation.

Method 1: Tx Builder

Method 2: Manual entry

Remember that the Kadena public blockchain network is comprised of many chains braided together. In effect, each chain is a standalone blockchain, therefore you will have to create your desired account on each chain for which you want it to exist. Naturally, the same account name will have a different account balance on each chain, and may also have different owners or a different keyset. Always be sure to take note of the chain on which you are transacting.

To remove an account from view, select the Details button beside the desired account

Select “Remove Account”

Read the warning message and confirm your selection by selecting “Remove Account”

Kadena natively supports multiple keys governing the same account, allowing for dynamic account controls such as jointly owned accounts or the ability to rotate which keys may govern an account.

As a result of this novel capability, it is important for users to clearly understand which accounts they own and which they may not own. For convenience, Chainweaver displays whether you are the owner of any account that you are watching.

Among other powerful user controls, two concepts are introduced through Chainweaver which provide the user with greater transparency and control; (1) granting capabilities and (2) Tx Builder.

Granting capabilities

Performing transfers necessitates a call to the blockchain’s coin contract. This contract describes the rules for transferring coins and one such rule requires that the Sender account grant the capability to transfer coins in order for the transaction to be submitted. The act of granting capabilities is akin to authorizing or signing a transaction. In more advanced scenarios some contracts require multiple capabilities to be granted. This concept gives the user greater control and transparency to what they are signing.

Tx Builder

This is a JSON blob including the necessary information to build a transaction. For simple transfers it might include just an account name and chain ID, like this:

For account creation it might also include a keyset, like this:

While users will never need to compose this code themselves, it is important to become familiar with reading it to understand how some blockchain operations work.

There are two recommended approaches for receiving KDA

Method 1: Tx Builder — best for receiving KDA from a sender who is also using Chainweaver

Method 2: Account Name + Chain ID — best for receiving KDA from a sender who is not using Chainweaver

Since the Kadena public blockchain network braids multiple chains together, you can transfer KDA within a single chain or across two different chains.

Transfer between the same chain

Navigate to the Account section and select “Transfer Coins” to reveal the transfer tool.

Fill in the required fields then select the "Sign & Transfer" button.

This will open the Sign Transfer dialog which allows you to configure transaction settings.

Once satisfied, select Next to view the Signatures tab. If any external signatures are required, you will be prompted to enter them here.

Preview the transaction to ensure the Summary Data and Transaction Result output displays the desired outcome. If everything looks correct, select Send Transfer to submit the transaction to the blockchain.

Transfer between different chains

This process has one distinct difference from transfers on the same chain. This time when you configure the transaction, you must select two Gas Payers:

It may seem unusual to have to pay for gas twice, but consider what is happening with a cross-chain transfer. In this scenario you are moving coins between two different blockchains, each with their own ledger. Therefore gas on one chain cannot pay for executing operations on a different chain.

Transfer from non-Chainweaver accounts

In addition to signing transactions from accounts which are owned within the wallet, Chainweaver also provides an interface to sign transactions from accounts which are not owned within the wallet. Chainweaver does this by auto-detecting whether the sending account is owned by the wallet. If the sending account is not owned by the wallet, Chainweaver will present a field for the user to enter the required private key(s). This special feature makes it easier for users to transfer KDA into Chainweaver from external wallets and exchanges.

Before you submit any transaction or deploy any smart contract, you will have the opportunity to configure a few settings. You can adjust both the Gas Price and the Gas Limit of your transaction. As either of these settings are adjusted, you can see how these changes might affect Transaction Speed and Max Transaction Fee.

Once a transaction has been submitted, Chainweaver will display the Transfer Status as it moves through progress states. The average block time in the Kadena network is 30 seconds. So depending on the Transaction Speed you assigned, it may take several blocks before your transaction is successfully mined.

Transaction success: When the transaction has been successfully mined in a block, a Transaction Result will display.

Transaction failure: If the transaction fails at any progress state then a red “X” will appear beside the failing state.

If you have a request key from a previously submitted transaction, you can also display its result by selecting the “Check Tx Status” button.

The ability to write, deploy, and call smart contracts from within Chainweaver makes it one of the most comprehensive workbench tools for blockchain. Navigate to the Contracts section and utilize the integrated development environment (IDE) for developing and testing Pact smart contracts.

Pact is the safe and simple smart contract language used for interacting with the Kadena blockchain. Visit learn pact for developer tutorials covering key concepts and real projects you can deploy yourself.

Once you have written the code for your new smart contract in the code editor, check the ENV tab of the tool panel on the right side for any error messages that might be displayed. Once you are satisfied with your code, you can either select “Load into REPL” or “Deploy.”

Should you select “Deploy,” you will next be prompted to designate the transaction destination and settings. On the “Sign” tab you must enter any new capabilities as defined in your contract code, then select the account to authorize each capability.

Once all required fields have been entered, select the “Preview” button. Here you will be able to review and confirm details before submitting the transaction.

Once a contract has been deployed, it will show up in the “Deployed Contracts” table under the “Module Explorer” tab of the Contracts tool panel. Contracts can be filtered by chain or through search.

Select “View” beside your chosen contract to reveal all of the available functions to call.

Select “Call” beside your chosen function to open a three-part dialog:

Preview the transaction, then select “Create Transaction” to execute the operation.

As a user, interacting with dApps is simple. Chainweaver takes advantage of a novel wallet signing API which facilitates communication between dApps and wallets.

First ensure your Chainweaver desktop application is open. When you’re ready to start some transaction with a dApp, initiate the request by submitting the required information (e.g. account name) to the dApp.

Once a call has been made, by pressing a button on the dApp interface or through some other means, the signing API will hit Chainweaver. When Chainweaver receives an API call, a new dialog will appear within Chainweaver displaying input data from the dApp.

Review the transaction details and complete the flow as you would for any other transaction; configure settings, grant capabilities, preview and create.

Kadena uses Ed25519 public/private key pair signatures. Chainweaver can be used to easily generate compatible key pairs. Alternatively, you can generate key pairs yourself by following any kind of Ed25519 key generation method such as this one contributed to our community GitHub.

As with any valuable asset, it is important to establish a secure and reliable method for controlling who has access to it. While Chainweaver is designed to satisfy strict security standards, you are ultimately responsible for maintaining the security of your wallet’s access credentials—the password and recovery phrase.

Passwords: Consider using a password manager to generate a strong password with randomness of character types. If you decide to create a password yourself, make sure it is not the same or similar to any other password you have ever used.

Recovery phrases: This 12-word phrase is the master seed that generates all your wallet’s public/private key pairs. With this phrase, anyone can control your wallet, even from another device. Consider securing more than one copy to prevent a single point of failure from events like fires, loss, etc.

Kadena does not control any of your personal/private data on our servers. Never share passwords or recovery phrases with anyone, including the Kadena team. We will never ask for you to provide this. If someone claims that we do, insist on not sharing.

Anyone with your wallet's password, private keys or recovery phrase can access your account. Passwords, private keys, and recovery phrases are in the users’ hands and are the users’ responsibility. Chainweaver is simply an interface that allows you to more easily interact with your accounts and the Kadena blockchain.

Lost password

If you lose your password, you can reset it by using your 12-word recovery phrase to restore the wallet with a new password.

Lost both password and recovery phrase

If you lose both your password and recovery phrase, you will permanently lose access to any accounts and their funds forever.

Kadena does not manage accounts with information such as passwords, private keys, or recovery phrases. We only have access to the information that is publicly available on the blockchain. We do not have servers and we do not hold your assets.

Change your password by navigating to the Settings section and selecting the appropriate button.

Export your wallet by navigating to the Settings section and selecting the appropriate button.

Exporting wallet data will generate an encrypted file containing sensitive and non-sensitive information available within the wallet. The file will be protected by the wallet password that was in use at time of export. Store this file in a secure location and do not alter its contents.

The wallet data to be exported within this file includes:

View and export your wallet’s transaction log by navigating to the Settings section and selecting the appropriate button.

The “Log out” button in the lower-left of the Section menu will lock your wallet. A locked wallet cannot sign transactions or receive signing API calls.

Find out about the latest improvements to Chainweaver here.

Kadena staff will never ask for sensitive information, including passwords, recovery phrases or private keys.

Beware of fake accounts and scam attempts.

Chainweaver will only communicate through verified channels.

Join our Discord server here and chat live with Kadena developers and the community on the #chainweaver channel