extra/hashcash/hashcash-docs.factor

   1 USING: help.markup help.syntax kernel math strings ;
   2 IN: hashcash
   3
   4 ARTICLE: "hashcash" "Hashcash"
   5 "Hashcash is a denial-of-service counter measure tool."
   6 $nl
   7 "A hashcash stamp constitutes a proof-of-work which takes a parameterizable amount of work to compute for the sender. The recipient can verify received hashcash stamps efficiently."
   8 $nl
   9 "More info on hashcash:"
  10 $nl
  11 { $url "http://www.hashcash.org/" } $nl
  12 { $url "http://en.wikipedia.org/wiki/Hashcash" } $nl
  13 { $url "http://www.ibm.com/developerworks/linux/library/l-hashcash.html?ca=dgr-lnxw01HashCash" } $nl
  14 "This library provide basic utilities for hashcash creation and validation."
  15 $nl
  16 "Creating stamps:"
  17 { $subsections
  18     mint
  19     mint*
  20 }
  21 "Validation:"
  22 { $subsections check-stamp }
  23 "Hashcash tuple and constructor:"
  24 { $subsections
  25     hashcash
  26     <hashcash>
  27 }
  28 "Utilities:"
  29 { $subsections salt } ;
  30
  31 { mint mint* <hashcash> check-stamp salt } related-words
  32
  33 HELP: mint
  34 { $values { "resource" string } { "stamp" "generated stamp" } }
  35 { $description "This word generate a valid stamp with default parameters and the specified resource." } ;
  36
  37 HELP: mint*
  38 { $values { "tuple" "a tuple" } { "stamp" "generated stamp" } }
  39 { $description "As " { $snippet "mint" } " but it takes an hashcash tuple as a parameter." } ;
  40
  41 HELP: check-stamp
  42 { $values { "stamp" string } { "?" boolean } }
  43 { $description "Check for stamp's validity. Only supports hashcash version 1." } ;
  44
  45 HELP: salt
  46 { $values { "length" integer } { "salted" string } }
  47 { $description "It generates a random string of " { $snippet "length" } " characters." } ;
  48
  49 HELP: <hashcash>
  50 { $values { "tuple" object } }
  51 { $description "It fill an hashcash tuple with the default values: 1 as hashcash version, 20 as bits, today's date as date and a random 8 character long salt" } ;
  52
  53 HELP: hashcash
  54 { $class-description "An hashcash object. An hashcash have the following slots:"
  55     { $slots
  56         { "version" "The version number. Only version 1 is supported." }
  57         { "bits" "The claimed bit value." }
  58         { "date" "The date a stamp was minted." }
  59         { "resource" "The resource for which a stamp is minted." }
  60         { "ext" "Extensions that a specialized application may want." }
  61         { "salt" "A random salt." }
  62         { "suffix" "The computed suffix. This is supposed to be manipulated by the library." }
  63     }
  64 } ;