Posted to tcl by stu at Tue Jul 17 14:38:48 GMT 2018view raw

  1. <!DOCTYPE html>
  2. <html>
  3. <head>
  4. <meta charset="utf-8"/>
  5. <style>
  6. table.head, table.foot { width: 100%; }
  7. td.head-rtitle, td.foot-os { text-align: right; }
  8. td.head-vol { text-align: center; }
  9. div.Pp { margin: 1ex 0ex; }
  10. div.Nd, div.Bf, div.Op { display: inline; }
  11. span.Pa, span.Ad { font-style: italic; }
  12. span.Ms { font-weight: bold; }
  13. dl.Bl-diag > dt { font-weight: bold; }
  14. code.Nm, code.Fl, code.Cm, code.Ic, code.In, code.Fd, code.Fn,
  15. code.Cd { font-weight: bold; font-family: inherit; }
  16. </style>
  17. <title>NANO(N)</title>
  18. </head>
  19. <body>
  20. <table class="head">
  21. <tr>
  22. <td class="head-ltitle">NANO(N)</td>
  23. <td class="head-vol"></td>
  24. <td class="head-rtitle">NANO(N)</td>
  25. </tr>
  26. </table>
  27. <div class="manual-text">
  28. <h1 class="Sh" title="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
  29. nano - Tcl bindings for Nano
  30. <h1 class="Sh" title="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
  31. <b>nano::</b>
  32. <br/>
  33. <b>address::</b>
  34. <br/>
  35. <b>toPublicKey</b> <i>address</i> ?<b>-hex</b>|<b>-binary</b>?
  36. ?<b>-verify</b>|<b>-no-verify</b>?
  37. <div>&#x00A0;</div>
  38. <b>fromPublicKey</b> <i>pubKey</i> ?<b>-xrb</b>|<b>-nano</b>?
  39. <div>&#x00A0;</div>
  40. <b>fromPrivateKey</b> <i>privateKey</i> ?<b>-xrb</b>|<b>-nano</b>?
  41. <div class="Pp"></div>
  42. <br/>
  43. <b>key::</b>
  44. <br/>
  45. <b>newSeed</b> ?<b>-hex</b>|<b>-binary</b>?
  46. <div>&#x00A0;</div>
  47. <b>newKey</b> ?<b>-hex</b>|<b>-binary</b>?
  48. <div>&#x00A0;</div>
  49. <b>fromSeed</b> <i>seed</i> ?<i>index</i>? ?<b>-hex</b>|<b>-binary</b>?
  50. <div>&#x00A0;</div>
  51. <b>publicKeyFromPrivateKey</b> <i>privateKey</i> ?<b>-hex</b>|<b>-binary</b>?
  52. <div class="Pp"></div>
  53. <br/>
  54. <b>block::</b>
  55. <br/>
  56. <b>json::toBlock</b> <i>blockJSON</i>
  57. <div>&#x00A0;</div>
  58. <b>json::fromDict</b> <i>blockDict</i>
  59. <div>&#x00A0;</div>
  60. <b>json::fromBlock</b> <i>blockData</i> ?<b>-xrb</b>|<b>-nano</b>? ?
  61. <b>-type=</b><i>blockType</i> ? ? <b>-signKey=</b><i>privateKey</i> ?
  62. <div>&#x00A0;</div>
  63. <b>json::sign</b> <i>blockJSON</i> <i>privateKey</i>
  64. ?<b>-update</b>|<b>-signature</b> ?<b>-hex</b>|<b>binary</b>??
  65. <div>&#x00A0;</div>
  66. <b>json::verifySignature</b> <i>blockJSON</i>
  67. <div>&#x00A0;</div>
  68. <b>json::work</b> <i>blockJSON</i> ?<b>-update</b>|<b>-work</b>
  69. ?<b>-hex</b>|<b>-binary</b>??
  70. <div>&#x00A0;</div>
  71. <b>json::validateWork</b> <i>blockJSON</i>
  72. <div>&#x00A0;</div>
  73. <b>json::filter</b> <i>blockJSON</i>
  74. <div class="Pp"></div>
  75. <b>dict::toBlock</b> <i>blockDict</i>
  76. <div>&#x00A0;</div>
  77. <b>dict::fromJSON</b> <i>blockJSON</i>
  78. <div>&#x00A0;</div>
  79. <b>dict::fromBlock</b> <i>blockData</i> ?<b>-xrb</b>|<b>-nano</b>? ?
  80. <b>-type=</b><i>blockType</i> ? ? <b>-signKey=</b><i>privateKey</i> ?
  81. <div>&#x00A0;</div>
  82. <b>dict::sign</b> <i>blockDict</i> <i>privateKey</i>
  83. ?<b>-update</b>|<b>-signature</b> ?<b>-hex</b>|<b>binary</b>??
  84. <div>&#x00A0;</div>
  85. <b>dict::verifySignature</b> <i>blockDict</i>
  86. <div>&#x00A0;</div>
  87. <b>dict::work</b> <i>blockDict</i> ?<b>-update</b>|<b>-work</b>
  88. ?<b>-hex</b>|<b>-binary</b>??
  89. <div>&#x00A0;</div>
  90. <b>dict::validateWork</b> <i>blockDict</i>
  91. <div class="Pp"></div>
  92. <b>hash</b> <i>blockData</i> ?<b>-hex</b>|<b>-binary</b>?
  93. <div>&#x00A0;</div>
  94. <b>signBlockHash</b> <i>blockHash</i> <i>privateKey</i>
  95. ?<b>-hex</b>|<b>-binary</b>?
  96. <div>&#x00A0;</div>
  97. <b>sign</b> <i>blockData</i> <i>privateKey</i> ?<b>-hex</b>|<b>-binary</b>?
  98. <div>&#x00A0;</div>
  99. <b>verifyBlockHash</b> <i>blockHash</i> <i>signature</i> <i>publicKey</i>
  100. <div>&#x00A0;</div>
  101. <b>verify</b> <i>blockData</i> <i>signature</i> <i>publicKey</i>
  102. <div class="Pp"></div>
  103. <b>create::send</b> <i>args</i>
  104. <div>&#x00A0;</div>
  105. <b>create::receive</b> <i>args</i>
  106. <div>&#x00A0;</div>
  107. <b>create::setRepresentative</b> <i>args</i>
  108. <div class="Pp"></div>
  109. <br/>
  110. <b>work::</b>
  111. <br/>
  112. <b>fromWorkData</b> <i>blockHashOrPublicKey</i> ?<b>-hex</b>|<b>-binary</b>?
  113. <div>&#x00A0;</div>
  114. <b>fromBlock</b> <i>blockData</i>
  115. <div>&#x00A0;</div>
  116. <b>validate</b> <i>workData</i> <i>work</i>
  117. <div class="Pp"></div>
  118. <br/>
  119. <b>account::</b>
  120. <br/>
  121. <b>setFrontier</b> <i>account</i> <i>frontierHash</i> <i>balance</i>
  122. <i>representative</i>
  123. <div>&#x00A0;</div>
  124. <b>getFrontier</b> <i>account</i>
  125. <div>&#x00A0;</div>
  126. <b>getFrontier</b> <i>account</i>
  127. ?<b>frontierHash</b>|<b>balance</b>|<b>representative</b>?
  128. <div>&#x00A0;</div>
  129. <b>addPending</b> <i>account</i> <i>blockHash</i> <i>amount</i>
  130. <div>&#x00A0;</div>
  131. <b>getPending</b> <i>account</i> ?<i>blockHash</i>?
  132. <div>&#x00A0;</div>
  133. <b>clearPending</b> <i>account</i> ?<i>blockHash</i>?
  134. <div class="Pp"></div>
  135. <b>receive</b> <i>account</i> <i>blockHash</i> <i>privateKey</i>
  136. <div>&#x00A0;</div>
  137. <b>receiveAllPending</b> <i>account</i> <i>privateKey</i>
  138. <div>&#x00A0;</div>
  139. <b>send</b> <i>fromAccount</i> <i>toAccount</i> <i>amount</i> <i>privateKey</i>
  140. <div>&#x00A0;</div>
  141. <b>setRepresentative</b> <i>account</i> <i>representative</i> <i>privateKey</i>
  142. <div class="Pp"></div>
  143. <br/>
  144. <br/>
  145. <div class="Pp"></div>
  146. <h1 class="Sh" title="Sh" id="INTRODUCTION"><a class="permalink" href="#INTRODUCTION">INTRODUCTION</a></h1>
  147. <i>Nano</i> is a low-latency payment platform that requires minimal resources,
  148. relying on a peer-to-peer network to distribute &quot;blocks&quot;, which are
  149. cryptographically signed transactions. This package provides bindings for
  150. interacting with the Nano network from <i>Tcl</i>.
  151. <div class="Pp"></div>
  152. Nano uses Ed25519 with Blake2b as the cryptographic hashing primitive for
  153. digital signatures, rather than the common construction of Ed25519 with the
  154. SHA2-512 cryptographic hashing function.
  155. <div class="Pp"></div>
  156. Nano implements a &quot;blockchain&quot;, which is a cryptographic linked-list,
  157. by identifying every &quot;block&quot; by its cryptographic hash and providing
  158. a pointer from every block to its predecessor in the &quot;chain&quot; as part
  159. of the hashed data.
  160. <div class="Pp"></div>
  161. This predecessors is referred to here as the &quot;previous&quot; block. In
  162. Nano, each account has its own blockchain and they reference each other using
  163. a data structure referred to as &quot;block lattice&quot;, where the
  164. individual chains contain blocks that reference blocks in other chains to tie
  165. them together. The field within blocks that reference other blocks on a
  166. different blockchain is referred to as either the &quot;link&quot; field or
  167. &quot;source block hash&quot;.
  168. <div class="Pp"></div>
  169. Each Nano block also encapsulates the full state of the account, containing, at
  170. a minimum, a tuple of (<i>account</i>, <i>balance</i>, <i>representative</i>,
  171. <i>previous</i>).
  172. <div class="Pp"></div>
  173. Since Nano blocks are signed by independent actors, who may, for their own gain,
  174. generate multiple valid blocks referring to the same predecessor
  175. (<i>previous</i>) block, an arbitration mechanism is employed by the Nano
  176. network to decide which blocks are valid within a given chain. This
  177. arbitration mechanism operates on the principles of consensus. Each account
  178. holder has a stake in the network operating nominally, otherwise the balance
  179. represented by an account is not useful for a transfer of value. In Nano the
  180. stake an account has in the network is equal to the account's balance. The
  181. larger the stake an account has the more incentivized the account-holder is to
  182. ensure the network is operating nominally and not accepting multiple blocks
  183. that reference the same predecessor.
  184. <div class="Pp"></div>
  185. Nano utilizes a mechanism called <i>voting</i> to determine which blocks are
  186. valid and which blocks are not valid. Each stakeholder votes their stake upon
  187. seeing a new subordinate block (<i>i.e.</i>, a block with a unique
  188. <i>previous</i> value). Since voting is an active and on-going process that
  189. occurs on the Nano peer-to-peer network, participants must be online to vote
  190. their stake. As this is often inconvenient or impossible, stakeholders may
  191. select another stakeholder to vote their share of the network. This delegate
  192. is referred to as a <i>representative</i>.
  193. <div class="Pp"></div>
  194. Representatives should be chosen carefully by stakeholders since malicious
  195. representatives may attempt to gather voting power and destabilize the Nano
  196. network by altering decisions made by consensus previously.
  197. <div class="Pp"></div>
  198. Nano accounts are referred to by address. A Nano address starts with the prefix
  199. &quot;<b>nano_</b>&quot; or &quot;<b>xrb_</b>&quot;. A Nano address is
  200. actually the public portion of a private/public keypair, plus the prefix, and
  201. a checksum to ensure that no digits are mistyped by users when communicating
  202. them. Nano public keys are 256-bit keys in the Ed25519 algorithm.
  203. <div class="Pp"></div>
  204. A user may have many accounts. To simplify the process of maintaining the
  205. private/public keypairs for all the accounts, Nano supports the concept of a
  206. <i>wallet</i>. A <i>wallet</i> is a conceptual entity that is used to refer to
  207. a <i>seed</i>, which is a random 256-bit number that can be used to derive
  208. multiple private/public keypairs from.
  209. <div class="Pp"></div>
  210. Balances in Nano are stored in a 128-bit integer value. There are various units
  211. for representing the balance, the smallest and base unit is called
  212. &quot;<i>raw</i>&quot;. The most common unit for users to use is called
  213. &quot;<i>Nano</i>&quot;, one of which is equal to 1e30 raw.
  214. <div class="Pp"></div>
  215. <h2 class="Ss" title="Ss" id="Addresses"><a class="permalink" href="#Addresses">Addresses</a></h2>
  216. Nano addresses are composed of a prefix (either &quot;<b>nano_</b>&quot; or
  217. &quot;<b>xrb_</b>&quot;) and 300 bits of base32 encoded data. The 300-bits of
  218. base32 encoded data produce a string that is 6 characters long using the
  219. base32 alphabet <b>13456789abcdefghijkmnopqrstuwxyz</b>. The format of these
  220. 300 bits are
  221. <pre>
  222. <div class="Pp"></div>
  223. struct {
  224. uint4_t padding = 0000b;
  225. uint256_t publicKey;
  226. uint40_t checksum;
  227. }
  228. <div class="Pp"></div>
  229. </pre>
  230. The checksum is computed as a 5 byte (40 bit) Blake2b hash of the 256-bit public
  231. key (in binary format), followed by reversing the bytes.
  232. <div class="Pp"></div>
  233. For example the public key
  234. <b>DC1512154EB72112B8CC230D7B8C7DD467DA78E4763182D6CAFAADB14855A5E8</b> which
  235. has a 5-byte Blake2b hash of <b>{0x18, 0x74, 0xA3, 0x46, 0x9C}</b> would be
  236. encoded as
  237. <b>0000.DC1512154EB72112B8CC230D7B8C7DD467DA78E4763182D6CAFAADB14855A5E8.9C46A37418</b>
  238. which when encoded in base32 and the prefix added produces the address
  239. <b>nano_3q1o4acnxfs34cwerarfhg89uo59ubwgaxjjiddeoyofp767dbhamj5c8x1r</b>.
  240. <div class="Pp"></div>
  241. <h2 class="Ss" title="Ss" id="Network"><a class="permalink" href="#Network">Network</a></h2>
  242. The Nano network consists of two different peer-to-peer networks. One for
  243. real-time block updates over UDP, and another for bulk ledger updates over TCP
  244. (<i>bootstrapping</i>). The real-time network is a broadcast style network
  245. where every message sent over it are relayed to all other nodes.
  246. <div class="Pp"></div>
  247. The customary and default port for the real-time/UDP network is 7075/udp, while
  248. the default port for the bootstrapping/TCP network is 7075/tcp.
  249. <div class="Pp"></div>
  250. The format of the messages on both networks is the same, however not every type
  251. of message may be used on either network. The <b>keepalive</b> message type is
  252. invalid on the TCP (bootstrapping) network and the <b>bulk_pull</b> message
  253. type is invalid on the UDP (real-time) network. The format of message are an 8
  254. byte header consisting of:
  255. <pre>
  256. <div class="Pp"></div>
  257. struct {
  258. uint8_t magicProtocol = 0x52;
  259. uint8_t magicNetwork = 0x41/0x42/0x43;
  260. uint8_t versionMax;
  261. uint8_t version;
  262. uint8_t versionMin;
  263. uint8_t messageType;
  264. uint16_t extensions;
  265. };
  266. <div class="Pp"></div>
  267. </pre>
  268. Where the <b>magicProtocol</b> field must be the value <b>0x52</b> (which is
  269. ASCII 'R') and the <b>magicNetwork</b> field must be one of <b>0x41</b>,
  270. <b>0x42</b>, or <b>0x43</b> corresponding to one of the three Nano networks. A
  271. value of <b>0x41</b> (ASCII 'A') represents the Test network; A value of
  272. <b>0x42</b> (ASCII 'B') represents the Beta network; A value of <b>0x43</b>
  273. (ASCII 'C') represents the Main network.
  274. <div class="Pp"></div>
  275. The various version fields control the relaying of the message to nodes running
  276. various versions of the Nano network protocol (distinct from the Nano
  277. reference implementation version). The <b>versionMax</b> and <b>versionMin</b>
  278. fields indicate the inclusive range of acceptable versions to relay or
  279. broadcast this message to. The <b>version</b> field indicates what version of
  280. the Nano protocol this node is using.
  281. <div class="Pp"></div>
  282. The messageType field indicates what type of message is being relayed, and must
  283. conform to the following enumeration
  284. <table class="tbl">
  285. <tr>
  286. <td>messageType</td>
  287. <td>Name</td>
  288. <td>On Bootstrap</td>
  289. <td>On Realtime</td>
  290. </tr>
  291. <tr>
  292. <td>0x00</td>
  293. <td>Invalid</td>
  294. <td>Yes</td>
  295. <td>Yes</td>
  296. </tr>
  297. <tr>
  298. <td>0x01</td>
  299. <td>Not_A_Type</td>
  300. <td>?</td>
  301. <td>?</td>
  302. </tr>
  303. <tr>
  304. <td>0x02</td>
  305. <td>Keepalive</td>
  306. <td>No</td>
  307. <td>Yes</td>
  308. </tr>
  309. <tr>
  310. <td>0x03</td>
  311. <td>Publish</td>
  312. <td>No</td>
  313. <td>Yes</td>
  314. </tr>
  315. <tr>
  316. <td>0x04</td>
  317. <td>Confirm_Req</td>
  318. <td>No</td>
  319. <td>Yes</td>
  320. </tr>
  321. <tr>
  322. <td>0x05</td>
  323. <td>Confirm_Ack</td>
  324. <td>No</td>
  325. <td>Yes</td>
  326. </tr>
  327. <tr>
  328. <td>0x06</td>
  329. <td>Bulk_Pull</td>
  330. <td>Yes</td>
  331. <td>No</td>
  332. </tr>
  333. <tr>
  334. <td>0x07</td>
  335. <td>Bulk_Push</td>
  336. <td>Yes</td>
  337. <td>No</td>
  338. </tr>
  339. <tr>
  340. <td>0x08</td>
  341. <td>Frontier_Req</td>
  342. <td>Yes</td>
  343. <td>No</td>
  344. </tr>
  345. <tr>
  346. <td>0x09</td>
  347. <td>Bulk_Pull_Blocks</td>
  348. <td>Yes</td>
  349. <td>No</td>
  350. </tr>
  351. </table>
  352. <div class="Pp"></div>
  353. <b>TODO: Extensions</b>
  354. <div class="Pp"></div>
  355. Following the message header comes the payload for the particular message type.
  356. <div class="Pp"></div>
  357. <dl class="Bl-tag">
  358. <dt><b>Invalid</b></dt>
  359. <dd>TODOC
  360. <div class="Pp"></div>
  361. </dd>
  362. </dl>
  363. <dl class="Bl-tag">
  364. <dt><b>Not_A_Type</b></dt>
  365. <dd>TODOC
  366. <div class="Pp"></div>
  367. </dd>
  368. </dl>
  369. <dl class="Bl-tag">
  370. <dt><b>Keepalive</b></dt>
  371. <dd>The Keepalive message requires exactly 8 IPv6 address and port number
  372. tuples to be sent as its payload. The IPv6 addresses are each 128-bits
  373. (16-bytes) long and the port numbers are 16-bit integers sent in network
  374. byte order. The payload for the Keepalive message type is 144 bytes in
  375. size.
  376. <div class="Pp"></div>
  377. </dd>
  378. </dl>
  379. <dl class="Bl-tag">
  380. <dt><b>Publish</b></dt>
  381. <dd>TODOC
  382. <div class="Pp"></div>
  383. </dd>
  384. </dl>
  385. <dl class="Bl-tag">
  386. <dt><b>Confirm_Req</b></dt>
  387. <dd>TODOC
  388. <div class="Pp"></div>
  389. </dd>
  390. </dl>
  391. <dl class="Bl-tag">
  392. <dt><b>Confirm_Ack</b></dt>
  393. <dd>TODOC
  394. <div class="Pp"></div>
  395. </dd>
  396. </dl>
  397. <dl class="Bl-tag">
  398. <dt><b>Bulk_Pull</b></dt>
  399. <dd>TODOC
  400. <div class="Pp"></div>
  401. </dd>
  402. </dl>
  403. <dl class="Bl-tag">
  404. <dt><b>Bulk_Push</b></dt>
  405. <dd>TODOC
  406. <div class="Pp"></div>
  407. </dd>
  408. </dl>
  409. <dl class="Bl-tag">
  410. <dt><b>Frontier_Req</b></dt>
  411. <dd>TODOC
  412. <div class="Pp"></div>
  413. </dd>
  414. </dl>
  415. <dl class="Bl-tag">
  416. <dt><b>Bulk_Pull_Blocks</b></dt>
  417. <dd>TODOC
  418. <div class="Pp"></div>
  419. <div class="Pp"></div>
  420. </dd>
  421. </dl>
  422. <h1 class="Sh" title="Sh" id="PROCEDURES"><a class="permalink" href="#PROCEDURES">PROCEDURES</a></h1>
  423. <h2 class="Ss" title="Ss" id="Addresses_2"><a class="permalink" href="#Addresses_2">Addresses</a></h2>
  424. <dl class="Bl-tag">
  425. <dt><b>::nano::address::toPublicKey</b></dt>
  426. <dd><i>address</i> ?<b>-hex</b>|<b>-binary</b>?
  427. ?<b>-verify</b>|<b>-no-verify</b>? <b> -&gt; </b><i>publicKey</i>
  428. <div class="Pp"></div>
  429. Converts a Nano address to a public key. The <b>-hex</b> option indicates
  430. that the public key should be returned in hexadecimal form. The
  431. <b>-binary</b> option indicates that the public key should be returned in
  432. binary form. The <b>-verify</b> option verifies the checksum embedded in
  433. the Nano address before returning. The <b>-no-verify</b> option inhibits
  434. verifying the checksum embedded in the Nano address.
  435. <div class="Pp"></div>
  436. </dd>
  437. </dl>
  438. <dl class="Bl-tag">
  439. <dt><b>::nano::address::fromPublicKey</b></dt>
  440. <dd><i>pubKey</i> ?<b>-xrb</b>|<b>-nano</b>? <b> -&gt; </b><i>address</i>
  441. <div class="Pp"></div>
  442. Converts a public key to a Nano address. The <b>-xrb</b> option specifies
  443. that the returned address should be prefixed with the old-style
  444. &quot;xrb_&quot; prefix, where the <b>-nano</b> option specifies that the
  445. returned address should be prefixed with the new-style &quot;nano_&quot;
  446. prefix.
  447. <div class="Pp"></div>
  448. </dd>
  449. </dl>
  450. <dl class="Bl-tag">
  451. <dt><b>::nano::address::fromPrivateKey</b></dt>
  452. <dd><i>privateKey</i> ?<b>-xrb</b>|<b>-nano</b>? <b> -&gt; </b><i>address</i>
  453. <div class="Pp"></div>
  454. Converts a private key to a Nano address. It accepts the same arguments as
  455. <b>fromPublicKey</b>.
  456. <div class="Pp"></div>
  457. </dd>
  458. </dl>
  459. <h2 class="Ss" title="Ss" id="Key_Management"><a class="permalink" href="#Key_Management">Key
  460. Management</a></h2>
  461. <dl class="Bl-tag">
  462. <dt><b>::nano::key::newSeed</b></dt>
  463. <dd>?<b>-hex</b>|<b>-binary</b>? -&gt; <i>seed</i>
  464. <div class="Pp"></div>
  465. Generates a new seed. A seed is a 256-bit bit-field which, along with a
  466. 32-bit index, is used to derive enumerated keys from a single point of
  467. entropy. See the <b>fromSeed</b> procedure. The <b>-hex</b> and
  468. <b>-binary</b> options determine the formatting of the result.
  469. <div class="Pp"></div>
  470. </dd>
  471. </dl>
  472. <dl class="Bl-tag">
  473. <dt><b>::nano::key::newKey</b></dt>
  474. <dd>?<b>-hex</b>|<b>-binary</b>? -&gt; <i>privateKey</i>
  475. <div class="Pp"></div>
  476. Generates a new private key. A private key can be used to sign transactions,
  477. which can then be verified with its corresponding public key (see
  478. <b>publicKeyFromPrivateKey</b>). This procedure is normally not used, but
  479. rather private keys are derived from a <i>seed</i> and <i>index</i> pair
  480. using the <b>fromSeed</b> procedure. The <b>-hex</b> and <b>-binary</b>
  481. options determine the formatting of the result.
  482. <div class="Pp"></div>
  483. </dd>
  484. </dl>
  485. <dl class="Bl-tag">
  486. <dt><b>::nano::key::fromSeed</b></dt>
  487. <dd><i>seed</i> ?<i>index</i>? ?<b>-hex</b>|<b>-binary</b>? -&gt;
  488. <i>privateKey</i>
  489. <div class="Pp"></div>
  490. Derive a private key from the seed specified as <i>seed</i> and the
  491. <i>index</i> indicated. This procedure is deterministic (i.e., the same
  492. <i>seed</i> and <i>index</i> will always give you the same private key).
  493. This procedure is used to derive many keypairs from a single user-managed
  494. piece of data, so the user does not have to manage multiple private keys.
  495. If the <i>index</i> is not specified it defaults to <b>0</b>. The
  496. <b>-hex</b> and <b>-binary</b> options determine the formatting of the
  497. result.
  498. <div class="Pp"></div>
  499. </dd>
  500. </dl>
  501. <dl class="Bl-tag">
  502. <dt><b>::nano::key::publicKeyFromPrivateKey</b></dt>
  503. <dd><i>privateKey</i> ?<b>-hex</b>|<b>-binary</b>? -&gt; <i>publicKey</i>
  504. <div class="Pp"></div>
  505. Converts a private key into its corresponding public key. Normally Ed25519
  506. private keys are a concatenation of the private and public keys, however
  507. in this package they are each treated separately. The <b>-hex</b> and
  508. <b>-binary</b> options determine the formatting of the result.
  509. <div class="Pp"></div>
  510. </dd>
  511. </dl>
  512. <h2 class="Ss" title="Ss" id="Low-level_Block"><a class="permalink" href="#Low-level_Block">Low-level
  513. Block</a></h2>
  514. <dl class="Bl-tag">
  515. <dt><b>::nano::block::</b><i>representation</i><b>::toBlock</b></dt>
  516. <dd><i>blockRepresentation</i> -&gt; <i>blockData</i>
  517. <div class="Pp"></div>
  518. Converts from one of the internal representations (either Tcl dictionary or
  519. JSON) to a Nano block. The <i>representation</i> portion of the command
  520. name may be one of <b>dict</b> or <b>json</b>.
  521. <div class="Pp"></div>
  522. </dd>
  523. </dl>
  524. <dl class="Bl-tag">
  525. <dt><b>::nano::block::json::fromDict</b></dt>
  526. <dd><i>blockDict</i> -&gt; <i>blockJSON</i>
  527. <div class="Pp"></div>
  528. Converts from a Tcl dictionary representation to a JSON representation of a
  529. block.
  530. <div class="Pp"></div>
  531. </dd>
  532. </dl>
  533. <dl class="Bl-tag">
  534. <dt><b>::nano::block::json::filter</b></dt>
  535. <dd><i>blockJSON</i> -&gt; <i>blockJSON</i>
  536. <div class="Pp"></div>
  537. Filters out JSON object attributes which are not suitable for using with
  538. other implementations, such as <i>_comment</i>, <i>_workData</i>, and
  539. <i>_blockHash</i>.
  540. <div class="Pp"></div>
  541. </dd>
  542. </dl>
  543. <dl class="Bl-tag">
  544. <dt><b>::nano::block::dict::fromJSON</b></dt>
  545. <dd><i>blockJSON</i> -&gt; <i>blockDict</i>
  546. <div class="Pp"></div>
  547. Converts from a JSON object representation to a Tcl dictionary
  548. representation of a block.
  549. <div class="Pp"></div>
  550. </dd>
  551. </dl>
  552. <dl class="Bl-tag">
  553. <dt><b>::nano::block::</b><i>representation</i><b>::fromBlock</b></dt>
  554. <dd><i>blockData</i> ?<b>-xrb</b>|<b>-nano</b>? ?
  555. <b>-type=</b><i>blockType</i> ? ? <b>-signKey=</b><i>privateKey</i> ?
  556. -&gt; <i>blockRepresentation</i>
  557. <div class="Pp"></div>
  558. Parses a Nano block and returns either a Tcl dictionary or a JSON object.
  559. The <b>-xrb</b> option causes all parsed addresses to be prefixed with the
  560. old-style &quot;xrb_&quot; address prefix, while the <b>-nano</b> option
  561. causes them to be prefixed with the new-style &quot;nano_prefix&quot;. The
  562. <i>representation</i> portion of the command name may be one of
  563. <b>dict</b> or <b>json</b>.
  564. <div class="Pp"></div>
  565. </dd>
  566. </dl>
  567. <dl class="Bl-tag">
  568. <dt><b>::nano::block::</b><i>representation</i><b>::sign</b></dt>
  569. <dd><i>blockRepresentation</i> <i>privateKey</i>
  570. ?<b>-update</b>|<b>-signature</b> ?<b>-hex</b>|<b>binary</b>?? -&gt;
  571. <i>signature</i>|<i>blockJSON</i>
  572. <div class="Pp"></div>
  573. Sign a block, in either Tcl dictionary or JSON representation, with the
  574. specified <i>privateKey</i>. If the <b>-update</b> option is used, return
  575. the object with the updated attribute. If the <b>-signature</b> option is
  576. used, return just the signature. The <b>-hex</b> and <b>-binary</b>
  577. options determine the formatting of the result. The <i>representation</i>
  578. portion of the command name may be one of <b>dict</b> or <b>json</b>.
  579. <div class="Pp"></div>
  580. </dd>
  581. </dl>
  582. <dl class="Bl-tag">
  583. <dt><b>::nano::block::</b><i>representation</i><b>::verifySignature</b></dt>
  584. <dd><i>blockRepresentation</i> -&gt; <i>boolean</i>
  585. <div class="Pp"></div>
  586. Verify the signature on a block, in either Tcl dictionary or JSON
  587. representation, matches the public key specified in the <b>account</b>
  588. attribute of that object. This may not work correctly for old-style blocks
  589. unless you manually add the <b>account</b> attribute. The
  590. <i>representation</i> portion of the command name may be one of
  591. <b>dict</b> or <b>json</b>.
  592. <div class="Pp"></div>
  593. </dd>
  594. </dl>
  595. <dl class="Bl-tag">
  596. <dt><b>::nano::block::</b><i>representation</i><b>::work</b></dt>
  597. <dd><i>blockRepresentation</i> ?<b>-update</b>|<b>-work</b>
  598. ?<b>-hex</b>|<b>binary</b>?? -&gt; <i>work</i>|<i>blockRepresentation</i>
  599. <div class="Pp"></div>
  600. Generate proof-of-work (PoW) required to submit a given block to the
  601. network. Nano uses PoW to increase the cost of submitting blocks to the
  602. network to cut down on spam. The <i>work</i> that is computed is based on
  603. the hash of the previous block on this chain, or if there is no previous
  604. block on this chain (i.e., because it is the first block on an account)
  605. the public key of the account. If the <b>-update</b> option is used,
  606. return the object with the updated attribute. If the <b>-work</b> option
  607. is used, just return the work. The <b>-hex</b> and <b>-binary</b> options
  608. determine the formatting of the result. The <i>representation</i> portion
  609. of the command name may be one of <b>dict</b> or <b>json</b>.
  610. <div class="Pp"></div>
  611. </dd>
  612. </dl>
  613. <dl class="Bl-tag">
  614. <dt><b>::nano::block::</b><i>representation</i><b>::validateWork</b></dt>
  615. <dd><i>blockRepresentation</i> -&gt; <i>boolean</i>
  616. <div class="Pp"></div>
  617. Validate the proof-of-work (PoW) in the object specified as
  618. <i>blockRepresentation</i> with the attribute <b>work</b> is valid for the
  619. block passed in. The <i>representation</i> portion of the command name may
  620. be one of <b>dict</b> or <b>json</b>.
  621. <div class="Pp"></div>
  622. </dd>
  623. </dl>
  624. <dl class="Bl-tag">
  625. <dt><b>::nano::block::hash</b></dt>
  626. <dd><i>blockData</i> ?<b>-hex</b>|<b>-binary</b>? -&gt; <i>blockHash</i>
  627. <div class="Pp"></div>
  628. Compute the cryptographic hash of a block. The cryptographic hashing
  629. algorithm used for Nano is Blake2b. Blocks are typically identified by
  630. their hash (i.e., content addressable). The <b>-hex</b> and <b>-binary</b>
  631. options determine the formatting of the result.
  632. <div class="Pp"></div>
  633. </dd>
  634. </dl>
  635. <dl class="Bl-tag">
  636. <dt><b>::nano::block::signBlockHash</b></dt>
  637. <dd><i>blockHash</i> <i>privateKey</i> ?<b>-hex</b>|<b>-binary</b>? -&gt;
  638. <i>signature</i>
  639. <div class="Pp"></div>
  640. Compute an Ed25519-with-Blake2b signature of a given block hash specified as
  641. <i>blockHash</i> with the private key specified as <i>privateKey</i>. In
  642. Nano, signed blocks are signed by signing the block's hash thus all that
  643. is needed to sign a block is its hash and the private key that corresponds
  644. to the account. <b>NOTE: Ensure that the</b> <i>privateKey</i>
  645. <b>specified matches the account the block belongs to.</b> The <b>-hex</b>
  646. and <b>-binary</b> options determine the formatting of the result.
  647. <div class="Pp"></div>
  648. </dd>
  649. </dl>
  650. <dl class="Bl-tag">
  651. <dt><b>::nano::block::sign</b></dt>
  652. <dd><i>blockData</i> <i>privateKey</i> ?<b>-hex</b>|<b>-binary</b>? -&gt;
  653. <i>signature</i>
  654. <div class="Pp"></div>
  655. This is a convenience procedure which computes the hash of a block given as
  656. <i>blockData</i>, and then calls <b>signBlockHash</b>. The <b>-hex</b> and
  657. <b>-binary</b> options determine the formatting of the result.
  658. <div class="Pp"></div>
  659. </dd>
  660. </dl>
  661. <dl class="Bl-tag">
  662. <dt><b>::nano::block::verifyBlockHash</b></dt>
  663. <dd><i>blockHash</i> <i>signature</i> <i>publicKey</i> -&gt; <i>boolean</i>
  664. <div class="Pp"></div>
  665. Verify that a block hash (<i>blockHash</i>) was signed (<i>signature</i>) by
  666. an account holding the private key that corresponds to the public key
  667. specified as <i>publicKey</i>.
  668. <div class="Pp"></div>
  669. </dd>
  670. </dl>
  671. <dl class="Bl-tag">
  672. <dt><b>::nano::block::verify</b></dt>
  673. <dd><i>blockData</i> <i>signature</i> <i>publicKey</i> -&gt; <i>boolean</i>
  674. <div class="Pp"></div>
  675. This is a convenience procedure which computes the hash of a block given as
  676. <i>blockData</i>, and then calls <b>verifyBlockHash</b>.
  677. <div class="Pp"></div>
  678. </dd>
  679. </dl>
  680. <dl class="Bl-tag">
  681. <dt><b>::nano::block::create::send</b></dt>
  682. <dd><b>from </b><i>address</i> <b>to </b><i>address</i> <b>previous
  683. </b><i>blockHash</i> <b>representative </b><i>address</i>
  684. <b>previousBalance </b><i>integer</i> <b>amount </b><i>integer</i> ?
  685. <b>-json </b><i>boolean</i> ? -&gt; <i>blockJSON</i>|<i>blockDict</i>
  686. <div class="Pp"></div>
  687. This is a low-level interface for creating blocks which correspond to
  688. sending Nano from one account to another. It constructs a block which
  689. sends the <b>amount</b> specified from the <b>from</b> address to the
  690. destination (<b>to</b>). The previous block's hash must be specified as
  691. the <i>blockHash</i> following <b>previous</b>. Additionally the balance
  692. of the account at the previous block must be supplied as the integer
  693. argument to <b>previousBalance</b>. All balance amounts are in units of
  694. <b>raw</b>. If the optional <b>-json</b> argument is used and specified as
  695. true the result is a JSON representation, otherwise a Tcl dict
  696. representation is used.
  697. <div class="Pp"></div>
  698. </dd>
  699. </dl>
  700. <dl class="Bl-tag">
  701. <dt><b>::nano::block::create::receive</b></dt>
  702. <dd><b>to </b><i>address</i> <b>sourceBlock </b><i>blockHash</i> <b>previous
  703. </b><i>blockHash</i> <b>representative </b><i>address</i>
  704. <b>previousBalance </b><i>integer</i> <b>amount </b><i>integer</i> ?
  705. <b>-json </b><i>boolean</i> ? -&gt; <i>blockJSON</i>|<i>blockDict</i>
  706. <div class="Pp"></div>
  707. This is a low-level interface for creating blocks which correspond to
  708. receiving (pocketing) Nano previously sent from another account to the
  709. account specified as the <i>address</i> supplied to the <b>to</b>
  710. argument. It constructs a block which receives the amount of Nano
  711. specified as the <b>amount</b> argument. The block hash (<i>blockHash</i>)
  712. of the send block which was used to send the Nano to this account must be
  713. specified as the argument to the <b>sourceBlock</b> option. The previous
  714. block's hash must be specified as the <i>blockHash</i> following
  715. <b>previous</b>. Additionally the balance of the account at the previous
  716. block must be supplied as the integer argument to <b>previousBalance</b>.
  717. All balance amounts are in units of <b>raw</b>. If the optional
  718. <b>-json</b> argument is used and specified as true the result is a JSON
  719. representation, otherwise a Tcl dict representation is used.
  720. <div class="Pp"></div>
  721. </dd>
  722. </dl>
  723. <dl class="Bl-tag">
  724. <dt><b>::nano::block::create::setRepresentative</b></dt>
  725. <dd><b>account </b><i>address</i> <b>previous </b><i>blockHash</i>
  726. <b>representative </b><i>address</i> ? <b>-json </b><i>boolean</i> ? -&gt;
  727. <i>blockJSON</i>|<i>blockDict</i>
  728. <div class="Pp"></div>
  729. This is a low-level interface for creating blocks which correspond to an
  730. explicit change of representative. Representatives in Nano are used as
  731. part of the Delegated Proof-of-Stake (dPoS) consensus mechanism which is
  732. used by the Nano network to determine which block (if any) out of many
  733. possible subordinate blocks in a chain are valid. So that every account
  734. holder does not have to be online to vote for valid transactions, an
  735. account may delegate another account to vote its stake on its behalf. That
  736. delegate is called a representative. An account may change its
  737. representative at any time by issuing a block with a new representative,
  738. such as a send or receive block, or by issuing an explicit change of
  739. representative block. This procedure creates an explicit change of
  740. representative block for the <b>account</b> specified. It changes to the
  741. delegate to the <b>representative</b> specified. Further, the
  742. <i>blockHash</i> of the previous block must be specified as the argument
  743. to <b>previous</b>. If the optional <b>-json</b> argument is used and
  744. specified as true the result is a JSON representation, otherwise a Tcl
  745. dict representation is used.
  746. <div class="Pp"></div>
  747. </dd>
  748. </dl>
  749. <h2 class="Ss" title="Ss" id="Work_Generation"><a class="permalink" href="#Work_Generation">Work
  750. Generation</a></h2>
  751. <dl class="Bl-tag">
  752. <dt><b>::nano::work::fromWorkData</b></dt>
  753. <dd><i>blockHashOrPublicKey</i> ?<b>-hex</b>|<b>-binary</b>? -&gt; <i>work</i>
  754. <div class="Pp"></div>
  755. Create proof-of-work (PoW) from a block hash or public key. Which one is
  756. used depends on whether or not there are any other blocks in this
  757. account's chain. If this is the first block in this account's chain then
  758. the public key of the account is used, otherwise the hash of the blocks
  759. predecessor (<i>previous</i>) is used. The specific value needed should be
  760. accessible from the <b>_workData</b> member of a JSON object or Tcl
  761. dictionary. Note that this attribute (and all attributes that begin with
  762. an underscore) should be discarded when sending the block outside of the
  763. Tcl process. The <b>-hex</b> and <b>-binary</b> options determine the
  764. formatting of the result.
  765. <div class="Pp"></div>
  766. </dd>
  767. </dl>
  768. <dl class="Bl-tag">
  769. <dt><b>::nano::work::fromBlock</b></dt>
  770. <dd><i>blockData</i> -&gt; <i>work</i>
  771. <div class="Pp"></div>
  772. This is a convenience procedure which computes work data (either a block
  773. hash or a public key) for a given block and then calls
  774. <b>fromWorkData</b>.
  775. <div class="Pp"></div>
  776. </dd>
  777. </dl>
  778. <dl class="Bl-tag">
  779. <dt><b>::nano::work::validate</b></dt>
  780. <dd><i>workData</i> <i>work</i> -&gt; <i>boolean</i>
  781. <div class="Pp"></div>
  782. This procedure validates that the supplied <i>work</i> is valid for the
  783. supplied <i>workData</i>, which is either a block hash or an account
  784. public key. For more information see the description of
  785. <b>fromWorkData</b>.
  786. <div class="Pp"></div>
  787. <div class="Pp"></div>
  788. </dd>
  789. </dl>
  790. <h2 class="Ss" title="Ss" id="High-level_Account"><a class="permalink" href="#High-level_Account">High-level
  791. Account</a></h2>
  792. <dl class="Bl-tag">
  793. <dt><b>:nano::account::setFrontier</b></dt>
  794. <dd><i>account</i> <i>frontierHash</i> <i>balance</i> <i>representative</i>
  795. <div class="Pp"></div>
  796. This procedure is used as part of the High-level Account interface. It sets
  797. the <i>frontier</i>, which is the block hash (<i>frontierHash</i>) and
  798. data (<i>balance</i>, <i>representative</i>) associated with that block
  799. that corresponds to the head of an account's chain.
  800. <div class="Pp"></div>
  801. </dd>
  802. </dl>
  803. <dl class="Bl-tag">
  804. <dt><b>:nano::account::getFrontier</b></dt>
  805. <dd><i>account</i> -&gt; <i>frontierInfo</i>
  806. <div class="Pp"></div>
  807. This procedure is used as part of the High-level Account interface. It gets
  808. the Tcl dictionary associated with the frontier most recently set for the
  809. specified <i>account</i>.
  810. <div class="Pp"></div>
  811. </dd>
  812. </dl>
  813. <dl class="Bl-tag">
  814. <dt><b>:nano::account::getFrontier</b></dt>
  815. <dd><i>account</i> ?<b>frontierHash</b>|<b>balance</b>|<b>representative</b>?
  816. -&gt; <i>frontierHash</i>|<i>balance</i>|<i>representative</i>
  817. <div class="Pp"></div>
  818. This procedure is used as part of the High-level Account interface. It gets
  819. a specific item from Tcl dictionary associated with the frontier most
  820. recently set for the specified <i>account</i>.
  821. <div class="Pp"></div>
  822. </dd>
  823. </dl>
  824. <dl class="Bl-tag">
  825. <dt><b>:nano::account::addPending</b></dt>
  826. <dd><i>account</i> <i>blockHash</i> <i>amount</i>
  827. <div class="Pp"></div>
  828. This procedure is used as part of the High-level Account interface. It is
  829. used to indicate than a given <i>account</i> has a <b>receive</b> block
  830. that they could create. The block hash of the corresponding <b>send</b>
  831. block should be supplied as the <i>blockHash</i> parameter. The amount of
  832. Nano that was sent in the <b>send</b> block should be specified as the
  833. <i>amount</i> parameter (in units of raw).
  834. <div class="Pp"></div>
  835. </dd>
  836. </dl>
  837. <dl class="Bl-tag">
  838. <dt><b>:nano::account::getPending</b></dt>
  839. <dd><i>account</i> ?<i>blockHash</i>? -&gt; <i>dict</i>
  840. <div class="Pp"></div>
  841. This procedure is used as part of the High-level Account interface. It is
  842. used to retrieve information stored by <b>addPending</b> for a given
  843. <i>account</i>. If the <i>blockHash</i> parameter is supplied then a Tcl
  844. dictionary is returned with a key called <b>amount</b> which contains the
  845. amount stored previously. If the <i>blockHash</i> parameter is not
  846. supplied then a Tcl dictionary is returned with keys corresponding to each
  847. block hash pending for the specified <i>account</i>, and containing a
  848. subordinate Tcl dictionary with a key called <b>amount</b> as previously
  849. described.
  850. <div class="Pp"></div>
  851. </dd>
  852. </dl>
  853. <dl class="Bl-tag">
  854. <dt><b>::nano::account::clearPending</b></dt>
  855. <dd><i>account</i> ?<i>blockHash</i>?
  856. <div class="Pp"></div>
  857. This procedure is used as part of the High-level Account interface. It is
  858. used to clear (that is, remove from the conceptual state of
  859. &quot;pending&quot;) entries created previously with <b>addPending</b> for
  860. a given <i>account</i>. If the <i>blockHash</i> parameter is supplied then
  861. only the entry corresponding to that blockhash is cleared, otherwise all
  862. entries for the specified <i>account</i> are cleared.
  863. <div class="Pp"></div>
  864. </dd>
  865. </dl>
  866. <dl class="Bl-tag">
  867. <dt><b>:nano::account::receive</b></dt>
  868. <dd><i>account</i> <i>blockHash</i> <i>privateKey</i> -&gt;
  869. <i>blockJSON</i>|<i>blockDict</i>
  870. <div class="Pp"></div>
  871. This procedure is used as part of the High-level Account interface. It is
  872. used to generate a receive block. Its interface is subject to change and
  873. not considered stable.
  874. <div class="Pp"></div>
  875. </dd>
  876. </dl>
  877. <dl class="Bl-tag">
  878. <dt><b>:nano::account::receiveAllPending</b></dt>
  879. <dd><i>account</i> <i>privateKey</i> -&gt;
  880. <i>listOfBlockJSON</i>|<i>listOfBlockDict</i>
  881. <div class="Pp"></div>
  882. This procedure is used as part of the High-level Account interface. It is
  883. used to generate receive blocks for every pending receive on a given
  884. <i>account</i>. Its interface is subject to change and not considered
  885. stable.
  886. <div class="Pp"></div>
  887. </dd>
  888. </dl>
  889. <dl class="Bl-tag">
  890. <dt><b>:nano::account::send</b></dt>
  891. <dd><i>fromAccount</i> <i>toAccount</i> <i>amount</i> <i>privateKey</i> -&gt;
  892. <i>blockJSON</i>|<i>blockDict</i>
  893. <div class="Pp"></div>
  894. This procedure is used as part of the High-level Account interface. It is
  895. used to generate a send block. Its interface is subject to change and not
  896. considered stable.
  897. <div class="Pp"></div>
  898. </dd>
  899. </dl>
  900. <dl class="Bl-tag">
  901. <dt><b>::nano::account::setRepresentative</b></dt>
  902. <dd><i>account</i> <i>representative</i> <i>privateKey</i> -&gt;
  903. <i>blockJSON</i>|<i>blockDict</i>
  904. <div class="Pp"></div>
  905. This procedure is used as part of the High-level Account interface. It is
  906. used to generate a block that changes the representative for the given
  907. <i>account</i>. Its interface is subject to change and not considered
  908. stable.
  909. <div class="Pp"></div>
  910. </dd>
  911. </dl>
  912. <h1 class="Sh" title="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1>
  913. <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
  914. 1: Generate a new seed and derive 10 addresses from it</a></h2>
  915. <pre>
  916. package require nano @@VERS@@
  917. <div class="Pp"></div>
  918. set seed [::nano::key::newSeed -hex]
  919. puts &quot;Generated seed: $seed&quot;
  920. <div class="Pp"></div>
  921. for {set index 0} {$index &lt; 10} {incr index} {
  922. set accountPrivateKey [::nano::key::fromSeed $seed $index -hex]
  923. set accountAddress [::nano::address::fromPrivateKey $accountPrivateKey]
  924. puts &quot; - $index: $accountAddress&quot;
  925. }
  926. </pre>
  927. <div class="Pp"></div>
  928. <h1 class="Sh" title="Sh" id="AUTHOR"><a class="permalink" href="#AUTHOR">AUTHOR</a></h1>
  929. Roy Keene &lt;<i>rkeene@nano.org</i>&gt;</div>
  930. <table class="foot">
  931. <tr>
  932. <td class="foot-date">@@SHORT_DATE@@</td>
  933. <td class="foot-os">nano @@VERS@@</td>
  934. </tr>
  935. </table>
  936. </body>
  937. </html>
  938.