Check-in [c0dd083188]
Overview
Comment:Updated man page
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: c0dd083188982eb71830caeab33eac435658d744a18eacd77e150e2b091a7852
User & Date: rkeene on 2018-07-09 15:33:15
Other Links: manifest | tags
Context
2018-07-09
16:52
Updated to support creating a wiki page for the Tcl Nano manual page check-in: 3bf973af21 user: rkeene tags: trunk
15:33
Updated man page check-in: c0dd083188 user: rkeene tags: trunk
05:11
Updated testing to handle errors and print a cleaner output check-in: e0f108b17b user: rkeene tags: trunk
Changes

Modified nano.man from [9839687c3f] to [f7be80da2e].

215
216
217
218
219
220
221
222

223
224
225




226

227
228
229










































































230
231
232
233
234
235
236
215
216
217
218
219
220
221

222
223


224
225
226
227
228
229



230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310







-
+

-
-
+
+
+
+

+
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+







.I account
.I representative
.I privateKey

.in -2m
.in -2m

.SH DESCRIPTION
.SH INTRODUCTION
.I Nano
is a low-latency payment platform that requires minimal resources.  This
package provides bindings for interacting with the Nano network from
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
.IR Tcl .

It uses Ed25519 with Blake2b as the cryptographic hashing primitive (rather
than the normal construction of Ed25519 with the SHA3-512 cryptographic
hashing function) for digital signatures.
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 crytographic 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
.RI ( 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
.RI ( 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
.I voting
to determine which blocks are valid and which blocks are not valid.  Each
stakeholder votes their stake upon seeing a new subordinate block
.RI ( i.e. ,
a block with a unique
.I 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 inconvienent or impossible, stakeholders may select another
stakeholder to vote their share of the network.  This delegate is referred to
as a
.IR representative .

Representatives should be chosen carefully by stakeholders since malicious
representatives may attempt to gather voting power and destablize the Nano
network by altering decisions made by consensus previously.

Nano accounts are referred to by address.  A Nano address starts with the
prefix
.RB \(dq nano_ "\(dq or \(dq" xrb_ \(dq.
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
.IR wallet .
A
.I wallet
is a conceptual entity that is used to refer to a
.IR seed ,
which is a random 256-bit number that can be used to derive mulitple
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
.RI \(dq raw \(dq.
The most common unit for users to use is called
.RI \(dq Nano \(dq,
one of which is equal to 1e30 raw.

.SH PROCEDURES
.SS Addresses
.TP
.B ::nano::address::toPublicKey
.I address
.RB ? -hex | -binary ?
661
662
663
664
665
666
667





668
669
670
671
672





673
674
675
676
677
678
679















680
681
682
683
684



















685
686
687
688
689













690
691
692
693
694
695
696
697




698
699
700
701
702





703
704
705
706
707
708
709
710
711




712
713
714
715
716
717
718





719
720














721
722
723
724
725
726
727
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782

783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889







+
+
+
+
+





+
+
+
+
+







+
+
+
+
+
+
+
+
+
+
+
+
+
+
+




-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+





+
+
+
+
+
+
+
+
+
+
+
+
+








+
+
+
+





+
+
+
+
+









+
+
+
+







+
+
+
+
+


+
+
+
+
+
+
+
+
+
+
+
+
+
+







associated with that block that corresponds to the head of an account's chain.

.TP
.B :nano::account::getFrontier
.I account
.RI " -> " 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
.IR account .

.TP
.B :nano::account::getFrontier
.I account
.RB ? frontierHash | balance | representative ?
.RI " -> " 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
.IR account .

.TP
.B :nano::account::addPending
.I account
.I blockHash
.I amount

This procedure is used as part of the High-level Account interface.  It is
used to indicate than a given
.I account
has a
.B receive
block that they could create.  The block hash of the corresponding
.B send
block should be supplied as the
.I blockHash
parameter.  The amount of Nano that was sent in the
.B send
block should be specified as the
.I amount
parameter (in units of raw).

.TP
.B :nano::account::getPending
.I account
.RI ? blockHash ?
.RI " -> " listOfDicts
.RI " -> " dict

This procedure is used as part of the High-level Account interface.  It is
used to retrieve information stored by
.B addPending 
for a given
.IR account .
If the
.I blockHash
parameter is supplied then a Tcl dictionary is returned with a key called
.B amount
which contains the amount stored previously.  If the
.I blockHash
parameter is not supplied then a Tcl dictionary is returned with keys
corresponding to each block hash pending for the specified
.IR account ,
and containing a subordinate Tcl dictionary with a key called
.B amount
as previously described.

.TP
.B ::nano::account::clearPending
.I account
.RI ? 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
.B addPending
for a given
.IR account .
If the
.I blockHash
parameter is supplied then only the entry corresponding to that blockhash is
cleared, otherwise all entries for the specified
.I account
are cleared.

.TP
.B :nano::account::receive
.I account
.I blockHash
.I privateKey
.RI " -> " 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.

.TP
.B :nano::account::receiveAllPending
.I account
.I privateKey
.RI " -> " 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
.IR account .
Its interface is subject to change and not considered stable.

.TP
.B :nano::account::send
.I fromAccount
.I toAccount
.I amount
.I privateKey
.RI " -> " 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.

.TP
.B ::nano::account::setRepresentative
.I account
.I representative
.I privateKey
.RI " -> " 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
.IR account .
Its interface is subject to change and not considered stable.

.SH EXAMPLES
.SS Example 1
.EX
package require nano @@VERS@@

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"
}
.EE

.SS Example 2
.SS Example 3

.SH AUTHOR
.Sp
Roy Keene
.RI < rkeene@nano.org >