Getting Started: Developing with Nano Currency — Part 1: Build your foundation
This post is part of a series of posts that help developers/coders/tinkerers of all levels get started coding with Nano Cryptocurrency.
- Build your foundation [this article]
- Interacting with Public and Private Nodes
- Interacting with Programmable Software Wallets [not yet published]
Disclaimer: I link to many apps/frameworks/projects with which I have no association. While I have personally used every app/framework/project that I reference, I can not guarantee its security or availability. When in doubt, never use a “seed” or private key given from software you don’t know to be secure. Also, I have no association with the Nano Foundation and nothing in these articles should be taken as “Official” guidance. I am simply an advocate for Nano and want to support the Nano Community, and specifically those looking to code with Nano, as best I can.
Hey devs of all sorts! No matter your coding experience, getting started with writing code that interacts with the Nano Network is actually quite simple.
The simplicity, however, is dependent on being familiar with the terminology and the possessing a basic understanding of Nano. In other words, you first need to build your foundation. Nano is different from most every other cryptocurrency. This difference is what excites me, personally, and is what enables the near instant, feeless, and eco-friendly attributes that so many people gravitate towards. I think as you begin to understand Nano, you will find it extremely intuitive as its behaves very similar to cash.
For this article I am going to take a top-down approach. I want you to understand the Nano Network first. Then I want you to understand the infrastructure that supports the Nano Network. And then, finally, I want you to understand the life of the Nano Network, the blocks that enable transactions and change the state of the network.
The Nano Network is a decentralized peer-to-peer (p2p) network in which Nano currency is securely transacted [ref]. Decentralized peer-to-peer means that Nano Nodes, require no coordinator to orchestrate their communications or actions.
Consensus across the Nano Network (what determines whether a Nano Block is valid) is determined by Open Representative Voting (ORV). ORV, while interesting, is beyond the scope of these “Getting Started” articles. As a developer getting started, you simply need to know that the Nano Network will confirm Nano Blocks that are valid and reject Nano Blocks that are invalid, but more on that below.
A Nano Node is a piece of software that communicates on the Nano Network. As a developer, this is the interface with the Nano Network that you will care most about (topic of our second “Getting Started” article). The Nano Foundation releases a Nano Node (open source) that is the accepted standard across the network. There exists multiple Public Nano Nodes with Public APIs with which you can communicate. But you can also download and operate your own Nano Node.
The Nano Node released by the Nano Foundation runs a remote procedure call (RPC) server and this is how we will communicate with the Nano Network.
It is worth mentioning that in the Nano Network, not all Nano Nodes are equal. A Nano Node can double as a “Representative”. Simply, a representative Nano Node is a node that has been delegated voting weight from one or more Nano Accounts via a Nano Block. And a Representative can be a “Principal Representative”, meaning its votes actually count towards determining consensus. But again, consensus across the Nano Network, is beyond the scope of these articles.
A software wallet is a piece of software that manages the Nano Wallet (and derived Nano Accounts) on behalf of a user. There are two different types of software wallets, (1) non-programmable and (2) programmable. Most people utilize a non-programmable software wallet when they send and receive cryptocurrencies. It typically provides a point-and-click experience to the user. There exists many choices for non-programmable Nano software wallets.
A programmable software wallet is more interesting (to me) and relevant to our conversation, though. Programmable software wallets provide some type of API (CLI, RPC, etc.) for interaction with the wallet. The Nano Foundation’s Nano Node includes a software wallet accessible via RPC (recommended for development and testing only). However, there also exists Pippin Nano Wallet, which does not require a self-hosted Nano Node. We will dive much deeper into programmable software wallets in our third article.
While the user experience between a non-programmable and a programmable software wallet is vastly different, at their root, they accomplish mostly the same set of tasks.
- Create a Nano Wallet
- Create one or more Nano Accounts
- Send Nano
- Receive Nano
- Change representative
There is obviously a lot more depth in processes than what this workflow offers, and we will tackle some of it below, and some of it in future articles.
Identified by a “seed”, from which all of your accounts (and their private keys) are derived, a Nano Wallet is a data structure with deterministic characteristics. Don’t get confused between a Software Wallet and a Nano Wallet. A Software Wallet (typically an application) is simply an interface for managing and protecting your Nano Wallet (a data structure).
In the above “Nano Software Wallet Workflow” figure, you can see that a seed is generated with a new Nano Wallet. I want to take time on this concept because it is critical to understand. The seed, is the key to all of your Nano Accounts in that Nano Wallet. It doesn’t matter what Software Wallet you use, they are mutually exclusive, if the seed is entered into two different Software Wallets at the same time, both of those Software Wallets will have access to the same Nano Wallet.
Here are three rules when it comes to a seed:
- Never share your seed with an untrusted person or software
- Always backup your seed in a way that can not be compromised
- Only use a seed generated from a trusted source
Protecting the seed is why people use hardware wallets. A hardware wallet will enable the seed to be used to create accounts and subsequently sign Nano Blocks (send, receive, change representative) without the seed ever being exposed to a user’s device (Internet connected, assume compromised, etc).
As a developer, if you are creating a seed or storing a seed for a user, you need to be absolutely certain you are doing so securely. For this series of “Getting Started” articles, I will defer to the Nano Foundation’s guide on “Key Management” as our focus will be on interacting with the Nano Network and not on secure coding practices or key management.
Nano Accounts are deterministically derived and indexed from the Nano Wallet. And there is no limit to the number of Nano Accounts that can be derived from a Nano Wallet.
For illustration purposes let’s go through an example. For this example, I will use Nault (but you can use any Nano Software Wallet you like). Input the below seed into that software wallet and create five Nano Accounts. You will find that the accounts are created in the exact same order as my screenshot below.
I think it goes without saying … but don’t actually use any of these accounts. Anyone on the Internet has access to any funds that are in these accounts (because anyone on the Internet has access to the seed).
A Nano Account comprises three pieces of data:
- Private Key
- Public Key
Know that these three pieces of data are actually related. From a Nano Wallet’s seed, a Private Key is derived. From a Private Key a Public Key is derived. And from a Public Key, yup… an Address is derived. You can see this in action over at nanoo.tools.
In this “Getting Started” series of articles, we aren’t going to focus much on the Private or the Public Key. Just know that, similar to a Nano Wallet’s seed, anyone with access to a Nano Account’s Private Key has full control over the Nano Account.
However, let’s spend some time looking at the address…
The address of an account is what you share if you want someone or something to send you Nano. It has a prefix of nano_* or xrb_*. These prefixes are interchangeable and the difference is merely cosmetic. xrb_* is from the RaiBlocks days and is legacy, but still supported by the Nano Foundation’s Nano Node.
It is safe to share your address with anyone. However, anyone with your address can view your balance and history of transactions through a block explorer like NanoCrawler.
Additionally, addresses can be represented as scannable QR Code or deep links.
Units of Nano
This part can be a little confusing, so bear with me and I’ll try to explain clearly.
To lay it all out, here is the reference from the Nano Foundation.
As a “Getting Started” developer, let me direct your attention to two different units, the ones with words in the “Name” column. When you hear someone talk about Nano’s price or how it trades on an exchange, you are hearing them reference “Nano” with an SI prefix of Mnano (10³⁰).
When you deal programmatically with building Nano Blocks, you are working in “raw” units (10⁰).
If you are searching the Internet you might see some references to the unit with an SI prefix of nano (10²⁴). But it is rare. And I have never seen any references to any of the other units.
In short, a “raw” is the smallest possible division of Nano. And yes, it is possible to send someone 1 raw on the Nano Network. When interacting with a Nano Node, the unit of measurement is a raw.
Check out the nanoo.tools/unit-converter for some hands-on play
Ok, so now that we understand the Nano Network which is made up of Nano Nodes. And we understand that it is a Software Wallet that communicate with Nano Nodes using information determined from a Nano Wallet and its derived Nano Accounts … we are building a solid foundation! However, none of what I just said is very interesting if there is no activity on the network. This activity is in the form of Nano Blocks.
A Nano Block is single packet of information that represents the state of a Nano Account. Every Nano Account has its own block chain (this is called a Block Lattice). The most recent block (frontier block) in the chain contains the current state of that account. As of January 2021, the Nano Foundation’s Nano Node is designed to maintain the complete block chain for all Nano Accounts. However, there are efforts underway to enable “pruning”, so that minimal Nano Blocks would need to be stored by Nano Nodes.
The structure of a Nano Block is as follows:
Here’s a quick description of each field:
- block hash: Not labeled above, but the first identifier of this structure is called a block hash and is the first hexadecimal string that begins in “8743…”. Every Nano Block has a unique block hash.
- type: The type of block, however, “state” is currently the only type of block.
- account: The Nano Account for which the block is created.
- previous: The block hash of the previous Nano Block on the Nano Account’s block chain (will be “0” for first block). This Nano Block (that is identified by the “block hash”), replaces the previous Nano Block (that is identified by the “previous” field) as the frontier block.
- representative: The Nano Account that the Nano Account will use as its representative, to which it delegates its voting weight.
- balance: Current balance of the Nano Account once the block is confirmed across the Nano Network. It is formatted in “raw” units.
- link: In a receive Nano Block, will be the hash of the corresponding send block; in a send Nano Block, will be the Nano Account to which the the amount is being sent.
- link_as_account: Same as the link, except referenced in address format (which is derived from the Public Key).
- signature: A signature to validate the integrity of the Nano Block
- work: The result of a small proof-of-work algorithm that performs the function of spam avoidance
We will dig into more examples and create our own Nano Blocks in the follow-on articles. For this article, as a developer, know that Nano Blocks are the medium on which the Nano Network is written. A Nano Block is created and processed/disseminated by a Nano Node throughout the Nano Network for confirmation and consensus from all the Principal Representatives.
The last item I’ll mention on Nano Blocks (for now) is the fact that there are four different “subtypes” of Nano Blocks of type “state”. Remember how I said the “type” field only has a value of “state”? Well depending on the contents of the block, one can determine the purpose of that Nano Block and a “subtype” can be assigned. In fact, the Nano Foundation’s Nano Node will accept a subtype as an input as a way to validate your inputs. If you are attempting to receive Nano but your balance decreases, the Nano Node can reject the block. As a Nano Block, on its own, has no context for whether it is a “send” or “receive”, and only deals in straight account balance, this subtype validation is a way to protect you from yourself.
The four subtypes of a Nano Block are:
The epoch is beyond the scope of these articles and is typically used to implement a change to how the Nano Network operates.
Receive and Send
The receive and send subtypes are fairly straightforward. If I send you Nano, you must receive it for the Nano to be added to your Nano Account. Only you can make changes to your Nano Account by signing blocks. So when I send you Nano, I create and sign one block decreasing the balance of my Nano Account. And when you receive the Nano, you create and sign your own block (referencing my block) increasing the balance of your Nano Account.
Since each Nano Account’s block chain grows independently of any other Nano Account, after I create a send Nano Block and decrease the value of my account, there is no requirement that I wait for you to receive it before I create another (send, receive, or change) Nano Block. And on the receive side, there is no requirement that you ever create a receive Nano Block. If the value of the Nano I send you is too small to be worth your time to process it (spam), you may choose to ignore that block indefinitely and carry on with whatever other Nano Blocks you want your Nano Account to create.
And finally, the change subtype is a Nano Block that simply changes the representative to which you are delegating your voting weight (which corresponds to your balance). I will go over creating a change Nano Block in the next article, however, that is the depth that we will go. If you want to learn more about what accounts are Principal Representatives, check out Principal Representatives page on mynano.ninja.
Thanks for reading and I hope you found this article useful as you begin developing with Nano. It really is a phenomenal technology and a lot of fun to dig into and build with.
I have linked many references throughout this article and I hope you do decide to dig deeper. I also hope you continue with this series of articles.
- Build your foundation [this article]
- Interacting with Public and Private Nodes
- Interacting with Programmable Software Wallets [not yet published]
While you are here on Medium, I recommend you also read articles from Nano Education and Nano. If you are on Twitter, feel free to follow me @SomeNanoTweets. If you are on reddit, Nano has a phenomenal subreddit with a huge amount of helpful and highly intelligent people. And if you are more of a real-time chat sort of person, check on the Nano discord where there is a specific dev channel to help aspiring Nano “BUIDLers” like you and me.
Ps, these articles are a lot of fun to write but they take A LOT of time. I wrote it to support Nano Community developers. And I would be highly appreciative if you also consider supporting me in return. If you found this article useful, please consider sending a donation.