c-geek/ucoin-cli.md

## ucoin-cli.md

      
    Raw
  

              ucoin-cli.md
            
          
    ucoin

Installation

Node.js

uCoin is powered by Node.js v0.10+, so you need it installed first. Here is an example for Ubuntu installation:
$ sudo apt-get update
$ sudo apt-get install python-software-properties python g++ make
$ sudo add-apt-repository ppa:chris-lea/node.js
$ sudo apt-get update
$ sudo apt-get install nodejs
ucoin

$ sudo apt-get install dos2unix gnupg
$ sudo npm install vucoin -g
Test it using:
$ ucoin -s ucoin.twiced.fr -p 9101 peering

Currency: beta_brousouf
Public key FPR: C73882B64B7E72237A2F460CE9CAB76D19A8651E
Contract: 2-09BA3E2EE604E169FCBE4A53AD66CF28E439FAF2
Public keys: 4
Remote host: localhost
Remote ipv4: 88.163.127.43
Remote port: 8081
Usage

Prerequisites

PGP key

To use ucoin software, you will need a PGP key generated with the tools of your choice. A simple way to get one is to install seahorse software and generate a new PGP key. There is no particular requirement at the moment on the format of the key.
Existing ucoin server

ucoin is a command-line client for ucoin servers. Thus, you either need:

to find an existing server accepting your key for a given currency
to build your own server for an existing currency (or for creating a new one)

The server will be identified using its IP/DNS + port.
In this example, we consider the following node:

address ucoin.twiced.fr
port 9101
currency beta_brousouf

Publish your key

Once your key is generated, you can publish it to a the node using the following command:
$ ucoin -s ucoin.twiced.fr -p 9101 -u nameOfYourKey send-pubkey
If things went well, you should get the message:
Posted key 'FINGERPRINT_OF_YOUR_KEY' of USER_ID_OF_YOUR_KEY

If not, try on another node which will accept your PGP key.

A node is not forced to accept any incoming key, it may have its own rules on how to accept them.


So if your key is refused by a node, you should try to understand why and maybe contact the node's administrators.

Note: if you are testing with ucoin.twiced.fr node, you can see that your key was successfully published here.
Tip: create a command alias

For commodity purposes, and as you might always use the same key and server, you could create a command alias using:
$ alias ucoin='ucoin -s ucoin.twiced.fr -p 9101 -u nameOfYourKey'
This say « when typing ucoin, use ucoin -s ucoin.twiced.fr -p 9101 -u nameOfYourKey instead ». We consider this is what is used for the rest of this document.
Join an the Community

What you did is just to publish your key, for uCoin to authentify futur messages you might send to it. Now, you can either:

Just handle money others send to you, using transactions
Or ask to join the Community, contacting existing members to check joining modalities

Note that if you are creating your own server and currency, you might also want to create your monetary contract. Below is described how to do so.
Create your own contract

If you are building your own server, the next step is to create your own contract in order to build your own community with people you know.
1. forge your first amendment

First of all, you need to get fingerprints of the keys you want to use for contract initialization, i.e. members fingerprints and voters fingerprints.
Here is an example:


We want to create a two members Community

Member 1 : 2E69197FAB029D8669EF85E82457A1587CA0ED9C

Member 2 : 33BBFC0C67078D72AF128B5BA296CC530126F372


One of the members will also be a voter (hence control Contract's evolution)

Voter 1 : 2E69197FAB029D8669EF85E82457A1587CA0ED9C


No Universal Dividend is generated in a first time


ucoind is running on localhost:9001


To create corresponding amendment, run:
$ echo "+33BBFC0C67078D72AF128B5BA296CC530126F372+2E69197FAB029D8669EF85E82457A1587CA0ED9C;+2E69197FAB029D8669EF85E82457A1587CA0ED9C" | ucoin -s localhost -p 9001 -n 1 -C forge-am > amendment0
2. Submit the voter's public key to uCoin

You are about to vote, that is, sign the amendment with voter's public key and submit it to uCoin. OK. But to do so, uCoin need to get voter's public key to verify vote's signature.
To do so:
$ ucoin -s localhost -p 9001 -u tobi send-pubkey

Une phrase de passe est nécessaire pour déverrouiller la clef secrète de
l'utilisateur : « Tobi Uchiwa (udid2;c;UCHIWA;OBITO;2000-09-30;e+35.69+139.69;0) <cem.moreau@gmail.com> »
clef RSA de 2048 bits, identifiant 7CA0ED9C, créée le 2013-06-23

Posted key '2E69197FAB029D8669EF85E82457A1587CA0ED9C' of Tobi Uchiwa (udid2;c;UCHIWA;OBITO;2000-09-30;e+35.69+139.69;0) <cem.moreau@gmail.com>

Note: you can see this key contains udid2 string udid2;c;UCHIWA;OBITO;2000-09-30;e+35.69+139.69;0. Such a comment value is absolutely NOT required. Any valid PGP key may be used.
3. Vote for generated amendment

Finally, to sumbit this amendment to your uCoin instance, just do:
$ ucoin -s localhost -p 9001 -u tobi vote amendment0
------------------------
Amendment to sign:
------------------------
Version: 1
Currency: beta_brousouf
Number: 0
GeneratedOn: 1385288649638
NextRequiredVotes: 1
MembersRoot: DC7A9229DFDABFB9769789B7BFAE08048BCB856F
MembersCount: 2
MembersChanges:
+2E69197FAB029D8669EF85E82457A1587CA0ED9C
+33BBFC0C67078D72AF128B5BA296CC530126F372
VotersRoot: 2E69197FAB029D8669EF85E82457A1587CA0ED9C
VotersCount: 1
VotersChanges:
+2E69197FAB029D8669EF85E82457A1587CA0ED9C
------------------------
You are about to vote for this amendment by signing and sending it. Do wish to continue? [y/n] y
Signing amendment...

Une phrase de passe est nécessaire pour déverrouiller la clef secrète de
l'utilisateur : « Tobi Uchiwa (udid2;c;UCHIWA;OBITO;2000-09-30;e+35.69+139.69;0) <cem.moreau@gmail.com> »
clef RSA de 2048 bits, identifiant 7CA0ED9C, créée le 2013-06-23

Posted vote for Amendment #0

Congratulations, your uCoin instance now have a valid Monetary Contract !
Update your contract

Need to add new members ? Change voters ? Create a Universal Dividend ? Just create and submit a new amendment:
New member(s)

$ echo "+C73882B64B7E72237A2F460CE9CAB76D19A8651E" | ucoin -s localhost -p 9001 -n 1 -C forge-am > amendment1
Note: you may add as many members at once as you want, by just concatenating them.
Exclude member(s)

Same as add, but with a - (minus) before key fingerprint.
$ echo "-33BBFC0C67078D72AF128B5BA296CC530126F372" | ucoin -s localhost -p 9001 -n 1 -C forge-am > amendment1
New voter(s)

$ echo ";+C73882B64B7E72237A2F460CE9CAB76D19A8651E" | ucoin -s localhost -p 9001 -n 1 -C forge-am > amendment2
Note: here, the char ; is delimiting members part from voters part: members changes are on the left, while voters are on the right.
Exclude voters(s)

Same as add, but with a - (minus) before key fingerprint.
$ echo ";-C73882B64B7E72237A2F460CE9CAB76D19A8651E" | ucoin -s localhost -p 9001 -n 1 -C forge-am > amendment2
Require more votes to valid next amendment

Until there, we used -n 1 option, which means next amendment only require 1 vote to be promoted in Monetary Contract. But in a Community, we might use some democratic process with several voters.
Hence, precising 2 votes are required to promote next amendment may be precised with option -n:
$ ucoin -s localhost -p 9001 -n 2 forge-am > amendment3
Create a Universal Dividend

Option -d <amount> allows members to create new money. For example, if we allow each members to create 100 units of money:
$ ucoin -s localhost -p 9001 -n 2 -d 100 forge-am > amendment3
Give threshold for newly issued coins

To avoid abuses, it might be precised in the Contract what is the minimum value a coin may have to be created. This is precised using option -m <minimum_power_value>.
For example, if we want future coins to be created with a minimum amount of 10:
$ ucoin -s localhost -p 9001 -n 2 -m 1 forge-am > amendment3
All at once

Of course, you may do all of this at once: adding members/voters, exclude some, create a Universal Dividend with coins of a minimum value and change required number of votes for next amendment acceptation.
Transactions : issue new money

According to moment you get in the Community, you may already have the right to create new coins. If you know the amendment number justifying this right, then you can enter the following:
$ ucoin issue 2 3,1 "Issuing one coin of value 30"
Where 2 is the amendment number justifying your issuance, and 3,1 signifies « A coin of value 3 with 1 zero behind ».
This command should ask you the passphrase of your key for signing, and result with:
Posted issuance transaction

if operation succeed.
Transactions : list your coins

Want to check how many coins you own ? Just use:
$ ucoin clist
Credit: 50
-------------------

Value Issuer                                   #

30    33BBFC0C67078D72AF128B5BA296CC530126F372 0
10    33BBFC0C67078D72AF128B5BA296CC530126F372 1
10    2E69197FAB029D8669EF85E82457A1587CA0ED9C 0
You may filter to an upper limit, for example to exclude coin 30:
$ ucoin clist 10
Credit: 20
-------------------

Value Issuer                                   #

10    33BBFC0C67078D72AF128B5BA296CC530126F372 1
10    2E69197FAB029D8669EF85E82457A1587CA0ED9C 0
Transactions : transfer your coins

Want to pay someone ? Just use the following command:
$ ucoin cget 10,10 | ucoin transfer 33BBFC0C67078D72AF128B5BA296CC530126F372 "Paying for the milk"

Posted transfer transaction
This asks to send two coins of value 10 to key 33BBFC0C67078D72AF128B5BA296CC530126F372.
Transactions : fusion your coins

Too many coins with too little value? Use coin fusion:
$ ucoin cget 10,10 | ucoin fusion "Too much coins"

Posted fusion transaction
Transactions : divide your coins

Not the good values? Need smaller coins? Use coin division:
$ ucoin cget 10,10 | ucoin divide 5,0,5,0,5,0,2,0,2,0,1,0 "Need smaller! 10+10 to 5+5+5+2+2+1"

Posted division transaction
Trust entry: declare your own

Declare hosting nodes

As part of the uCoin protocol, any key may issue a document called THT entry allowing a given key to declare a list of trusted nodes for hosting all key's transaction. Which means, a list of nodes any transaction of the key will go through, becoming privilidged places to check the coins owned by a given key.
To do so, use ucoin host-add and host-rm to make a list of nodes you will declare as hosting nodes.
Use the following command to add a node as hosting node:
$ ucoin -u nameOfYourKey host-add NODE_FINGERPRINT
For example:
$ ucoin -u tobi host-add 86F7E437FAA5A7FCE15D1DDCB9EAEAEA377667B8
In the other way, use host-rm to remove it:
$ ucoin -u tobi host-rm 86F7E437FAA5A7FCE15D1DDCB9EAEAEA377667B8
All this stuff is locally done. To publish it, use pub-tht command:
$ ucoin -u tobi pub-tht
Posted THT entry.
Declare trusted nodes

In addition to hosting nodes, which are rather an help for other people to trust your transaction database state, you may also declare a list of trusted nodes. This information is made for other people to known which nodes you are prone to trust for receiving transactions.
N.B.: this information is absolutely note mandatory, just like hosting nodes, but may be a precious information for other people.
To do so, use trust-* commands which are just siblings of host-* commands to manage trust entries:
$ ucoin -u tobi trust-add 86F7E437FAA5A7FCE15D1DDCB9EAEAEA377667B8
In the other way, use trust-rm to remove it:
$ ucoin -u tobi trust-rm 86F7E437FAA5A7FCE15D1DDCB9EAEAEA377667B8
To publish it, use the same command as for hosting nodes, i.e. pub-tht.
Check THT entry

At any moment, to verify what you are going to send, you may check the content of your THT entry with the following command:
$ ucoin -u tobi tht

Hosters:
394EA2F4ACB60280F7EADC6F6C5D479E6C669563
86F7E437FAA5A7FCE15D1DDCB9EAEAEA377667B8
C73882B64B7E72237A2F460CE9CAB76D19A8651E
D049002A6724D35F867F64CC087BA351C0AEB6DF
DE3800B793426FEDF087AE625E88EDD3B35505A1
Trusts:
C73882B64B7E72237A2F460CE9CAB76D19A8651E
D049002A6724D35F867F64CC087BA351C0AEB6DF