nano - Tcl bindings for Nano
nano::
address::
toPublicKey address ?
-hex|
-binary?
?
-verify|
-no-verify?
fromPublicKey pubKey ?
-xrb|
-nano?
fromPrivateKey privateKey ?
-xrb|
-nano?
key::
newSeed ?
-hex|
-binary?
newKey ?
-hex|
-binary?
fromSeed seed ?
index? ?
-hex|
-binary?
publicKeyFromPrivateKey privateKey ?
-hex|
-binary?
block::
json::toBlock blockJSON
json::fromDict blockDict
json::fromBlock blockData ?
-xrb|
-nano? ?
-type=blockType ? ?
-signKey=privateKey ?
json::sign blockJSON privateKey
?
-update|
-signature ?
-hex|
binary??
json::verifySignature blockJSON
json::work blockJSON ?
-update|
-work
?
-hex|
-binary??
json::validateWork blockJSON
json::filter blockJSON
dict::toBlock blockDict
dict::fromJSON blockJSON
dict::fromBlock blockData ?
-xrb|
-nano? ?
-type=blockType ? ?
-signKey=privateKey ?
dict::sign blockDict privateKey
?
-update|
-signature ?
-hex|
binary??
dict::verifySignature blockDict
dict::work blockDict ?
-update|
-work
?
-hex|
-binary??
dict::validateWork blockDict
hash blockData ?
-hex|
-binary?
signBlockHash blockHash privateKey
?
-hex|
-binary?
sign blockData privateKey ?
-hex|
-binary?
verifyBlockHash blockHash signature publicKey
verify blockData signature publicKey
create::send args
create::receive args
create::setRepresentative args
work::
fromWorkData blockHashOrPublicKey ?
-hex|
-binary?
fromBlock blockData
validate workData work
account::
setFrontier account frontierHash balance
representative
getFrontier account
getFrontier account
?
frontierHash|
balance|
representative?
addPending account blockHash amount
getPending account ?
blockHash?
clearPending account ?
blockHash?
receive account blockHash privateKey
receiveAllPending account privateKey
send fromAccount toAccount amount privateKey
setRepresentative account representative privateKey
Nano is a low-latency payment platform that requires minimal resources,
relying on a peer-to-peer network to distribute "blocks", which are
cryptographically signed transactions. This package provides bindings for
interacting with the Nano network from
Tcl.
Nano uses Ed25519 with Blake2b as the cryptographic hashing primitive for
digital signatures, rather than the common construction of Ed25519 with the
SHA2-512 cryptographic hashing function.
Nano implements a "blockchain", which is a cryptographic linked-list,
by identifying every "block" by its cryptographic hash and providing
a pointer from every block to its predecessor in the "chain" as part
of the hashed data.
This predecessors is referred to here as the "previous" block. In
Nano, each account has its own blockchain and they reference each other using
a data structure referred to as "block lattice", where the
individual chains contain blocks that reference blocks in other chains to tie
them together. The field within blocks that reference other blocks on a
different blockchain is referred to as either the "link" field or
"source block hash".
Each Nano block also encapsulates the full state of the account, containing, at
a minimum, a tuple of (
account,
balance,
representative,
previous).
Since Nano blocks are signed by independent actors, who may, for their own gain,
generate multiple valid blocks referring to the same predecessor
(
previous) block, an arbitration mechanism is employed by the Nano
network to decide which blocks are valid within a given chain. This
arbitration mechanism operates on the principles of consensus. Each account
holder has a stake in the network operating nominally, otherwise the balance
represented by an account is not useful for a transfer of value. In Nano the
stake an account has in the network is equal to the account's balance. The
larger the stake an account has the more incentivized the account-holder is to
ensure the network is operating nominally and not accepting multiple blocks
that reference the same predecessor.
Nano utilizes a mechanism called
voting to determine which blocks are
valid and which blocks are not valid. Each stakeholder votes their stake upon
seeing a new subordinate block (
i.e., a block with a unique
previous value). Since voting is an active and on-going process that
occurs on the Nano peer-to-peer network, participants must be online to vote
their stake. As this is often inconvenient or impossible, stakeholders may
select another stakeholder to vote their share of the network. This delegate
is referred to as a
representative.
Representatives should be chosen carefully by stakeholders since malicious
representatives may attempt to gather voting power and destabilize the Nano
network by altering decisions made by consensus previously.
Nano accounts are referred to by address. A Nano address starts with the prefix
"
nano_" or "
xrb_". A Nano address is
actually the public portion of a private/public keypair, plus the prefix, and
a checksum to ensure that no digits are mistyped by users when communicating
them. Nano public keys are 256-bit keys in the Ed25519 algorithm.
A user may have many accounts. To simplify the process of maintaining the
private/public keypairs for all the accounts, Nano supports the concept of a
wallet. A
wallet is a conceptual entity that is used to refer to
a
seed, which is a random 256-bit number that can be used to derive
multiple private/public keypairs from.
Balances in Nano are stored in a 128-bit integer value. There are various units
for representing the balance, the smallest and base unit is called
"
raw". The most common unit for users to use is called
"
Nano", one of which is equal to 1e30 raw.
Nano addresses are composed of a prefix (either "
nano_" or
"
xrb_") and 300 bits of base32 encoded data. The 300-bits of
base32 encoded data produce a string that is 6 characters long using the
base32 alphabet
13456789abcdefghijkmnopqrstuwxyz. The format of these
300 bits are
struct {
uint4_t padding = 0000b;
uint256_t publicKey;
uint40_t checksum;
}
The checksum is computed as a 5 byte (40 bit) Blake2b hash of the 256-bit public
key (in binary format), followed by reversing the bytes.
For example the public key
DC1512154EB72112B8CC230D7B8C7DD467DA78E4763182D6CAFAADB14855A5E8 which
has a 5-byte Blake2b hash of
{0x18, 0x74, 0xA3, 0x46, 0x9C} would be
encoded as
0000.DC1512154EB72112B8CC230D7B8C7DD467DA78E4763182D6CAFAADB14855A5E8.9C46A37418
which when encoded in base32 and the prefix added produces the address
nano_3q1o4acnxfs34cwerarfhg89uo59ubwgaxjjiddeoyofp767dbhamj5c8x1r.
The Nano network consists of two different peer-to-peer networks. One for
real-time block updates over UDP, and another for bulk ledger updates over TCP
(
bootstrapping). The real-time network is a broadcast style network
where every message sent over it are relayed to all other nodes.
The customary and default port for the real-time/UDP network is 7075/udp, while
the default port for the bootstrapping/TCP network is 7075/tcp.
The format of the messages on both networks is the same, however not every type
of message may be used on either network. The
keepalive message type is
invalid on the TCP (bootstrapping) network and the
bulk_pull message
type is invalid on the UDP (real-time) network. The format of message are an 8
byte header consisting of:
struct {
uint8_t magicProtocol = 0x52;
uint8_t magicNetwork = 0x41/0x42/0x43;
uint8_t versionMax;
uint8_t version;
uint8_t versionMin;
uint8_t messageType;
uint16_t extensions;
};
Where the
magicProtocol field must be the value
0x52 (which is
ASCII 'R') and the
magicNetwork field must be one of
0x41,
0x42, or
0x43 corresponding to one of the three Nano networks. A
value of
0x41 (ASCII 'A') represents the Test network; A value of
0x42 (ASCII 'B') represents the Beta network; A value of
0x43
(ASCII 'C') represents the Main network.
The various version fields control the relaying of the message to nodes running
various versions of the Nano network protocol (distinct from the Nano
reference implementation version). The
versionMax and
versionMin
fields indicate the inclusive range of acceptable versions to relay or
broadcast this message to. The
version field indicates what version of
the Nano protocol this node is using.
The messageType field indicates what type of message is being relayed, and must
conform to the following enumeration
| messageType |
Name |
On Bootstrap |
On Realtime |
Version |
| 0x00 |
Invalid |
Yes |
Yes |
0+ |
| 0x01 |
Not_A_Type |
? |
? |
0+ |
| 0x02 |
Keepalive |
No |
Yes |
0+ |
| 0x03 |
Publish |
No |
Yes |
0+ |
| 0x04 |
Confirm_Req |
No |
Yes |
0+ |
| 0x05 |
Confirm_Ack |
No |
Yes |
0+ |
| 0x06 |
Bulk_Pull |
Yes |
No |
? |
| 0x07 |
Bulk_Push |
Yes |
No |
? |
| 0x08 |
Frontier_Req |
Yes |
No |
? |
| 0x09 |
Bulk_Pull_Blocks |
Yes |
No |
11+ |
| 0x0A |
Node_ID_Handshake |
Yes |
No |
12+ |
| 0x0B |
Bulk_Pull_Account |
Yes |
No |
12+ |
TODO: Extensions
Following the message header comes the payload for the particular message type.
- Invalid
- TODOC
- Not_A_Type
- TODOC
- Keepalive
- The Keepalive message serves as an introduction and beaconing mechanism
for the Nano real-time network. The Keepalive message requires exactly 8
IPv6 address and port number tuples to be sent as its payload. The IPv6
addresses are each 128-bits (16-bytes) long and the port numbers are
16-bit integers sent in little endian byte order. The payload for the
Keepalive message type is 144 bytes in size.
- Publish
- TODOC
- Confirm_Req
- TODOC
- Confirm_Ack
- TODOC
- Bulk_Pull
- The Bulk_Pull message is used to pull the entire chain for an account,
down to its beginning or to a given block. It takes 2 arguments, both of
them 256-bit. The first argument is the account, so its 256-bit public key
should be encoded as binary in big-endian notation. The second argument is
the block hash to stop sending at, or 256 bits of 0s to indicate that the
entire chain should be sent. The payload for Bulk_Pull messages is 64
bytes in size.
The response from a Bulk_Pull request will be a stream of tuples, each
containing a 256-bit block hash, and a block message. TODOC: Format
- Bulk_Push
- TODOC
- Frontier_Req
- The Frontier_Req message is used to pull a list of accounts from a remote
node for the purpose of bootstrapping. It requires 3 arguments: The
256-bit public key of an account to start with, a 32-bit integer denoting
the age of accounts to return, and a 32-bit integer denoting the number of
records to return. If the age parameter is 0xffffffff then
all records are returned, regardless of age. If the count parameter
is 0xffffffff then all records are returned and no limit is
imposed.
The response from a Frontier_Req is a 256-bit public key, and the 256-bit
block hash that corresponds to the frontier (most recent block) for that
account's blockchain from the node where the response was generated.
- Bulk_Pull_Blocks
- TODOC
- Node_ID_Handshake
- TODOC
- Bulk_Pull_Account
- TODOC
- ::nano::address::toPublicKey
- address ?-hex|-binary?
?-verify|-no-verify? -> publicKey
Converts a Nano address to a public key. The -hex option indicates
that the public key should be returned in hexadecimal form. The
-binary option indicates that the public key should be returned in
binary form. The -verify option verifies the checksum embedded in
the Nano address before returning. The -no-verify option inhibits
verifying the checksum embedded in the Nano address.
- ::nano::address::fromPublicKey
- pubKey ?-xrb|-nano? -> address
Converts a public key to a Nano address. The -xrb option specifies
that the returned address should be prefixed with the old-style
"xrb_" prefix, where the -nano option specifies that the
returned address should be prefixed with the new-style "nano_"
prefix.
- ::nano::address::fromPrivateKey
- privateKey ?-xrb|-nano? -> address
Converts a private key to a Nano address. It accepts the same arguments as
fromPublicKey.
- ::nano::key::newSeed
- ?-hex|-binary? -> seed
Generates a new seed. A seed is a 256-bit bit-field which, along with a
32-bit index, is used to derive enumerated keys from a single point of
entropy. See the fromSeed procedure. The -hex and
-binary options determine the formatting of the result.
- ::nano::key::newKey
- ?-hex|-binary? -> privateKey
Generates a new private key. A private key can be used to sign transactions,
which can then be verified with its corresponding public key (see
publicKeyFromPrivateKey). This procedure is normally not used, but
rather private keys are derived from a seed and index pair
using the fromSeed procedure. The -hex and -binary
options determine the formatting of the result.
- ::nano::key::fromSeed
- seed ?index? ?-hex|-binary? ->
privateKey
Derive a private key from the seed specified as seed and the
index indicated. This procedure is deterministic (i.e., the same
seed and index will always give you the same private key).
This procedure is used to derive many keypairs from a single user-managed
piece of data, so the user does not have to manage multiple private keys.
If the index is not specified it defaults to 0. The
-hex and -binary options determine the formatting of the
result.
- ::nano::key::publicKeyFromPrivateKey
- privateKey ?-hex|-binary? -> publicKey
Converts a private key into its corresponding public key. Normally Ed25519
private keys are a concatenation of the private and public keys, however
in this package they are each treated separately. The -hex and
-binary options determine the formatting of the result.
- ::nano::block::representation::toBlock
- blockRepresentation -> blockData
Converts from one of the internal representations (either Tcl dictionary or
JSON) to a Nano block. The representation portion of the command
name may be one of dict or json.
- ::nano::block::json::fromDict
- blockDict -> blockJSON
Converts from a Tcl dictionary representation to a JSON representation of a
block.
- ::nano::block::json::filter
- blockJSON -> blockJSON
Filters out JSON object attributes which are not suitable for using with
other implementations, such as _comment, _workData, and
_blockHash.
- ::nano::block::dict::fromJSON
- blockJSON -> blockDict
Converts from a JSON object representation to a Tcl dictionary
representation of a block.
- ::nano::block::representation::fromBlock
- blockData ?-xrb|-nano? ?
-type=blockType ? ? -signKey=privateKey ?
-> blockRepresentation
Parses a Nano block and returns either a Tcl dictionary or a JSON object.
The -xrb option causes all parsed addresses to be prefixed with the
old-style "xrb_" address prefix, while the -nano option
causes them to be prefixed with the new-style "nano_prefix". The
representation portion of the command name may be one of
dict or json.
- ::nano::block::representation::sign
- blockRepresentation privateKey
?-update|-signature ?-hex|binary?? ->
signature|blockJSON
Sign a block, in either Tcl dictionary or JSON representation, with the
specified privateKey. If the -update option is used, return
the object with the updated attribute. If the -signature option is
used, return just the signature. The -hex and -binary
options determine the formatting of the result. The representation
portion of the command name may be one of dict or json.
- ::nano::block::representation::verifySignature
- blockRepresentation -> boolean
Verify the signature on a block, in either Tcl dictionary or JSON
representation, matches the public key specified in the account
attribute of that object. This may not work correctly for old-style blocks
unless you manually add the account attribute. The
representation portion of the command name may be one of
dict or json.
- ::nano::block::representation::work
- blockRepresentation ?-update|-work
?-hex|binary?? -> work|blockRepresentation
Generate proof-of-work (PoW) required to submit a given block to the
network. Nano uses PoW to increase the cost of submitting blocks to the
network to cut down on spam. The work that is computed is based on
the hash of the previous block on this chain, or if there is no previous
block on this chain (i.e., because it is the first block on an account)
the public key of the account. If the -update option is used,
return the object with the updated attribute. If the -work option
is used, just return the work. The -hex and -binary options
determine the formatting of the result. The representation portion
of the command name may be one of dict or json.
- ::nano::block::representation::validateWork
- blockRepresentation -> boolean
Validate the proof-of-work (PoW) in the object specified as
blockRepresentation with the attribute work is valid for the
block passed in. The representation portion of the command name may
be one of dict or json.
- ::nano::block::hash
- blockData ?-hex|-binary? -> blockHash
Compute the cryptographic hash of a block. The cryptographic hashing
algorithm used for Nano is Blake2b. Blocks are typically identified by
their hash (i.e., content addressable). The -hex and -binary
options determine the formatting of the result.
- ::nano::block::signBlockHash
- blockHash privateKey ?-hex|-binary? ->
signature
Compute an Ed25519-with-Blake2b signature of a given block hash specified as
blockHash with the private key specified as privateKey. In
Nano, signed blocks are signed by signing the block's hash thus all that
is needed to sign a block is its hash and the private key that corresponds
to the account. NOTE: Ensure that the privateKey
specified matches the account the block belongs to. The -hex
and -binary options determine the formatting of the result.
- ::nano::block::sign
- blockData privateKey ?-hex|-binary? ->
signature
This is a convenience procedure which computes the hash of a block given as
blockData, and then calls signBlockHash. The -hex and
-binary options determine the formatting of the result.
- ::nano::block::verifyBlockHash
- blockHash signature publicKey -> boolean
Verify that a block hash (blockHash) was signed (signature) by
an account holding the private key that corresponds to the public key
specified as publicKey.
- ::nano::block::verify
- blockData signature publicKey -> boolean
This is a convenience procedure which computes the hash of a block given as
blockData, and then calls verifyBlockHash.
- ::nano::block::create::send
- from address to address previous
blockHash representative address
previousBalance integer amount integer ?
-json boolean ? -> blockJSON|blockDict
This is a low-level interface for creating blocks which correspond to
sending Nano from one account to another. It constructs a block which
sends the amount specified from the from address to the
destination (to). The previous block's hash must be specified as
the blockHash following previous. Additionally the balance
of the account at the previous block must be supplied as the integer
argument to previousBalance. All balance amounts are in units of
raw. If the optional -json argument is used and specified as
true the result is a JSON representation, otherwise a Tcl dict
representation is used.
- ::nano::block::create::receive
- to address sourceBlock blockHash previous
blockHash representative address
previousBalance integer amount integer ?
-json boolean ? -> blockJSON|blockDict
This is a low-level interface for creating blocks which correspond to
receiving (pocketing) Nano previously sent from another account to the
account specified as the address supplied to the to
argument. It constructs a block which receives the amount of Nano
specified as the amount argument. The block hash (blockHash)
of the send block which was used to send the Nano to this account must be
specified as the argument to the sourceBlock option. The previous
block's hash must be specified as the blockHash following
previous. Additionally the balance of the account at the previous
block must be supplied as the integer argument to previousBalance.
All balance amounts are in units of raw. If the optional
-json argument is used and specified as true the result is a JSON
representation, otherwise a Tcl dict representation is used.
- ::nano::block::create::setRepresentative
- account address previous blockHash
representative address ? -json boolean ? ->
blockJSON|blockDict
This is a low-level interface for creating blocks which correspond to an
explicit change of representative. Representatives in Nano are used as
part of the Delegated Proof-of-Stake (dPoS) consensus mechanism which is
used by the Nano network to determine which block (if any) out of many
possible subordinate blocks in a chain are valid. So that every account
holder does not have to be online to vote for valid transactions, an
account may delegate another account to vote its stake on its behalf. That
delegate is called a representative. An account may change its
representative at any time by issuing a block with a new representative,
such as a send or receive block, or by issuing an explicit change of
representative block. This procedure creates an explicit change of
representative block for the account specified. It changes to the
delegate to the representative specified. Further, the
blockHash of the previous block must be specified as the argument
to previous. If the optional -json argument is used and
specified as true the result is a JSON representation, otherwise a Tcl
dict representation is used.
- ::nano::work::fromWorkData
- blockHashOrPublicKey ?-hex|-binary? -> work
Create proof-of-work (PoW) from a block hash or public key. Which one is
used depends on whether or not there are any other blocks in this
account's chain. If this is the first block in this account's chain then
the public key of the account is used, otherwise the hash of the blocks
predecessor (previous) is used. The specific value needed should be
accessible from the _workData member of a JSON object or Tcl
dictionary. Note that this attribute (and all attributes that begin with
an underscore) should be discarded when sending the block outside of the
Tcl process. The -hex and -binary options determine the
formatting of the result.
- ::nano::work::fromBlock
- blockData -> work
This is a convenience procedure which computes work data (either a block
hash or a public key) for a given block and then calls
fromWorkData.
- ::nano::work::validate
- workData work -> boolean
This procedure validates that the supplied work is valid for the
supplied workData, which is either a block hash or an account
public key. For more information see the description of
fromWorkData.
- :nano::account::setFrontier
- account frontierHash balance representative
This procedure is used as part of the High-level Account interface. It sets
the frontier, which is the block hash (frontierHash) and
data (balance, representative) associated with that block
that corresponds to the head of an account's chain.
- :nano::account::getFrontier
- account -> frontierInfo
This procedure is used as part of the High-level Account interface. It gets
the Tcl dictionary associated with the frontier most recently set for the
specified account.
- :nano::account::getFrontier
- account ?frontierHash|balance|representative?
-> frontierHash|balance|representative
This procedure is used as part of the High-level Account interface. It gets
a specific item from Tcl dictionary associated with the frontier most
recently set for the specified account.
- :nano::account::addPending
- account blockHash amount
This procedure is used as part of the High-level Account interface. It is
used to indicate than a given account has a receive block
that they could create. The block hash of the corresponding send
block should be supplied as the blockHash parameter. The amount of
Nano that was sent in the send block should be specified as the
amount parameter (in units of raw).
- :nano::account::getPending
- account ?blockHash? -> dict
This procedure is used as part of the High-level Account interface. It is
used to retrieve information stored by addPending for a given
account. If the blockHash parameter is supplied then a Tcl
dictionary is returned with a key called amount which contains the
amount stored previously. If the blockHash parameter is not
supplied then a Tcl dictionary is returned with keys corresponding to each
block hash pending for the specified account, and containing a
subordinate Tcl dictionary with a key called amount as previously
described.
- ::nano::account::clearPending
- account ?blockHash?
This procedure is used as part of the High-level Account interface. It is
used to clear (that is, remove from the conceptual state of
"pending") entries created previously with addPending for
a given account. If the blockHash parameter is supplied then
only the entry corresponding to that blockhash is cleared, otherwise all
entries for the specified account are cleared.
- :nano::account::receive
- account blockHash privateKey ->
blockJSON|blockDict
This procedure is used as part of the High-level Account interface. It is
used to generate a receive block. Its interface is subject to change and
not considered stable.
- :nano::account::receiveAllPending
- account privateKey ->
listOfBlockJSON|listOfBlockDict
This procedure is used as part of the High-level Account interface. It is
used to generate receive blocks for every pending receive on a given
account. Its interface is subject to change and not considered
stable.
- :nano::account::send
- fromAccount toAccount amount privateKey ->
blockJSON|blockDict
This procedure is used as part of the High-level Account interface. It is
used to generate a send block. Its interface is subject to change and not
considered stable.
- ::nano::account::setRepresentative
- account representative privateKey ->
blockJSON|blockDict
This procedure is used as part of the High-level Account interface. It is
used to generate a block that changes the representative for the given
account. Its interface is subject to change and not considered
stable.
package require nano 1.1
set seed [::nano::key::newSeed -hex]
puts "Generated seed: $seed"
for {set index 0} {$index < 10} {incr index} {
set accountPrivateKey [::nano::key::fromSeed $seed $index -hex]
set accountAddress [::nano::address::fromPrivateKey $accountPrivateKey]
puts " - $index: $accountAddress"
}
Roy Keene <
rkeene@nano.org>
Z 6c726b8b80081e2c75de3f7b982fcd30