/extra/hashcash/hashcash-docs.factor

 1USING: help.markup help.syntax kernel math ;
 2IN: hashcash
 3
 4ARTICLE: "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
33HELP: mint
34{ $values { "resource" "a string" } { "stamp" "generated stamp" } }
35{ $description "This word generate a valid stamp with default parameters and the specified resource." } ;
36
37HELP: mint*
38{ $values { "tuple" "a tuple" } { "stamp" "generated stamp" } }
39{ $description "As " { $snippet "mint" } " but it takes an hashcash tuple as a parameter." } ;
40
41HELP: check-stamp
42{ $values { "stamp" "a string" } { "?" boolean } }
43{ $description "Check for stamp's validity. Only supports hashcash version 1." } ;
44
45HELP: salt
46{ $values { "length" integer } { "salted" "a string" } }
47{ $description "It generates a random string of " { $snippet "length" } " characters." } ;
48
49HELP: <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
53HELP: hashcash
54{ $class-description "An hashcash object. An hashcash have the following slots:"
55    { $table
56        { { $slot "version" } "The version number. Only version 1 is supported." }
57        { { $slot "bits" } "The claimed bit value." }
58        { { $slot "date" } "The date a stamp was minted." }
59        { { $slot "resource" } "The resource for which a stamp is minted." }
60        { { $slot "ext" } "Extensions that a specialized application may want." }
61        { { $slot "salt" } "A random salt." }
62        { { $slot "suffix" } "The computed suffix. This is supposed to be manipulated by the library." }
63    }
64} ;