Posted to tcl by stu at Tue Jul 17 14:38:48 GMT 2018view raw
- <!DOCTYPE html>
- <html>
- <head>
- <meta charset="utf-8"/>
- <style>
- table.head, table.foot { width: 100%; }
- td.head-rtitle, td.foot-os { text-align: right; }
- td.head-vol { text-align: center; }
- div.Pp { margin: 1ex 0ex; }
- div.Nd, div.Bf, div.Op { display: inline; }
- span.Pa, span.Ad { font-style: italic; }
- span.Ms { font-weight: bold; }
- dl.Bl-diag > dt { font-weight: bold; }
- code.Nm, code.Fl, code.Cm, code.Ic, code.In, code.Fd, code.Fn,
- code.Cd { font-weight: bold; font-family: inherit; }
- </style>
- <title>NANO(N)</title>
- </head>
- <body>
- <table class="head">
- <tr>
- <td class="head-ltitle">NANO(N)</td>
- <td class="head-vol"></td>
- <td class="head-rtitle">NANO(N)</td>
- </tr>
- </table>
- <div class="manual-text">
- <h1 class="Sh" title="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
- nano - Tcl bindings for Nano
- <h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
- <b>nano::</b>
- <br/>
- <b>address::</b>
- <br/>
- <b>toPublicKey</b> <i>address</i> ?<b>-hex</b>|<b>-binary</b>?
- ?<b>-verify</b>|<b>-no-verify</b>?
- <div> </div>
- <b>fromPublicKey</b> <i>pubKey</i> ?<b>-xrb</b>|<b>-nano</b>?
- <div> </div>
- <b>fromPrivateKey</b> <i>privateKey</i> ?<b>-xrb</b>|<b>-nano</b>?
- <div class="Pp"></div>
- <br/>
- <b>key::</b>
- <br/>
- <b>newSeed</b> ?<b>-hex</b>|<b>-binary</b>?
- <div> </div>
- <b>newKey</b> ?<b>-hex</b>|<b>-binary</b>?
- <div> </div>
- <b>fromSeed</b> <i>seed</i> ?<i>index</i>? ?<b>-hex</b>|<b>-binary</b>?
- <div> </div>
- <b>publicKeyFromPrivateKey</b> <i>privateKey</i> ?<b>-hex</b>|<b>-binary</b>?
- <div class="Pp"></div>
- <br/>
- <b>block::</b>
- <br/>
- <b>json::toBlock</b> <i>blockJSON</i>
- <div> </div>
- <b>json::fromDict</b> <i>blockDict</i>
- <div> </div>
- <b>json::fromBlock</b> <i>blockData</i> ?<b>-xrb</b>|<b>-nano</b>? ?
- <b>-type=</b><i>blockType</i> ? ? <b>-signKey=</b><i>privateKey</i> ?
- <div> </div>
- <b>json::sign</b> <i>blockJSON</i> <i>privateKey</i>
- ?<b>-update</b>|<b>-signature</b> ?<b>-hex</b>|<b>binary</b>??
- <div> </div>
- <b>json::verifySignature</b> <i>blockJSON</i>
- <div> </div>
- <b>json::work</b> <i>blockJSON</i> ?<b>-update</b>|<b>-work</b>
- ?<b>-hex</b>|<b>-binary</b>??
- <div> </div>
- <b>json::validateWork</b> <i>blockJSON</i>
- <div> </div>
- <b>json::filter</b> <i>blockJSON</i>
- <div class="Pp"></div>
- <b>dict::toBlock</b> <i>blockDict</i>
- <div> </div>
- <b>dict::fromJSON</b> <i>blockJSON</i>
- <div> </div>
- <b>dict::fromBlock</b> <i>blockData</i> ?<b>-xrb</b>|<b>-nano</b>? ?
- <b>-type=</b><i>blockType</i> ? ? <b>-signKey=</b><i>privateKey</i> ?
- <div> </div>
- <b>dict::sign</b> <i>blockDict</i> <i>privateKey</i>
- ?<b>-update</b>|<b>-signature</b> ?<b>-hex</b>|<b>binary</b>??
- <div> </div>
- <b>dict::verifySignature</b> <i>blockDict</i>
- <div> </div>
- <b>dict::work</b> <i>blockDict</i> ?<b>-update</b>|<b>-work</b>
- ?<b>-hex</b>|<b>-binary</b>??
- <div> </div>
- <b>dict::validateWork</b> <i>blockDict</i>
- <div class="Pp"></div>
- <b>hash</b> <i>blockData</i> ?<b>-hex</b>|<b>-binary</b>?
- <div> </div>
- <b>signBlockHash</b> <i>blockHash</i> <i>privateKey</i>
- ?<b>-hex</b>|<b>-binary</b>?
- <div> </div>
- <b>sign</b> <i>blockData</i> <i>privateKey</i> ?<b>-hex</b>|<b>-binary</b>?
- <div> </div>
- <b>verifyBlockHash</b> <i>blockHash</i> <i>signature</i> <i>publicKey</i>
- <div> </div>
- <b>verify</b> <i>blockData</i> <i>signature</i> <i>publicKey</i>
- <div class="Pp"></div>
- <b>create::send</b> <i>args</i>
- <div> </div>
- <b>create::receive</b> <i>args</i>
- <div> </div>
- <b>create::setRepresentative</b> <i>args</i>
- <div class="Pp"></div>
- <br/>
- <b>work::</b>
- <br/>
- <b>fromWorkData</b> <i>blockHashOrPublicKey</i> ?<b>-hex</b>|<b>-binary</b>?
- <div> </div>
- <b>fromBlock</b> <i>blockData</i>
- <div> </div>
- <b>validate</b> <i>workData</i> <i>work</i>
- <div class="Pp"></div>
- <br/>
- <b>account::</b>
- <br/>
- <b>setFrontier</b> <i>account</i> <i>frontierHash</i> <i>balance</i>
- <i>representative</i>
- <div> </div>
- <b>getFrontier</b> <i>account</i>
- <div> </div>
- <b>getFrontier</b> <i>account</i>
- ?<b>frontierHash</b>|<b>balance</b>|<b>representative</b>?
- <div> </div>
- <b>addPending</b> <i>account</i> <i>blockHash</i> <i>amount</i>
- <div> </div>
- <b>getPending</b> <i>account</i> ?<i>blockHash</i>?
- <div> </div>
- <b>clearPending</b> <i>account</i> ?<i>blockHash</i>?
- <div class="Pp"></div>
- <b>receive</b> <i>account</i> <i>blockHash</i> <i>privateKey</i>
- <div> </div>
- <b>receiveAllPending</b> <i>account</i> <i>privateKey</i>
- <div> </div>
- <b>send</b> <i>fromAccount</i> <i>toAccount</i> <i>amount</i> <i>privateKey</i>
- <div> </div>
- <b>setRepresentative</b> <i>account</i> <i>representative</i> <i>privateKey</i>
- <div class="Pp"></div>
- <br/>
- <br/>
- <div class="Pp"></div>
- <h1 class="Sh" title="Sh" id="INTRODUCTION"><a class="permalink" href="#INTRODUCTION">INTRODUCTION</a></h1>
- <i>Nano</i> 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 <i>Tcl</i>.
- <div class="Pp"></div>
- 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.
- <div class="Pp"></div>
- 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.
- <div class="Pp"></div>
- 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".
- <div class="Pp"></div>
- Each Nano block also encapsulates the full state of the account, containing, at
- a minimum, a tuple of (<i>account</i>, <i>balance</i>, <i>representative</i>,
- <i>previous</i>).
- <div class="Pp"></div>
- Since Nano blocks are signed by independent actors, who may, for their own gain,
- generate multiple valid blocks referring to the same predecessor
- (<i>previous</i>) 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.
- <div class="Pp"></div>
- Nano utilizes a mechanism called <i>voting</i> to determine which blocks are
- valid and which blocks are not valid. Each stakeholder votes their stake upon
- seeing a new subordinate block (<i>i.e.</i>, a block with a unique
- <i>previous</i> 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 <i>representative</i>.
- <div class="Pp"></div>
- 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.
- <div class="Pp"></div>
- Nano accounts are referred to by address. A Nano address starts with the prefix
- "<b>nano_</b>" or "<b>xrb_</b>". 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.
- <div class="Pp"></div>
- 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
- <i>wallet</i>. A <i>wallet</i> is a conceptual entity that is used to refer to
- a <i>seed</i>, which is a random 256-bit number that can be used to derive
- multiple private/public keypairs from.
- <div class="Pp"></div>
- 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
- "<i>raw</i>". The most common unit for users to use is called
- "<i>Nano</i>", one of which is equal to 1e30 raw.
- <div class="Pp"></div>
- <h2 class="Ss" title="Ss" id="Addresses"><a class="permalink" href="#Addresses">Addresses</a></h2>
- Nano addresses are composed of a prefix (either "<b>nano_</b>" or
- "<b>xrb_</b>") 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 <b>13456789abcdefghijkmnopqrstuwxyz</b>. The format of these
- 300 bits are
- <pre>
- <div class="Pp"></div>
- struct {
- uint4_t padding = 0000b;
- uint256_t publicKey;
- uint40_t checksum;
- }
- <div class="Pp"></div>
- </pre>
- 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.
- <div class="Pp"></div>
- For example the public key
- <b>DC1512154EB72112B8CC230D7B8C7DD467DA78E4763182D6CAFAADB14855A5E8</b> which
- has a 5-byte Blake2b hash of <b>{0x18, 0x74, 0xA3, 0x46, 0x9C}</b> would be
- encoded as
- <b>0000.DC1512154EB72112B8CC230D7B8C7DD467DA78E4763182D6CAFAADB14855A5E8.9C46A37418</b>
- which when encoded in base32 and the prefix added produces the address
- <b>nano_3q1o4acnxfs34cwerarfhg89uo59ubwgaxjjiddeoyofp767dbhamj5c8x1r</b>.
- <div class="Pp"></div>
- <h2 class="Ss" title="Ss" id="Network"><a class="permalink" href="#Network">Network</a></h2>
- 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
- (<i>bootstrapping</i>). The real-time network is a broadcast style network
- where every message sent over it are relayed to all other nodes.
- <div class="Pp"></div>
- 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.
- <div class="Pp"></div>
- The format of the messages on both networks is the same, however not every type
- of message may be used on either network. The <b>keepalive</b> message type is
- invalid on the TCP (bootstrapping) network and the <b>bulk_pull</b> message
- type is invalid on the UDP (real-time) network. The format of message are an 8
- byte header consisting of:
- <pre>
- <div class="Pp"></div>
- 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;
- };
- <div class="Pp"></div>
- </pre>
- Where the <b>magicProtocol</b> field must be the value <b>0x52</b> (which is
- ASCII 'R') and the <b>magicNetwork</b> field must be one of <b>0x41</b>,
- <b>0x42</b>, or <b>0x43</b> corresponding to one of the three Nano networks. A
- value of <b>0x41</b> (ASCII 'A') represents the Test network; A value of
- <b>0x42</b> (ASCII 'B') represents the Beta network; A value of <b>0x43</b>
- (ASCII 'C') represents the Main network.
- <div class="Pp"></div>
- 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 <b>versionMax</b> and <b>versionMin</b>
- fields indicate the inclusive range of acceptable versions to relay or
- broadcast this message to. The <b>version</b> field indicates what version of
- the Nano protocol this node is using.
- <div class="Pp"></div>
- The messageType field indicates what type of message is being relayed, and must
- conform to the following enumeration
- <table class="tbl">
- <tr>
- <td>messageType</td>
- <td>Name</td>
- <td>On Bootstrap</td>
- <td>On Realtime</td>
- </tr>
- <tr>
- <td>0x00</td>
- <td>Invalid</td>
- <td>Yes</td>
- <td>Yes</td>
- </tr>
- <tr>
- <td>0x01</td>
- <td>Not_A_Type</td>
- <td>?</td>
- <td>?</td>
- </tr>
- <tr>
- <td>0x02</td>
- <td>Keepalive</td>
- <td>No</td>
- <td>Yes</td>
- </tr>
- <tr>
- <td>0x03</td>
- <td>Publish</td>
- <td>No</td>
- <td>Yes</td>
- </tr>
- <tr>
- <td>0x04</td>
- <td>Confirm_Req</td>
- <td>No</td>
- <td>Yes</td>
- </tr>
- <tr>
- <td>0x05</td>
- <td>Confirm_Ack</td>
- <td>No</td>
- <td>Yes</td>
- </tr>
- <tr>
- <td>0x06</td>
- <td>Bulk_Pull</td>
- <td>Yes</td>
- <td>No</td>
- </tr>
- <tr>
- <td>0x07</td>
- <td>Bulk_Push</td>
- <td>Yes</td>
- <td>No</td>
- </tr>
- <tr>
- <td>0x08</td>
- <td>Frontier_Req</td>
- <td>Yes</td>
- <td>No</td>
- </tr>
- <tr>
- <td>0x09</td>
- <td>Bulk_Pull_Blocks</td>
- <td>Yes</td>
- <td>No</td>
- </tr>
- </table>
- <div class="Pp"></div>
- <b>TODO: Extensions</b>
- <div class="Pp"></div>
- Following the message header comes the payload for the particular message type.
- <div class="Pp"></div>
- <dl class="Bl-tag">
- <dt><b>Invalid</b></dt>
- <dd>TODOC
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>Not_A_Type</b></dt>
- <dd>TODOC
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>Keepalive</b></dt>
- <dd>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 network
- byte order. The payload for the Keepalive message type is 144 bytes in
- size.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>Publish</b></dt>
- <dd>TODOC
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>Confirm_Req</b></dt>
- <dd>TODOC
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>Confirm_Ack</b></dt>
- <dd>TODOC
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>Bulk_Pull</b></dt>
- <dd>TODOC
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>Bulk_Push</b></dt>
- <dd>TODOC
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>Frontier_Req</b></dt>
- <dd>TODOC
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>Bulk_Pull_Blocks</b></dt>
- <dd>TODOC
- <div class="Pp"></div>
- <div class="Pp"></div>
- </dd>
- </dl>
- <h1 class="Sh" title="Sh" id="PROCEDURES"><a class="permalink" href="#PROCEDURES">PROCEDURES</a></h1>
- <h2 class="Ss" title="Ss" id="Addresses_2"><a class="permalink" href="#Addresses_2">Addresses</a></h2>
- <dl class="Bl-tag">
- <dt><b>::nano::address::toPublicKey</b></dt>
- <dd><i>address</i> ?<b>-hex</b>|<b>-binary</b>?
- ?<b>-verify</b>|<b>-no-verify</b>? <b> -> </b><i>publicKey</i>
- <div class="Pp"></div>
- Converts a Nano address to a public key. The <b>-hex</b> option indicates
- that the public key should be returned in hexadecimal form. The
- <b>-binary</b> option indicates that the public key should be returned in
- binary form. The <b>-verify</b> option verifies the checksum embedded in
- the Nano address before returning. The <b>-no-verify</b> option inhibits
- verifying the checksum embedded in the Nano address.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>::nano::address::fromPublicKey</b></dt>
- <dd><i>pubKey</i> ?<b>-xrb</b>|<b>-nano</b>? <b> -> </b><i>address</i>
- <div class="Pp"></div>
- Converts a public key to a Nano address. The <b>-xrb</b> option specifies
- that the returned address should be prefixed with the old-style
- "xrb_" prefix, where the <b>-nano</b> option specifies that the
- returned address should be prefixed with the new-style "nano_"
- prefix.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>::nano::address::fromPrivateKey</b></dt>
- <dd><i>privateKey</i> ?<b>-xrb</b>|<b>-nano</b>? <b> -> </b><i>address</i>
- <div class="Pp"></div>
- Converts a private key to a Nano address. It accepts the same arguments as
- <b>fromPublicKey</b>.
- <div class="Pp"></div>
- </dd>
- </dl>
- <h2 class="Ss" title="Ss" id="Key_Management"><a class="permalink" href="#Key_Management">Key
- Management</a></h2>
- <dl class="Bl-tag">
- <dt><b>::nano::key::newSeed</b></dt>
- <dd>?<b>-hex</b>|<b>-binary</b>? -> <i>seed</i>
- <div class="Pp"></div>
- 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 <b>fromSeed</b> procedure. The <b>-hex</b> and
- <b>-binary</b> options determine the formatting of the result.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>::nano::key::newKey</b></dt>
- <dd>?<b>-hex</b>|<b>-binary</b>? -> <i>privateKey</i>
- <div class="Pp"></div>
- 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
- <b>publicKeyFromPrivateKey</b>). This procedure is normally not used, but
- rather private keys are derived from a <i>seed</i> and <i>index</i> pair
- using the <b>fromSeed</b> procedure. The <b>-hex</b> and <b>-binary</b>
- options determine the formatting of the result.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>::nano::key::fromSeed</b></dt>
- <dd><i>seed</i> ?<i>index</i>? ?<b>-hex</b>|<b>-binary</b>? ->
- <i>privateKey</i>
- <div class="Pp"></div>
- Derive a private key from the seed specified as <i>seed</i> and the
- <i>index</i> indicated. This procedure is deterministic (i.e., the same
- <i>seed</i> and <i>index</i> 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 <i>index</i> is not specified it defaults to <b>0</b>. The
- <b>-hex</b> and <b>-binary</b> options determine the formatting of the
- result.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>::nano::key::publicKeyFromPrivateKey</b></dt>
- <dd><i>privateKey</i> ?<b>-hex</b>|<b>-binary</b>? -> <i>publicKey</i>
- <div class="Pp"></div>
- 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 <b>-hex</b> and
- <b>-binary</b> options determine the formatting of the result.
- <div class="Pp"></div>
- </dd>
- </dl>
- <h2 class="Ss" title="Ss" id="Low-level_Block"><a class="permalink" href="#Low-level_Block">Low-level
- Block</a></h2>
- <dl class="Bl-tag">
- <dt><b>::nano::block::</b><i>representation</i><b>::toBlock</b></dt>
- <dd><i>blockRepresentation</i> -> <i>blockData</i>
- <div class="Pp"></div>
- Converts from one of the internal representations (either Tcl dictionary or
- JSON) to a Nano block. The <i>representation</i> portion of the command
- name may be one of <b>dict</b> or <b>json</b>.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>::nano::block::json::fromDict</b></dt>
- <dd><i>blockDict</i> -> <i>blockJSON</i>
- <div class="Pp"></div>
- Converts from a Tcl dictionary representation to a JSON representation of a
- block.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>::nano::block::json::filter</b></dt>
- <dd><i>blockJSON</i> -> <i>blockJSON</i>
- <div class="Pp"></div>
- Filters out JSON object attributes which are not suitable for using with
- other implementations, such as <i>_comment</i>, <i>_workData</i>, and
- <i>_blockHash</i>.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>::nano::block::dict::fromJSON</b></dt>
- <dd><i>blockJSON</i> -> <i>blockDict</i>
- <div class="Pp"></div>
- Converts from a JSON object representation to a Tcl dictionary
- representation of a block.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>::nano::block::</b><i>representation</i><b>::fromBlock</b></dt>
- <dd><i>blockData</i> ?<b>-xrb</b>|<b>-nano</b>? ?
- <b>-type=</b><i>blockType</i> ? ? <b>-signKey=</b><i>privateKey</i> ?
- -> <i>blockRepresentation</i>
- <div class="Pp"></div>
- Parses a Nano block and returns either a Tcl dictionary or a JSON object.
- The <b>-xrb</b> option causes all parsed addresses to be prefixed with the
- old-style "xrb_" address prefix, while the <b>-nano</b> option
- causes them to be prefixed with the new-style "nano_prefix". The
- <i>representation</i> portion of the command name may be one of
- <b>dict</b> or <b>json</b>.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>::nano::block::</b><i>representation</i><b>::sign</b></dt>
- <dd><i>blockRepresentation</i> <i>privateKey</i>
- ?<b>-update</b>|<b>-signature</b> ?<b>-hex</b>|<b>binary</b>?? ->
- <i>signature</i>|<i>blockJSON</i>
- <div class="Pp"></div>
- Sign a block, in either Tcl dictionary or JSON representation, with the
- specified <i>privateKey</i>. If the <b>-update</b> option is used, return
- the object with the updated attribute. If the <b>-signature</b> option is
- used, return just the signature. The <b>-hex</b> and <b>-binary</b>
- options determine the formatting of the result. The <i>representation</i>
- portion of the command name may be one of <b>dict</b> or <b>json</b>.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>::nano::block::</b><i>representation</i><b>::verifySignature</b></dt>
- <dd><i>blockRepresentation</i> -> <i>boolean</i>
- <div class="Pp"></div>
- Verify the signature on a block, in either Tcl dictionary or JSON
- representation, matches the public key specified in the <b>account</b>
- attribute of that object. This may not work correctly for old-style blocks
- unless you manually add the <b>account</b> attribute. The
- <i>representation</i> portion of the command name may be one of
- <b>dict</b> or <b>json</b>.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>::nano::block::</b><i>representation</i><b>::work</b></dt>
- <dd><i>blockRepresentation</i> ?<b>-update</b>|<b>-work</b>
- ?<b>-hex</b>|<b>binary</b>?? -> <i>work</i>|<i>blockRepresentation</i>
- <div class="Pp"></div>
- 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 <i>work</i> 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 <b>-update</b> option is used,
- return the object with the updated attribute. If the <b>-work</b> option
- is used, just return the work. The <b>-hex</b> and <b>-binary</b> options
- determine the formatting of the result. The <i>representation</i> portion
- of the command name may be one of <b>dict</b> or <b>json</b>.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>::nano::block::</b><i>representation</i><b>::validateWork</b></dt>
- <dd><i>blockRepresentation</i> -> <i>boolean</i>
- <div class="Pp"></div>
- Validate the proof-of-work (PoW) in the object specified as
- <i>blockRepresentation</i> with the attribute <b>work</b> is valid for the
- block passed in. The <i>representation</i> portion of the command name may
- be one of <b>dict</b> or <b>json</b>.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>::nano::block::hash</b></dt>
- <dd><i>blockData</i> ?<b>-hex</b>|<b>-binary</b>? -> <i>blockHash</i>
- <div class="Pp"></div>
- 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 <b>-hex</b> and <b>-binary</b>
- options determine the formatting of the result.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>::nano::block::signBlockHash</b></dt>
- <dd><i>blockHash</i> <i>privateKey</i> ?<b>-hex</b>|<b>-binary</b>? ->
- <i>signature</i>
- <div class="Pp"></div>
- Compute an Ed25519-with-Blake2b signature of a given block hash specified as
- <i>blockHash</i> with the private key specified as <i>privateKey</i>. 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. <b>NOTE: Ensure that the</b> <i>privateKey</i>
- <b>specified matches the account the block belongs to.</b> The <b>-hex</b>
- and <b>-binary</b> options determine the formatting of the result.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>::nano::block::sign</b></dt>
- <dd><i>blockData</i> <i>privateKey</i> ?<b>-hex</b>|<b>-binary</b>? ->
- <i>signature</i>
- <div class="Pp"></div>
- This is a convenience procedure which computes the hash of a block given as
- <i>blockData</i>, and then calls <b>signBlockHash</b>. The <b>-hex</b> and
- <b>-binary</b> options determine the formatting of the result.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>::nano::block::verifyBlockHash</b></dt>
- <dd><i>blockHash</i> <i>signature</i> <i>publicKey</i> -> <i>boolean</i>
- <div class="Pp"></div>
- Verify that a block hash (<i>blockHash</i>) was signed (<i>signature</i>) by
- an account holding the private key that corresponds to the public key
- specified as <i>publicKey</i>.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>::nano::block::verify</b></dt>
- <dd><i>blockData</i> <i>signature</i> <i>publicKey</i> -> <i>boolean</i>
- <div class="Pp"></div>
- This is a convenience procedure which computes the hash of a block given as
- <i>blockData</i>, and then calls <b>verifyBlockHash</b>.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>::nano::block::create::send</b></dt>
- <dd><b>from </b><i>address</i> <b>to </b><i>address</i> <b>previous
- </b><i>blockHash</i> <b>representative </b><i>address</i>
- <b>previousBalance </b><i>integer</i> <b>amount </b><i>integer</i> ?
- <b>-json </b><i>boolean</i> ? -> <i>blockJSON</i>|<i>blockDict</i>
- <div class="Pp"></div>
- 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 <b>amount</b> specified from the <b>from</b> address to the
- destination (<b>to</b>). The previous block's hash must be specified as
- the <i>blockHash</i> following <b>previous</b>. Additionally the balance
- of the account at the previous block must be supplied as the integer
- argument to <b>previousBalance</b>. All balance amounts are in units of
- <b>raw</b>. If the optional <b>-json</b> argument is used and specified as
- true the result is a JSON representation, otherwise a Tcl dict
- representation is used.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>::nano::block::create::receive</b></dt>
- <dd><b>to </b><i>address</i> <b>sourceBlock </b><i>blockHash</i> <b>previous
- </b><i>blockHash</i> <b>representative </b><i>address</i>
- <b>previousBalance </b><i>integer</i> <b>amount </b><i>integer</i> ?
- <b>-json </b><i>boolean</i> ? -> <i>blockJSON</i>|<i>blockDict</i>
- <div class="Pp"></div>
- 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 <i>address</i> supplied to the <b>to</b>
- argument. It constructs a block which receives the amount of Nano
- specified as the <b>amount</b> argument. The block hash (<i>blockHash</i>)
- of the send block which was used to send the Nano to this account must be
- specified as the argument to the <b>sourceBlock</b> option. The previous
- block's hash must be specified as the <i>blockHash</i> following
- <b>previous</b>. Additionally the balance of the account at the previous
- block must be supplied as the integer argument to <b>previousBalance</b>.
- All balance amounts are in units of <b>raw</b>. If the optional
- <b>-json</b> argument is used and specified as true the result is a JSON
- representation, otherwise a Tcl dict representation is used.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>::nano::block::create::setRepresentative</b></dt>
- <dd><b>account </b><i>address</i> <b>previous </b><i>blockHash</i>
- <b>representative </b><i>address</i> ? <b>-json </b><i>boolean</i> ? ->
- <i>blockJSON</i>|<i>blockDict</i>
- <div class="Pp"></div>
- 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 <b>account</b> specified. It changes to the
- delegate to the <b>representative</b> specified. Further, the
- <i>blockHash</i> of the previous block must be specified as the argument
- to <b>previous</b>. If the optional <b>-json</b> argument is used and
- specified as true the result is a JSON representation, otherwise a Tcl
- dict representation is used.
- <div class="Pp"></div>
- </dd>
- </dl>
- <h2 class="Ss" title="Ss" id="Work_Generation"><a class="permalink" href="#Work_Generation">Work
- Generation</a></h2>
- <dl class="Bl-tag">
- <dt><b>::nano::work::fromWorkData</b></dt>
- <dd><i>blockHashOrPublicKey</i> ?<b>-hex</b>|<b>-binary</b>? -> <i>work</i>
- <div class="Pp"></div>
- 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 (<i>previous</i>) is used. The specific value needed should be
- accessible from the <b>_workData</b> 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 <b>-hex</b> and <b>-binary</b> options determine the
- formatting of the result.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>::nano::work::fromBlock</b></dt>
- <dd><i>blockData</i> -> <i>work</i>
- <div class="Pp"></div>
- This is a convenience procedure which computes work data (either a block
- hash or a public key) for a given block and then calls
- <b>fromWorkData</b>.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>::nano::work::validate</b></dt>
- <dd><i>workData</i> <i>work</i> -> <i>boolean</i>
- <div class="Pp"></div>
- This procedure validates that the supplied <i>work</i> is valid for the
- supplied <i>workData</i>, which is either a block hash or an account
- public key. For more information see the description of
- <b>fromWorkData</b>.
- <div class="Pp"></div>
- <div class="Pp"></div>
- </dd>
- </dl>
- <h2 class="Ss" title="Ss" id="High-level_Account"><a class="permalink" href="#High-level_Account">High-level
- Account</a></h2>
- <dl class="Bl-tag">
- <dt><b>:nano::account::setFrontier</b></dt>
- <dd><i>account</i> <i>frontierHash</i> <i>balance</i> <i>representative</i>
- <div class="Pp"></div>
- This procedure is used as part of the High-level Account interface. It sets
- the <i>frontier</i>, which is the block hash (<i>frontierHash</i>) and
- data (<i>balance</i>, <i>representative</i>) associated with that block
- that corresponds to the head of an account's chain.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>:nano::account::getFrontier</b></dt>
- <dd><i>account</i> -> <i>frontierInfo</i>
- <div class="Pp"></div>
- 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 <i>account</i>.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>:nano::account::getFrontier</b></dt>
- <dd><i>account</i> ?<b>frontierHash</b>|<b>balance</b>|<b>representative</b>?
- -> <i>frontierHash</i>|<i>balance</i>|<i>representative</i>
- <div class="Pp"></div>
- 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 <i>account</i>.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>:nano::account::addPending</b></dt>
- <dd><i>account</i> <i>blockHash</i> <i>amount</i>
- <div class="Pp"></div>
- This procedure is used as part of the High-level Account interface. It is
- used to indicate than a given <i>account</i> has a <b>receive</b> block
- that they could create. The block hash of the corresponding <b>send</b>
- block should be supplied as the <i>blockHash</i> parameter. The amount of
- Nano that was sent in the <b>send</b> block should be specified as the
- <i>amount</i> parameter (in units of raw).
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>:nano::account::getPending</b></dt>
- <dd><i>account</i> ?<i>blockHash</i>? -> <i>dict</i>
- <div class="Pp"></div>
- This procedure is used as part of the High-level Account interface. It is
- used to retrieve information stored by <b>addPending</b> for a given
- <i>account</i>. If the <i>blockHash</i> parameter is supplied then a Tcl
- dictionary is returned with a key called <b>amount</b> which contains the
- amount stored previously. If the <i>blockHash</i> parameter is not
- supplied then a Tcl dictionary is returned with keys corresponding to each
- block hash pending for the specified <i>account</i>, and containing a
- subordinate Tcl dictionary with a key called <b>amount</b> as previously
- described.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>::nano::account::clearPending</b></dt>
- <dd><i>account</i> ?<i>blockHash</i>?
- <div class="Pp"></div>
- 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 <b>addPending</b> for
- a given <i>account</i>. If the <i>blockHash</i> parameter is supplied then
- only the entry corresponding to that blockhash is cleared, otherwise all
- entries for the specified <i>account</i> are cleared.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>:nano::account::receive</b></dt>
- <dd><i>account</i> <i>blockHash</i> <i>privateKey</i> ->
- <i>blockJSON</i>|<i>blockDict</i>
- <div class="Pp"></div>
- 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.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>:nano::account::receiveAllPending</b></dt>
- <dd><i>account</i> <i>privateKey</i> ->
- <i>listOfBlockJSON</i>|<i>listOfBlockDict</i>
- <div class="Pp"></div>
- 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
- <i>account</i>. Its interface is subject to change and not considered
- stable.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>:nano::account::send</b></dt>
- <dd><i>fromAccount</i> <i>toAccount</i> <i>amount</i> <i>privateKey</i> ->
- <i>blockJSON</i>|<i>blockDict</i>
- <div class="Pp"></div>
- 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.
- <div class="Pp"></div>
- </dd>
- </dl>
- <dl class="Bl-tag">
- <dt><b>::nano::account::setRepresentative</b></dt>
- <dd><i>account</i> <i>representative</i> <i>privateKey</i> ->
- <i>blockJSON</i>|<i>blockDict</i>
- <div class="Pp"></div>
- 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
- <i>account</i>. Its interface is subject to change and not considered
- stable.
- <div class="Pp"></div>
- </dd>
- </dl>
- <h1 class="Sh" title="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
- <h2 class="Ss" title="Ss" id="Example_1:_Generate_a_new_seed_and_derive_10_addresses_from_it"><a class="permalink" href="#Example_1:_Generate_a_new_seed_and_derive_10_addresses_from_it">Example
- 1: Generate a new seed and derive 10 addresses from it</a></h2>
- <pre>
- package require nano @@VERS@@
- <div class="Pp"></div>
- set seed [::nano::key::newSeed -hex]
- puts "Generated seed: $seed"
- <div class="Pp"></div>
- 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"
- }
- </pre>
- <div class="Pp"></div>
- <h1 class="Sh" title="Sh" id="AUTHOR"><a class="permalink" href="#AUTHOR">AUTHOR</a></h1>
- Roy Keene <<i>rkeene@nano.org</i>></div>
- <table class="foot">
- <tr>
- <td class="foot-date">@@SHORT_DATE@@</td>
- <td class="foot-os">nano @@VERS@@</td>
- </tr>
- </table>
- </body>
- </html>