Guides

Menu...

Introduction

Here you will find a list of advanced guides to help you use the Nexus Wallet for purposes such as registering Assets, creating Tokens and Namespaces. If you have any further questions please join one of the Nexus Community Channels found in the footer, and post a message asking for help.

What is an Asset?

In its simplest form, an Asset is nothing more than arbitrary data stored on the Nexus blockchain in a state register. You as the user can decide what data is stored in that Asset, and depending on the way the Asset is created, whether or not the data in the Asset can ever be changed (is mutable / immutable). Think of it like writing on a piece of paper. You can choose to write what you want on that piece of paper. If you write it in ink then it is permanent. If you write some of it in pencil, then you can erase it and change it to something else.

What is a State Register?

The Nexus architecture uses state registers for storing many different types of data including Accounts, Tokens, Names, and Assets. A state register sounds fancy, but it is really just a space where information can be stored.

With the Nexus API, you can make special kinds of transactions to create these registers or update / append to the data in them. When the data in a register changes, it is said that the register is 'changing state' from what it was previously to what you are now changing it to - hence the name state register.

Every register on the Nexus blockchain has two main properties: An address (referred to as a register address) which is used to determine the location of the data in the register database, and an owner, which is the genesis hash of the Signature Chain that currently owns the register.

What can Assets be used for?

Allowing users to store arbitrary data in a blockchain is not a new concept - we've been able to do that since the early days of Bitcoin. What's unique about Nexus' register-based blockchain is that all changes to a register - including changes to the data and to the ownership of it - are captured in the transactions recorded on the blockchain. Not only does this allow us to validate data changes via consensus rules, but it also allows us to view the entire history of changes to the data in a register and its ownership.

It becomes an audit log for data, allowing users to see what that data looked like and who owned it at any point in time. That's a hugely powerful concept and opens the door to many use cases where a history of the data is required, e.g. supply chains, postal tracking, land/real estate deeds, certificates of authenticity, art watermarking, wills, etc. Each Asset is owned by a Signature Chain, which is great for situations where there is one single owner of an Asset.

However, what about those use cases where partial ownership is required, for example where a piece of real estate is owned by two or more investors and they want to prove their ownership via a public blockchain? Nexus solves this by allowing an Asset to be tokenized, which means that the ownership of an Asset is transferred to a token rather than a Signature Chain. Once tokenized, any users that hold the tokens in their Signature Chain become partial owners of the Asset, much like owning shares in a company.

Furthermore, tokenized Assets provide the ability for shared revenue to be automatically distributed in the form of NXS payments to the partial owners of the Asset, based on the percentage of tokens held. This is useful for use cases such as the automatic payment of dividends for Security Token Offerings (STO's), and for the distribution of royalties from revenue earned from an Asset such as a music album.

How do I create an Asset?

The Nexus API provides a straightforward and intuitive interface for users to create, update, and transfer Assets. To create a basic Asset you can use the Wallet console or Nexus command line interface (CLI) and issue a simple command:

assets/create/asset name=myfirstasset data=this_is_some_data

The create/asset API method allows the Asset to be defined in several different formats. Shown above is the basic format, which is the default. In the basic format the data is supplied in key=value pairs, all data is treated internally as a string (a series of alphanumeric characters), and all data is immutable (cannot be changed). The create/asset API alternatively allows complex Assets to be defined using JSON format.

The following example shows how an Asset might be used to store the title deeds to a property:

assets/create/asset

name=deed1A
address=1640 Riversdale Drive, CA
deed-id=494563494
certificate-url=http://www.property.com/deeds/494563494.pdf
certificate-md5-hash=67ac5a9362efdef5a52e5438c4ad7bda

What does it cost to create an Asset?

The fee charged for creating Assets depends on the amount of data you are storing. The charge is 0.01 NXS ber byte, with a minimum fee of 1 NXS. This means that the cost of an Asset will be between 1 and 10 NXS depending on how much data it contains.

How much data can I store in an Asset?

Currently all registers are limited to a maximum of 1Kb, which is about 1000 characters of text.

How do I transfer an Asset?

You can transfer ownership of an Asset to another Signature Chain with a simple API command specifying the name/address of the Asset you own, and the username/genesis of the recipient:

assets/transfer/asset name=myasset username=bob

How do I define which fields are editable?

In order to update data in an Asset, you have to initially create them using a JSON format, as opposed to the basic format shown above. Using the JSON format allows you to specify field type, length, mutability, and an initial value for each data field in the Asset.

What is a Token?

In the broader sense, tokens can be thought of as virtual currencies that exist on a blockchain.

What can Tokens be used for?

They can be used for a variety of uses such as:

  1. Representing ownership in an Asset:

    • a company
    • property / land title
    • rights to a book / album / film / piece of art
    • patents
  2. Utilities
  3. Loyalty programs
  4. Gaming tokens
  5. DAO voting rights

How does a Token created on the Nexus blockchain differ to tokens created on Ethereum, Waves, NEO, NEM, Stellar, etc?

The primary difference is simplicity. To create a token on Ethereum, or most other token platforms, users must write a smart contract - code written in a specific programming language - to define the token and how it will be used/distributed. This requires the user to have programming skills and the task can often be quite complicated. Nexus has taken a different approach by simplifying the process, allowing users to create a token in one short console command / API request. The wallet interface goes a step further providing a simple interface to guide users through the process.

Are there any limitations to this simplified approach?

The tradeoff for simplicity is flexibility. A token created from a traditional smart contract allows developers to define any rules they wish for the distribution and use of a token, which are encoded in the token definition contract. This flexibility is certainly useful, but is overly complex for people without programming skills.

Nexus decouples the contract rules from the token definition allowing the token creation to be far simpler, though provides further steps if more complex rules are needed. For those use cases that require more complex token utility, Nexus users can add contract rules as conditions to token debit transactions.

If the rules are too complex to be supported by a transaction condition, developers can write these rules into their application layer.

What properties does a token have?

When you first create a token you must specify the supply (the maximum number of whole tokens that will be available) and decimals (the number of decimal places that a token amount can have).

The combination of these two values gives the number of token divisible units that will be available (the equivalent of Bitcoin’s Satoshi’s property). For example a decimals value of 3 means that each token can be divided into 10^3 (1,000) parts. Therefore a token created with a supply of 1,000,000 and decimals of 3 would result in 1,000,000,000 (1,000,000 x 1,000) token divisible units. This is important, as this figure is what is used to calculate the fee applied when creating the token.

Once created, the token has three important properties:

  • maxsupply - the maximum number of tokens that will exist
  • currentsupply - the number of circulating tokens that have been distributed to token accounts
  • balance - the number of tokens that have not yet been distributed (maxsupply - currentsupply)

How do I create a token?

Tokens can easily be created through the Nexus Wallet or the console/CLI. The user defines a new token so that it can be distributed, traded, or used to tokenize an asset.

To create a new Token, go to the User module in the Wallet, and please follow the below instructions:

  1. Click on Tokens.
  2. Click Create new Token.
  3. Choose a Token Name.
  4. Choose the total number of Tokens to be created.
  5. Choose the amount of significant digits the Token will have.
  6. At the top of the box, the fee will be displayed in NXS for creating your supply of tokens.
  7. Click Create Token.
  8. Pay Fees.

To achieve the same using the console use the following command:

tokens/create/token name=My Token supply=100 decimals=2

How much does it cost to create?

The fee is based on the number of token divisible units you define (the combination of supply and decimals). There is a minimum fee of 1 NXS and the calculation is linear thereafter, so that each additional significant digit costs an additional 100 NXS. E.g.

100 units = 1 NXS

1000 units = 100 NXS

1000000 units = 400 NXS

10000000000 units = 800 NXS

How do I distribute my token?

Initially all of the token supply is held in the balance of the token. Distributing your token to other users is then very similar to how you send NXS. The first step is that the receiving users must create a new account for your token type and then provide you with the account name/address. Then you can use the wallet interface to send them just like you would send NXS, choosing the token from the Send From list. Alternatively, you can use the console with the following command:

tokens/debit/token name=My Token name_to=paul:tokenaccount amount=1000

Can I increase the supply once I have created my token?

At the time of writing, no the maximum supply cannot be changed once the token has been created. However, this ability is planned for a future release. How do I use a token to represent partial ownership of a digital or real-world asset?

One of the most significant use cases for tokens is the ability to tokenize an asset. Tokenized Assets provide the ability for shared revenue to be automatically distributed in the form of NXS payments to the partial owners of the Asset, based on the percentage of tokens held. This is useful for use cases such as the automatic payment of dividends for Security Token Offerings (STO’s), and for the distribution of royalties from revenue earned from an Asset such as a music album.