client.html

   1 <html>
   2 <head>
   3 <link rel="stylesheet" type="text/css" href="css/docstyle.css">
   4 <title>A Trubanc Web Client</title>
   5 </head>
   6 <body>
   7 <h1>A Trubanc Web Client</h1>
   8
   9 <p>
  10 I have written a <a href="./">Trubanc</a> web client, mostly as an
  11 example of how to use the
  12 <a href="viewtext.php?file=lib%2Fclient.php&search=&numbers=Yes">
  13 client API</a>, but it's also a useful tool for maintaining multiple
  14 Trubanc accounts on multiple Trubanc servers. This page uses sampled
  15 screen-shots from the client to teach you how to use it. You can
  16 follow those links within the text, or simply go to
  17 <a href="./client/">Trubanc.com/client</a> to create a new account.
  18 </p>
  19
  20 <p>
  21 If you're interested in technical details of what goes on behind the
  22 scenes, this page is organized in about the same way as
  23 <a href="plain-english.html">
  24 Trubanc in Plain English</a>.
  25
  26 <p>
  27 Disclaimer: This site has a fully-functional Trubanc client and
  28 server, but you wouldn't want to store any real money here. First off,
  29 you enter your passphrase into the client, unencrypted, so it's
  30 visible to anyone who can see your web traffic. You COULD install the
  31 client on your own computer and get rid of that problem, but the
  32 Trubanc server on this machine is under development, so I may
  33 occasionally break things. Plus, it's hosted on a machine in Arizona,
  34 under the watchful guns of the United States government. They have a
  35 nasty habit of deciding to steal people's property, because of made up
  36 "crimes" of "money laundering", or "operating a money tranfer service
  37 without a license" or "tax evasion". I hope that there will one day
  38 soon be many real Trubanc servers to choose from, hosted outside of
  39 the influence of the US government, and backed up daily to prevent
  40 lossage. For now, though, please use this site only to become
  41 accustomed to Trubanc, and to help me test it.
  42 </p>
  43
  44 <span class="summary-header">Note</span>
  45 <p id="summary">
  46 If you just want to learn the Trubanc web client by doing, follow the
  47 directions in the gray boxes titled "Summary".
  48 </p>
  49
  50 <h2>Opening an Account</h2>
  51
  52 <p>
  53 When you first go to the client web page, you'll see the
  54 <a href="demo/">Login screen</a>. Once you've created an account,
  55 simply enter your passphrase and click the "Login" button (or press
  56 the "Enter" or "Return" key on your keyboard). But first, you need to
  57 create public key pair. Click the "Register a new account" link on the
  58 login screen to go to the
  59 <a href="demo/register.html">
  60 Registration screen</a>.
  61 </p>
  62
  63 <p>
  64 Trubanc uses
  65 <a href="http://www.pgpi.org/doc/pgpintro/">
  66 public key</a>
  67 <a href="http://en.wikipedia.org/wiki/Public-key_cryptography">
  68 cryptography</a> to identify you in all communication with the server,
  69 and to ensure that the server you reach over the internet today is the
  70 same one you reached yesterday. With Trubanc, your private key,
  71 stored, encrypted with your passphrase, on the machine that hosts the
  72 client, <i>is</i> your identity. Guard it well. I will soon write
  73 instructions for installing the client on your PC. But if you use one
  74 over the internet, make sure it's over an encrypted (https)
  75 link. Protect your passphrase like your gold. If somebody gets it, and
  76 your encrypted private key, or access to a public client site holding
  77 your private key, they are <i>you</i> as far as a Trubanc server is
  78 concerned. But without it, <i>nobody</i> can impersonate you.
  79 </p>
  80
  81 <p>
  82 To create your identity, you must first pick a passphrase. This should
  83 be a longish sequence of words that you can remember, but that it
  84 would be unlikely for anyone to guess. It's best to use your memory,
  85 not a piece of paper, to remember your passphrase. Pick a good one,
  86 and don't forget it. If you do, you've lost your identity and access
  87 to any assets stored in accounts keyed to it. Unless you picked a
  88 really easy passphrase, nobody can recover it for you. That's a good
  89 thing. There's a random-word passphrase generator on the
  90 <a href="https://loom.cc/?function=folder_tools">
  91 Loom Tools</a> page. Press the "Random" button in the "Passphrase"
  92 line.
  93 </p>
  94
  95 <p>
  96 In order to protect Trubanc clients and servers from spammers, you'll
  97 also need to enter a "Coupon". A Trubanc coupon is a portable store of
  98 value. Coupons are usually used to give usage tokens to people who
  99 want to open new accounts, but they can be minted in any asset
 100 type. After you use one you get from a friend or the bank proprieter
 101 to create an account, you can mint your own on the
 102 <a href="demo/balance.html">
 103 balance screen</a>, and fund new accounts for your friends.
 104 </p>
 105
 106 <p>
 107 Enter your passphrase twice, once in the "Passphrase" field, and again
 108 in the "Verification" field. Paste your "Coupon". Pick a "Key
 109 size". RSA Labs
 110 <a href="http://www.rsa.com/rsalabs/node.asp?id=2004">thinks</a> that
 111 a key size of 3072 bits should be secure until beyond the year
 112 2031. So that's the default. Smaller sizes are a little faster to
 113 generate, and use, but only a little. It hardly matters for a key that
 114 you'll only be using on this site to play with the interface. Finally,
 115 press the "Create account" button. It takes a few seconds to generate
 116 a new passphrase, so be patient.
 117 </p>
 118
 119 <span class="summary-header">Summary</span>
 120 <ul id="summary">
 121 <li>Get a usage token coupon from somebody.</li>
 122 <li>Pick a passphrase.</li>
 123 <li>Go to
 124 <a href="client/">trubanc.com/client</a></li>
 125 <li>Click the "Register a new account" link to go to the registration
 126   screen.
 127 <li>Enter your "Passphrase" and "Verification".</li>
 128 <li>Paste the "Coupon".</li>
 129 <li>Press the "Create account" button.</li>
 130 </ul>
 131
 132 <h2>Receiving Assets</h2>
 133
 134 <p>
 135 The
 136 <a href="demo/balance.html">Balance screen</a> is where you spend most
 137 of your quality Trubanc time. It lets you see spends from others that
 138 you haven't yet acknowledged, spends from yourself that the recipient
 139 has acknowledged and you haven't yet completed, and your current
 140 balances in all the assets you possess. It also has a "Show raw
 141 balance" link, which brings up the
 142 <a href="demo/rawbalance.html">
 143 raw balance screen</a>. This shows the low-level encodings of the
 144 signed and countersigned messages in your inbox, outbox, and
 145 balances. Unless you're a Trubanc developer, you probably won't need
 146 to look at this much.
 147 </p>
 148
 149 <p>
 150 After you add a new bank, you'll see at least two spends. One will be
 151 from the coupon from your sponsor, for enough usage tokens to cover the
 152 registration fee. The other will be a negative spend from the bank for
 153 that registration fee. In Trubanc, the bank can't simply change your
 154 balance behind your back. All balances and spends are signed by you
 155 and countersigned by the bank. So in order to change your balance, you
 156 must explicity make or accept spends. If someone spends assets to you
 157 that you don't want, e.g. to purchase something that you no longer
 158 sell, you can choose to reject that spend.
 159 </p>
 160
 161 <p>
 162 A Trubanc transaction has three steps:
 163 </p>
 164 <ol>
 165 <li>A makes a spend to B.</li>
 166 <li>B accepts or rejects the spend.</li>
 167 <li>A closes the transaction.</li>
 168 </ol>
 169
 170 <p>
 171 The "<b>=== Inbox ===</b>" section of the balance screen has six
 172 columns:
 173 <ol>
 174 <li><b>Request:</b> this is "Spend" for spends other people made to you, or
 175   "Accept" or "Reject" for acknowledgements of spends you made to
 176   others.</li>
 177 <li><b>From:</b> This contains the name or ID of the other person. If
 178   you've given him a nickname on the
 179 <a href="demo/contacts.html">Contacts screen</a>, that will appear. If
 180 he also has an account name, that will appear in parentheses. If the
 181 other person is not amongst your contacts, a "Nickname" text box
 182 will allow you to add him.</li>
 183 <li><b>Amount:</b> The amount that was spent in this transaction. If
 184   you see "<span style="color: red;"><i>(new)</i></span>" after the
 185   asset name, that means that you have never credited any amounts of
 186   this asset type to your account. This can help you avoid accepting
 187   counterfeit assets (same name, but different ID).</li>
 188 <li><b>Note:</b> The note in the original spend for this
 189   transaction. For acknowledgement lines, this is your original spend note.</li>
 190 <li><b>Action:</b> the action you want to perform on this line when
 191   you press the "Process Inbox" button.</li>
 192 <li><b>Reply:</b> you may type a reply here for spends, and you'll see
 193   the other person's reply here for acknowledgements of your spends.</li>
 194 </ol>
 195
 196 <p>
 197 To accept or reject or skip a spend, select what you want to do in
 198 each row's "Action" column. To prevent the server database from
 199 filling up, you're not allowed to do a new spend until you've cleared
 200 your inbox, but you can keep some spends around until then by skipping
 201 them.
 202 </p>
 203
 204 <p>
 205 To remove a spend acknowledgement from your inbox, closing the
 206 transaction, check the "Remove" box in its "Action" column.
 207 </p>
 208
 209 <p>
 210 Click the "Process Inbox" button to perform the corresponding "Action"
 211 to each row.
 212 </p>
 213
 214 <span class="summary-header">Summary</span>
 215 <ul id="summary">
 216 <li>Go to the
 217 <a href="demo/balance.html">
 218 Balance screen</a>.
 219 <li>In the "Action" column, select an action for each spend and unclick
 220   the "Remove" boxes for acknowledgements you wish to keep.</li>
 221 <li>Type a "Reply" for each accepted or rejected spend that needs
 222   one.</li>
 223 <li>Click the "Process Inbox" button.</li>
 224 </ul>
 225
 226 <h2>Adding Contacts</h2>
 227
 228 <p>
 229 The Trubanc server keeps track of customers by their ID, the SHA1 hash of
 230 their public keys. Remembering 40-character hex strings tends to be
 231 hard for most of us humans, though, so the web client allows you to
 232 associate nicknames with your contacts. The
 233 <a href="demo/contacts.html">
 234 Contacts screen</a> shows you contacts that you have added in the past
 235 and allows you to add new ones. This is so simple that I'll just put
 236 it in the summary. You can also add a contact from the "Inbox" section
 237 of the
 238 <a href="demo/balance.html">
 239 Balance screen</a>, or during a spend, by fillin in the "Nickname" box
 240 in the inbox "From" column. or near the bottom of the spend form. This
 241 will add a new contact with a blank nickname and notes. You'll
 242 probably want to visit the Contacts screen to add those, especially if
 243 the customer has no Account Name.
 244 </p>
 245
 246 <span class="summary-header">Summary</span>
 247 <ul id="summary">
 248 <li>Go to the
 249 <a href="demo/contacts.html">
 250 Contacts screen</a>.
 251 <li>Paste your contact's "ID".<li>
 252 <li>If you want, type a "Nickname".</li>
 253 <li>If you want, type some "Notes".</li>
 254 <li>Press the "Add/Change Contact" button.</li>
 255 <li>If the ID is new, a contact will be added. If it already exists,
 256   the Nickname and Notes of the existing contact will be updated, if
 257   non-blank. To remove a nickname or note, type a single space in that
 258   field.</li>
 259 </ul>
 260
 261 <h2>Spending Assets</h2>
 262
 263 <p>
 264 All tranfers are sent and received on the
 265 <a href="demo/balance.html">
 266 Balance screen</a>. The "Receiving Assets" section above dealt with
 267 the "Inbox", This section deals with the "Balances" and "Outbox"
 268 sections.
 269 </p>
 270
 271 <p>
 272 Spends are pretty well documented below the "Balances" and spend form:
 273 </p>
 274 <blockquote>
 275 <p>
 276 To make a spend, fill in the "Spend amount", choose a "Recipient" or
 277 enter a "Recipient ID, enter (optionally) a "Note", and click the
 278 "Spend" button next to the asset you wish to spend.
 279 </p>
 280
 281 <p>
 282 To transfer balances, enter the "Spend Amount", select or fill-in the
 283 "Transfer to" name (letters, numbers, and spaces only), and click the
 284 "Spend" button next to the asset you want to transfer from. Each
 285 storage location costs one usage token, and there is currently no way
 286 to recover an unused location. 0 balances will show only on the raw
 287 balance screen.
 288 </p>
 289
 290 <p>
 291 To mint a coupon, enter the "Spend Amount", check the "Mint coupon"
 292 box, and click the "Spend" button next to the asset you want to
 293 transfer to the coupon. You can redeem a coupon on the "Banks" page.
 294 </p>
 295
 296 <p>
 297 Entering a "Nickname" will add the "Recipient ID" to your contacts
 298 list with that nickname, or change the nickname of the selected
 299 "Recipient".
 300 </p>
 301 </blockquote>
 302
 303 <p>
 304 Trubanc lets you split up your balances into multiple
 305 sub-accounts. You start off with just one, named "main". You can add
 306 more by tranferring to them as described above.
 307 </p>
 308
 309 <p>
 310 The "Outbox" section, below the spend instructions shows pending
 311 spends and coupons. The word "coupon" is a link to a page that shows
 312 that coupon, for easy copy and paste. When you mint a coupon, you'll
 313 be taken automatically to the new coupon's page. To redeem a coupon,
 314 paste it into the "Bank URL or Coupon" box on the
 315 <a href="demo/banks.html">
 316 Banks screen</a>, and click the "Add bank" button.
 317 </p>
 318
 319 <p>
 320 Spends that have not yet been accepted or rejected, and coupons that
 321 have not yet been redeemed, can be cancelled by pressing the "Cancel"
 322 button in that row of the "Outbox" section. Cancelled spends will come
 323 into your inbox just as if the recipient had rejected them, except the
 324 bank will pocket the transaction fee, to discourage this as a regular
 325 practice. Cancelled coupons will come into your inbox as a regular
 326 spend, as if you had redeemed the coupon. You'll need to accept the
 327 spend, and acknowledge the acceptance, as two "Process Inbox" button
 328 presses.
 329 </p>
 330
 331 <span class="summary-header">Summary</span>
 332 <ul id="summary">
 333 <li>Go to the
 334 <a href="demo/balance.html">
 335 Balance screen</a>.</li>
 336 <li>Enter the "Spend amount".</li>
 337 <li>Choose a "Recipient" or paste in his "Recipient ID".</li>
 338 <li>Type a "Nickname" if you want to add or change it.</li>
 339 <li>Click the "Spend" button next to the asset you want to spend.</li>
 340 </ul>
 341
 342 <h2>Adding a Bank</h2>
 343
 344 <p>
 345 To create an account at a new bank, or add an existing bank account to
 346 a new client, use the
 347 <a href="demo/banks.html">
 348 Banks screen</a>. To create a new account, or to redeem it in an
 349 existing account, paste a coupon into "Bank URL or Coupon". For a
 350 new account, if you want the account to be named, enter an "Account
 351 name". To add an existing account at another bank to a client that
 352 doesn't have it, enter the bank's URL as the "Bank URL or Coupon",
 353 instead of a coupon. Then press the "Add Bank" button.
 354 </p>
 355
 356 <span class="summary-header">Summary</span>
 357 <ul id="summary">
 358 <li>Acquire a coupon with usage tokens for the new bank.
 359 <li>Go to the
 360 <a href="client/?cmd=banks">Banks screen</a>.</li>
 361 <li>Paste the coupon into "Bank URL or Coupon".</li>
 362 <li>Enter an "Account Name", if you want to identify yourself with
 363 other than your ID.</li>
 364 <li>Press the "Add Bank" button.</li>
 365 </ul>
 366
 367 <h2>Preventing Spam</h2>
 368
 369 <p>
 370 Since a spend requires two files, an outbox entry for the spender and
 371 an inbox entry for the recipient, the spender is charged two usage
 372 tokens to make the spend. That pays the bank for disk space (storage
 373 fees and non-refundable transaction fees will come soon). If the
 374 recipient accepts the spend, the spender will get those usage tokens
 375 back when he closes the transaction. If the recipient rejects the
 376 spend, he, not the spender, gets the usage tokens.
 377 </p>
 378
 379 <p>
 380 A zero spend, with an attached note is very similar to an email. If it
 381 were free, spammers would be able to fill your Trubanc inbox with
 382 garbage. Since rejecting that spam message will cost the spammer two
 383 tokens, it will cost him money to keep doing it. This should
 384 discourage spam. I'll eventually add a feature where you can choose to
 385 give back the usage tokens with a rejected spend. Until then, you'll
 386 need to explicitly spend them back, except to spammers. An easy way to
 387 spend back usage tokens is to do a zero spend with a note to the
 388 recipient to reject the spend and take the tokens.
 389 </p>
 390
 391 <h2>Issuing Assets</h2>
 392
 393 <p>
 394 Many Trubanc banks will issue their own assets. Many of the existing
 395 digital gold currencies work that way. But, like
 396 <a href="https://loom.cc/">Loom</a>, Trubanc allows anyone to issue a
 397 currency. If you convince enough people that your currency is stable
 398 and accepted by enough people, they'll use it. Creating your new asset
 399 type is very easy. On the
 400 <a href="demo/assets.html">
 401 Assets screen</a>, you'll see a list of all the assets that are or
 402 ever were in your account. You can fill in the form with your new
 403 asset's "Scale", "Precision", and "Asset Name", and press the "Add
 404 Asset" button. "Scale" is the number of digits kept track
 405 of to the right of the decimal point. "Precision" is the minimum
 406 number of decimal places that will be printed, even if they're all
 407 zero. "Scale" must be greater than or equal to "Precision". Most
 408 GoldGram-like curencies use a scale of 7 and a precision of 3. The
 409 "Asset name" can be whatever you like. In the demo Trubanc, it costs
 410 two usage tokens to create a new asset type.
 411 </p>
 412
 413 <p>
 414 When you create a new asset, it will appear in your "main"
 415 sub-account, with a balance of "-0". Negative balances are for assets
 416 you issue. You can spend as much of such an asset as you like, but
 417 people will trust your asset a lot better if you never spend more of
 418 it that you can back with the commodity you've choosen to back it.
 419 </p>
 420
 421 <p>
 422 You can move asset issuance to another sub-account, or transfer it to
 423 another person, by doing a spend for the entire negative amount. So,
 424 right after asset creation, when your balance is "-0.000" in  your
 425 "main" sub-account, you can type "-0" as the "Spend amount" on the
 426 <a href="demo/balance.html">
 427 Balance screen</a>, and select either a "Recipient" or a "Transfer to"
 428 sub-account. If you transfer issuance to another person, you'll likely
 429 want to inform your asset holders of the change. It could have an
 430 effect on the perceived value of your asset.
 431 </p>
 432
 433 <span class="summary-header">Summary</span>
 434 <ul id="summary">
 435 <li>Go to the
 436 <a href="demo/assets.html">
 437 Assets page</a>.</li>
 438 <li>Enter a "Scale", "Precision", and "Asset name".</li>
 439 <li>Press the "Add Asset" button.</li>
 440 </ul>
 441
 442 <h2>Keeping History</h2>
 443
 444 <p>I plan to add history to the client soon. Until then, once you've
 445   cleared a transaction from your account, it's gone.</p>
 446
 447 <p>Copyright &copy; 2008 Bill St. Clair, All Rights Reserved</p>
 448
 449 </body>
 450 </html>