├── ApplicationIdentity.md ├── DeveloperGuide ├── DeveloperGuide.md ├── data_structures.md ├── factom-cli.md ├── hello_world.md ├── install.md └── intro.md ├── DistributedPseudonymousOracles.pdf ├── FactoidAPI.md ├── FactomAPI.pdf ├── FactomAPI_Chinese.md ├── FactomAPI_Chinese.pdf ├── FactomLedgerbyConsensus.pdf ├── FactomOracle.pdf ├── Factom_FAQ.pdf ├── Factom_Whitepaper.pdf ├── Factom_Whitepaper_Errata.md ├── Factom_Whitepaper_Japanese.pdf ├── Factom_Whitepaper_v1.2.pdf ├── Factom_Whitepaper_v1.2_FR.pdf ├── Identity.md ├── LICENSE ├── README.md ├── SpecialChains.md ├── communityTesterDirections.md ├── developerSandboxSetup.md ├── examples └── tax │ ├── ERS_privatekey.txt │ ├── ERS_publickey.txt │ ├── Encrypted_Biden_Tax_Return.txt │ ├── Encrypted_Obama_Tax_Return.txt │ ├── README.md │ ├── Unencrypted_Biden_Tax_Return.txt │ └── Unencrypted_Obama_Tax_Return.txt ├── factomDataStructureDetails.md ├── factomFullInstall.md ├── images ├── Keymaker1.png ├── Keymaker10.png ├── Keymaker11.png ├── Keymaker12.png ├── Keymaker13.png ├── Keymaker14.png ├── Keymaker15.png ├── Keymaker16.png ├── Keymaker17.png ├── Keymaker2.png ├── Keymaker3.png ├── Keymaker4.png ├── Keymaker5.png ├── Keymaker6.png ├── Keymaker7.png ├── Keymaker8.png ├── Keymaker9.png ├── Whitepaper---Entries-Blocks-written-as-Factom-Blocks.png ├── Whitepaper---Factom---Proof-of-Existance-Layer.png ├── Whitepaper---Factom-Complete-System.png ├── Whitepaper---Factom-Layer-Diagram.png ├── Whitepaper---Hashes-and-Data-are-Written-to-Entry-Blocks.png ├── chain-structure.png ├── controlpanel.png ├── factom-cli.png ├── factomd.png └── fctwallet.png ├── installFromSourceDirections.md ├── legacyWallets.md ├── wallet_info ├── bip44_test.py ├── token_sale │ ├── README.md │ └── words_to_factoid_purchase.py └── wallet_test_vectors.md └── whitepaper.md /ApplicationIdentity.md: -------------------------------------------------------------------------------- 1 | # Application Identity 2 | Not to be confused with Server Identities used within the context of Factomd Consensus. This document describes a generic identity system for use in applications where an Identity is a structured chain that keeps an auditable history of public keys and when they were activated or retired. 3 | 4 | ## Identity Key Pair 5 | 6 | For Factom Application Identities, ed25519 keys are used to sign and verify messages. Rather than simply using raw 32 byte arrays for keys, the following encoding scheme is used: 7 | 8 | Pseudo-code for constructing a private key string: 9 | ``` 10 | prefix_bytes = [0x03, 0x45, 0xf3, 0xd0, 0xd6] // gives an "idsec" prefix once in base58 11 | key_bytes = [32 bytes of raw private key] // the actual ed25519 private key seed 12 | checksum = sha256( sha256(prefix_bytes + key_bytes) )[:4] // 4 byte integrity check on the previous 37 bytes 13 | 14 | idsec_key_string = base58( prefix_bytes + key_bytes + checksum ) 15 | ``` 16 | 17 | Pseudo-code for constructing a public key string: 18 | ``` 19 | prefix_bytes = [0x03, 0x45, 0xef, 0x9d, 0xe0] // gives an "idpub" prefix once in base58 20 | key_bytes = [32 bytes of raw public key] // the actual ed25519 public key 21 | checksum = sha256( sha256(prefix_bytes + key_bytes) )[:4] // 4 byte integrity check on the previous 37 bytes 22 | 23 | idpub_key_string = base58( prefix_bytes + key_bytes + checksum ) 24 | ``` 25 | 26 | For the sake of human-readability, all characters must be in Bitcoin's base58 character set, the private key will always begin with "idsec", and the public key will always begin with "idpub". Additionally, the checksum at the end serves to signal that a user has incorrectly typed/copied their key. 27 | 28 | Example key pair for the private key of all zeros: 29 | - `idsec19zBQP2RjHg8Cb8xH2XHzhsB1a6ZkB23cbS21NSyH9pDbzhnN6 idpub2Cy86teq57qaxHyqLA8jHwe5JqqCvL1HGH4cKRcwSTbymTTh5n` 30 | 31 | Example key pair for the private key of all ones: 32 | - `idsec1ARpkDoUCT9vdZuU3y2QafjAJtCsQYbE2d3JDER8Nm56CWk9ix idpub2op91ghJbRLrukBArtxeLJotFgXhc6E21syu3Ef8V7rCcRY5cc` 33 | 34 | ## Identity Chain 35 | As mentioned above, an Identity is a chain with a specific structure. The ExtIDs of the first entry contain the tag "IdentityChain", followed by any user specified byte arrays (human-readable or otherwise) that make up the Identity Name. The initial public Identity Keys are contained within a JSON object in the Content field of the same entry, the first key string being highest priority (i.e. a master-key) and last being lowest priority. 36 | 37 | First Entry Structure: 38 | - ExtID[0] = "IdentityChain" 39 | - ExtID[1] = *Identity Name 1* 40 | - ... 41 | - ExtID[N] = *Identity Name N* 42 | - Content = {"version": 1, "keys": ["idpub2Cy86teq57qaxHyqLA8jHwe5JqqCvL1HGH4cKRcwSTbymTTh5n", "idpub2op91ghJbRLrukBArtxeLJotFgXhc6E21syu3Ef8V7rCcRY5cc"]} 43 | 44 | Where "idpub2Cy8..." is of higher priority than "idpub2op9..." 45 | 46 | ## Identity Key Replacement 47 | A Key Replacement is performed by creating a structured entry in the Identity's chain. This entry will tell us that from this point on (the block that the entry is in), the old key will be considered invalid and the new key will be considered valid. In order to reconstruct the current set of active keys for an Identity, one would parse through the chain's entries validating and executing these key replacement entries in the order that they appear. 48 | 49 | Rules for a Valid Replacement Entry: 50 | - The entry must strictly follow the below External ID format 51 | - Old key must be currently active for the identity of interest 52 | - New key must have never been active for the identity of interest (for any priority level) 53 | - Signer key must be currently active and of the same or higher priority than the old key 54 | - Multiple key replacements included in the same block must be parsed in the exact order that they appear in the block 55 | - A key replacement entry that resides outside of the Identity's chain will not be taken into consideration when determining which keys were valid at a given block height 56 | 57 | Entry Structure: 58 | - ExtID[0] = "ReplaceKey" 59 | - ExtID[1] = Old key string 60 | - ExtID[2] = New Key string 61 | - ExtID[3] = bytes of signature( identity chain id + ExtID[1] + ExtID[2] ) 62 | - ExtID[4] = Key string used to sign the above 63 | 64 | A function to the tune of "GetKeysAtHeight" would be used to parse a given Identity's chain (according to the above rules) in order to determine which keys were recognized as active at a certain point in time (a block height). This can be used to validate that an entry signed by an Identity was constructed using an authorized key pair. 65 | -------------------------------------------------------------------------------- /DeveloperGuide/DeveloperGuide.md: -------------------------------------------------------------------------------- 1 | Getting Started with Factom on Linux 2 | === 3 | 4 | This guide is for technical users who are interested in learning about Factom. By following this guide you will learn the basics of using Factom, and building simple applications that read and write data to and from the Factom Blockchain. 5 | 6 | In this guide you will learn how to: 7 | * install Factom 8 | * understand Factom data structures and design patterns 9 | * buy Factoids 10 | * convert Factoids into Entry Credits 11 | * create Factom Chains and Entries 12 | * read data from Factom 13 | * create a simple Factom application 14 | 15 | Make sure you understand... 16 | --- 17 | This guide uses factom-cli commands on a command shell as well as library/api calls in some example applications. You will need to be familier with opening a shell and issuing commands to use the factom-cli to create and read Factom Entries. You do not need to be an expert programmer but you will need to understand some common programming concepts to create and run applications that interact with Factom. 18 | 19 | Installing Factom 20 | === 21 | The fastest way to install Factom is to use the Factom installation package provided by [http://factom.org](). The package contains binaries for factomd, fctwallet, and factom-cli. 22 | 23 | Download the factom [installer package](http://factom.org/downloads/factom.deb) for Debian GNU/Linux. 24 | 25 | $ wget http://factom.org/downloads/factom.deb 26 | 27 | Run the Factom Installer. The binaries have been built for 32 bit systems to ensure compatability with older hardware, so on 64 bit systems you must add the ``--force-architecture`` option when installing. 28 | 29 | $ sudo dpkg --force-architecture -i ./factom.deb 30 | 31 | Check that the packages have been installed into their correct locations. 32 | 33 | $ which factomd 34 | /usr/bin/factomd 35 | 36 | $ which fctwallet 37 | /usr/bin/fctwallet 38 | 39 | $ which factom-cli 40 | /usr/bin/factom-cli 41 | 42 | Once the Factom Binaries have been installed successfully, run ``$ factomd`` and let it sync with the Factom network. This may take a little time if it is the first time running factomd on a new machine. 43 | 44 | Buying Factoids 45 | === 46 | If you have a Factoid or Entry Credit private key (a Factoid private key will begin with FS, an Entry Credit key, with ES) you may import the address into your wallet using factom-cli. 47 | 48 | $ factom-cli importaddress myFactoids01 'FS...' 49 | 50 | If you participated in the original factoid sale on Koinify you may import your 12 words. 51 | 52 | $ factom-cli importaddress myFactoids02 'yellow yellow yellow yellow yellow yellow yellow yellow yellow yellow yellow yellow' 53 | 54 | Converting Factoids into Entry Credits 55 | === 56 | Entry Credits allow data to be written into Factom. Each Entry Credit address represents a key pair that allows signing of payments for data to be written into the Factom network. Factoids are converted into Entry Credits by adding 1 or more ecoutputs to a transaction. 57 | 58 | Run ``$ factomd`` and ``$ fctwallet``. 59 | 60 | Use factomcli to create an Entry Credit address. The EC address in this example will be called app01. 61 | 62 | $ factom-cli generateaddress ec app01 63 | ec = EC2gigrpHsADYXbnGDhBf58z8isuiT8HffZT1gFfcQERzon4SD44 64 | 65 | Create a new transaction 'a'. 66 | 67 | $ factom-cli newtransaction a 68 | 69 | Add 10 factoids as an input to the transaction from the Factoid address we created earlier. 70 | 71 | $ factom-cli addinput a myFactoids01 10 72 | 73 | Add 10 Factoids as the amount to convert into Entry Credits. 74 | 75 | $ factom-cli addecoutput a app01 10 76 | 77 | Pay the transaction fee from the same Factoid address 78 | 79 | $ factom-cli addfee a myFactoids01 80 | 81 | Sign and submit the transaction to the Factom network. 82 | 83 | $ factom-cli sign a 84 | $ factom-cli submit a 85 | 86 | After 10 minutes you should see the Entry Credits at the new address. 87 | 88 | $ factom-cli balance ec app01 89 | Balance of app01 = 1010 90 | 91 | Once the Entry Credit address has been loaded with credits it may be used to create Factom Entries and Chains. 92 | 93 | Understanding Factom data structures. 94 | === 95 | 96 | Entries 97 | --- 98 | User data in the Factom network is organized into Entries and Chains. A Factom Entry is composed of a ChainID, 0 or more External IDs, and the Entry Content. The External IDs and Content are binary data but it is most common to write decoded text into these fields. It is up to the application to interpret the Entries. A Factom application may write data into the External IDs and Entry Content and then parse or interpret the data any way it likes. 99 | 100 | Entry Blocks 101 | --- 102 | Comming Soon! 103 | 104 | Chains 105 | --- 106 | A Factom Chain is a series of Factom Entries. When a new Entry is commited and revealed to the Factom network, it is added to the an Entry Block for its specified Chain. At the end of each 10 minute period all of the new Entry Blocks are combined into the Directory Block, then anchored into the Bitcoin Blockchain. 107 | 108 | Hello World! 109 | === 110 | 111 | Creating a new Factom Entry 112 | --- 113 | In the first example a new Entry is constructed then sent to the Factom network. Notice that the ExtIDs, and Entry Content are []byte not string. This allows the Entries to contain binary data. For example an ExtID may be a key or a key signature. 114 | 115 | package main 116 | 117 | import ( 118 | "log" 119 | "time" 120 | 121 | "github.com/FactomProject/factom" 122 | ) 123 | 124 | func main() { 125 | e := factom.NewEntry() 126 | e.ChainID = "5c337e9010600c415d2cd259ed0bf904e35666483277664d869a98189b35ca81" 127 | e.ExtIDs = append(e.ExtIDs, []byte("hello")) 128 | e.Content = []byte("Hello Factom!") 129 | 130 | if err := factom.CommitEntry(e, "app01"); err != nil { 131 | log.Fatal(err) 132 | } 133 | time.Sleep(10 * time.Second) 134 | if err := factom.RevealEntry(e); err != nil { 135 | log.Fatal(err) 136 | } 137 | } 138 | 139 | The easiest way to create Factom applications in golang is to import the factom package. 140 | 141 | import ( 142 | //... 143 | "github.com/FactomProject/factom" 144 | ) 145 | 146 | Create a new ``factom.Entry`` and fill in the relevent data. We will be adding this Entry to a testing Chain ``5c337e9010600c415d2cd259ed0bf904e35666483277664d869a98189b35ca81``. the first External ID for the Entry will be "hello" and the Entry Content will be "Hello Factom!". 147 | 148 | e := factom.NewEntry() 149 | e.ChainID = "5c337e9010600c415d2cd259ed0bf904e35666483277664d869a98189b35ca81" 150 | e.ExtIDs = append(e.ExtIDs, []byte("hello")) 151 | e.Content = []byte("Hello Factom!") 152 | 153 | Once the Entry is ready we send the Commit Message to the Factom network. The Commit is process by fctwallet and signed with the Entry Credit address specified here. 154 | 155 | if err := factom.CommitEntry(e, "app01"); err != nil { 156 | log.Fatal(err) 157 | } 158 | 159 | It is not strictly nessesary to wait between the Commit Message and the Reveal, but waiting reduces the chance of errors. When we are ready we reveal the Entry. 160 | 161 | if err := factom.RevealEntry(e); err != nil { 162 | log.Fatal(err) 163 | } 164 | 165 | If there are no errors, the Entry will be included in the current 10 minute Entry Block for the specified Chain. After the end of the current 10 minutes the Entry Block containing the Entry will be hashed and included into the Directory Block which will then be anchored into the Bitcoin Blockchain. 166 | 167 | Creating a new Factom Chain 168 | --- 169 | A new Factom Chain is created by constructing an Entry to be the first Entry of the new Chain, then constructing the Chain from the Entry. The Chain is then Commited and Revealed to the Factom network. 170 | 171 | package main 172 | 173 | import ( 174 | "log" 175 | "time" 176 | 177 | "github.com/FactomProject/factom" 178 | ) 179 | 180 | func main() { 181 | e := factom.NewEntry() 182 | e.ExtIDs = append(e.ExtIDs, []byte("MyChain"), []byte("12345")) 183 | e.Content = []byte("Hello Factom!") 184 | 185 | c := factom.NewChain(e) 186 | log.Println("Creating new Chain:", c.ChainID) 187 | 188 | if err := factom.CommitChain(c, "app01"); err != nil { 189 | log.Fatal(err) 190 | } 191 | time.Sleep(10 * time.Second) 192 | if err := factom.RevealChain(c); err != nil { 193 | log.Fatal(err) 194 | } 195 | } 196 | 197 | Since a new Chain is being created the Entry may be constructed without the ChainID field. The new ChainID will be computed using the ExtIDs of the Entry. Remember that the ExtIDs of the first Entry of a Chain must be unique among all first Entries. A new Chain cannot be created if a Chain with the same ChainID already exists. 198 | 199 | e := factom.NewEntry() 200 | e.ExtIDs = append(e.ExtIDs, []byte("MyChain"), []byte("12345")) 201 | e.Content = []byte("Hello Factom!") 202 | 203 | c := factom.NewChain(e) 204 | 205 | The ChainID will be printed to the screen. 206 | 207 | log.Println("Creating new Chain:", c.ChainID) 208 | 209 | ``Creating new Chain: cfa35f22d4790a3f3121d6cc192da26813ee29cb0f8ad220fbe3563fa9d351d1`` 210 | 211 | Reading data from Factom 212 | === 213 | 214 | Key signed application 215 | === 216 | -------------------------------------------------------------------------------- /DeveloperGuide/data_structures.md: -------------------------------------------------------------------------------- 1 | Understanding Factom Data Structures. 2 | === 3 | 4 | User data in the Factom network is organized into Entries and Chains. Entries hold the user data, and Chains associate Entries with one another over time. 5 | 6 | * Anyone may write an Entry into any existing Chain 7 | * An Entry must be associated with a Chain 8 | * All Entry Content and External IDs are visible to anyone 9 | * An Entry may contain any binary data up to 10KB 10 | * It is up to the application to interperate the Entry Content and External IDs 11 | 12 | Entries 13 | --- 14 | A Factom Entry is composed of: 15 | - A ChainID, 16 | - 0 or more External IDs, and 17 | - Entry Content. 18 | 19 | The External IDs and Content are binary data but it is most common to write decoded text into these fields. It is up to the application to interpret the Entries. A Factom application may write any data into the External IDs and Entry Content and parse or interpret the data any way it likes. All Entries of a given Chain in a 10 minute block of time are hashed and bundled into an Entry Block for the given Chain. 20 | 21 | Chains 22 | --- 23 | Factom Chains are essentially mini Blockchains for individual applications. Chains may be used by applications to: 24 | - find the Entries they are interested in, 25 | - prove that Entries were made, and 26 | - prove that certain Entries were never added to the Chain. 27 | 28 | ![chain-structure] (https://github.com/FactomProject/FactomDocs/blob/master/images/chain-structure.png) 29 | 30 | Chains consist of a series of Entry Blocks, one for every 10 minute period where new Entries were added to the Chain. When a new Entry is commited and revealed to the Factom network, its hash is added to the Entry Block for the specified Chain. At the end of the 10 minute period all of the new Entry Blocks for all Chains are combined into one Directory Block, which is then anchored into the Bitcoin and Ethereum Blockchains. If there are no new Entries for a Chain in a given 10 minute period, no new Entry Block is added for the Chain. 31 | 32 | A new Chain is created by constructing a First Entry which establishes the new ChainID. The first Entry is a normal Entry with the added reqirement that its collective External IDs must be unique among all first Entries for all existing Chains. The first Entry Content has no additional restrictions, but by convention it may be used to describe the Chain and post relevant information on processing the Chain. For example the first Entry may prescribe a format that future Entries' Content must follow to be considered valid by the application, or it may post a public key by which all valid Entries in the Chain must be signed. 33 | 34 | More Info 35 | --- 36 | For more information on Entries, Chains, Entry Blocks, and internal Factom data structures, see the [Factom Whitepaper](https://github.com/FactomProject/FactomDocs/blob/master/Factom_Whitepaper.pdf) 37 | -------------------------------------------------------------------------------- /DeveloperGuide/factom-cli.md: -------------------------------------------------------------------------------- 1 | Using factom-cli 2 | === 3 | factom-cli is the command line interface for interacting with the factom daemon and the factom wallet daemon. factom-cli may be used to write new data into Factom, read data from Factom, and manage Factoids and Entry Credits in the Factom Wallet. 4 | 5 | Getting Entry Credits 6 | --- 7 | Entry Credits are required to write Chains and Entries into Factom. A testing Address may be used to obtain Entry Credits when running Factom in testing mode, seperate from the true Factom Network. 8 | 9 | Once factomd is running in SERVER mode and factom-walletd has been started the testing Address may be imported with its private key. 10 | 11 | $ factom-cli importaddress Fs3E9gV6DXsYzf7Fqx1fVBQPQXV695eP3k5XbmHEZVRLkMdD9qCK 12 | FA2jK2HcLnRdS94dEcU27rF3meoJfpUcZPSinpb7AwQvPRY6RL1Q 13 | $ factom-cli listaddresses 14 | FA2jK2HcLnRdS94dEcU27rF3meoJfpUcZPSinpb7AwQvPRY6RL1Q 300 15 | 16 | It is convinient to assign the Public Address to a Bash variable for future operations. 17 | $ f1=FA2jK2HcLnRdS94dEcU27rF3meoJfpUcZPSinpb7AwQvPRY6RL1Q 18 | 19 | A new Entry Credit Address may be created and stored in the wallet. Again, it is convinient to save the Entry Credit Address as a variable for later use. 20 | * create new ec address 21 | $ factom-cli newecaddress 22 | EC2jF4CQZNriM8Z78YPMNrZFBEsHGrgdfnUN2gbLBgTJwtneMFbU 23 | $ e1=EC2jF4CQZNriM8Z78YPMNrZFBEsHGrgdfnUN2gbLBgTJwtneMFbU 24 | 25 | Entry Credits are purchased for the new Entry Credit Address using the Factoid Address that was imported before. The Public Factoid Address is used to query the wallet which returns the Private Key to factom-cli to sign the transaction that purchases Entry Credits. Factoids may only be spent with the factom-cli using Factoid Addresses that are stored in the factom-walletd database. 26 | 27 | $ factom-cli buyec $f1 $e1 10000 28 | TxID: 1b300a370573cf130e82a00bf3924d0c81ee79dac12e477bf0a4c2c44062c79f 29 | $ factom-cli listaddresses 30 | FA2jK2HcLnRdS94dEcU27rF3meoJfpUcZPSinpb7AwQvPRY6RL1Q 289.988 31 | EC2jF4CQZNriM8Z78YPMNrZFBEsHGrgdfnUN2gbLBgTJwtneMFbU 10000 32 | 33 | Creating Chains and Entries 34 | --- 35 | A new Chain can now be created using the newly aquired Entry Credits. The External IDs of the First Entry of a Chain MUST be unique among all existing First Entrys. If Factom is being run in testing mode it is unlilkely that the Chain Name will be taken, but it is good practace to include a random nonce anyway. 36 | 37 | A new Chain is created by Writing a unique First Entry. 38 | 39 | $ echo Hello Factom | factom-cli addchain -e Hello -e $(openssl rand -base64 10) $e1 40 | Commiting Chain Transaction ID: ae4b5ec092072c54b55a5c06b9662d65a85f5683c5962abbffb7129a488dba29 41 | ChainID: e6a766a9bd9a40a708d85b8523ca55a179fa681853f49941c3456296e605c4b5 42 | Entryhash: 3b5d63a87f2435cc017f824cfa370cd6a9064f6721912d6dd990e429128a7ca9 43 | 44 | Getting the Chain Head will show the most recent Entry Block belongin to the Chain. If the Entry Block is the first Entry Block in the Chain the Previous Key Merkel Root will be all zeros, otherwise the Previous Key Merkel Root will be the Merkel Root of the Previous Entry Block in the Chain. 45 | 46 | $ factom-cli get chainhead e6a766a9bd9a40a708d85b8523ca55a179fa681853f49941c3456296e605c4b5 47 | EBlock: e3f876b40bd641f863a88d2c8299a58d6b749f9ea53f70327fef1659673e72e1 48 | BlockSequenceNumber: 0 49 | ChainID: e6a766a9bd9a40a708d85b8523ca55a179fa681853f49941c3456296e605c4b5 50 | PrevKeyMR: 0000000000000000000000000000000000000000000000000000000000000000 51 | Timestamp: 1472749920 52 | DBHeight: 111 53 | EBEntry { 54 | Timestamp 1472750280 55 | EntryHash 3b5d63a87f2435cc017f824cfa370cd6a9064f6721912d6dd990e429128a7ca9 56 | } 57 | 58 | More Entries can be added to the Chain once it has been created. Additional Entries into the Chain need not have a unique set of External IDs. 59 | 60 | $ echo Hello again | factom-cli addentry -c e6a766a9bd9a40a708d85b8523ca55a179fa681853f49941c3456296e605c4b5 $e1 61 | Commiting Entry Transaction ID: a2fbbc9e3beb8f7d6274d761df0645d07c8c56de41045e6f8fff1292f380e3bd 62 | ChainID: e6a766a9bd9a40a708d85b8523ca55a179fa681853f49941c3456296e605c4b5 63 | Entryhash: d2628343f63c4cdbd0122d0563acf3f2a9331ebf56212476b02930ee863c7691 64 | 65 | Reading Factom Chains 66 | --- 67 | The factom-cli can retrive the First Entry of any Chain. By convention the First Entry of a Chain may contain usefull information about the Chains purpose, and/or how the Chains Entries are to be interperated or validated. 68 | 69 | $ factom-cli get firstentry e6a766a9bd9a40a708d85b8523ca55a179fa681853f49941c3456296e605c4b5 70 | ChainID: e6a766a9bd9a40a708d85b8523ca55a179fa681853f49941c3456296e605c4b5 71 | ExtID: Hello 72 | ExtID: j4vLmL/jH2bflw== 73 | Content: 74 | Hello Factom 75 | 76 | The factom-cli may also be used to get all of the Entries in an existing Chain. 77 | 78 | $ factom-cli get allentries e6a766a9bd9a40a708d85b8523ca55a179fa681853f49941c3456296e605c4b5 79 | Entry [0] { 80 | ChainID: e6a766a9bd9a40a708d85b8523ca55a179fa681853f49941c3456296e605c4b5 81 | ExtID: Hello 82 | ExtID: j4vLmL/jH2bflw== 83 | Content: 84 | Hello Factom 85 | 86 | } 87 | Entry [1] { 88 | ChainID: e6a766a9bd9a40a708d85b8523ca55a179fa681853f49941c3456296e605c4b5 89 | Content: 90 | Hello again 91 | 92 | } 93 | 94 | Specific Entries or Entry Blocks may also be requested using factom-cli 95 | 96 | $ factom-cli get entry 3b5d63a87f2435cc017f824cfa370cd6a9064f6721912d6dd990e429128a7ca9 97 | ChainID: e6a766a9bd9a40a708d85b8523ca55a179fa681853f49941c3456296e605c4b5 98 | ExtID: Hello 99 | ExtID: j4vLmL/jH2bflw== 100 | Content: 101 | Hello Factom 102 | 103 | $ factom-cli get eblock e3f876b40bd641f863a88d2c8299a58d6b749f9ea53f70327fef1659673e72e1 104 | BlockSequenceNumber: 0 105 | ChainID: e6a766a9bd9a40a708d85b8523ca55a179fa681853f49941c3456296e605c4b5 106 | PrevKeyMR: 0000000000000000000000000000000000000000000000000000000000000000 107 | Timestamp: 1472749920 108 | DBHeight: 111 109 | EBEntry { 110 | Timestamp 1472750280 111 | EntryHash 3b5d63a87f2435cc017f824cfa370cd6a9064f6721912d6dd990e429128a7ca9 112 | } 113 | -------------------------------------------------------------------------------- /DeveloperGuide/hello_world.md: -------------------------------------------------------------------------------- 1 | Hello World! 2 | === 3 | 4 | The easiest way to create Factom entries and chains programatically is to use the [factom library](http://github.com/FactomProject/factom) for golang. Install and setup the Go environment using the [installation instructions](https://golang.org/doc/install) provided by [golang.org](http://golang.org). Import the [factom package](https://github.com/FactomProject/factom) with ``go get github.com/FactomProject/factom``. 5 | 6 | Creating a new Factom Entry 7 | --- 8 | In the first example a new Entry is constructed then sent to the Factom network. Notice that the ExtIDs, and Entry Content are ``[]byte`` not ``string``. This allows the Entries to contain binary data. For example an ExtID may be a key or a key signature. 9 | 10 | package main 11 | 12 | import ( 13 | "log" 14 | "time" 15 | 16 | "github.com/FactomProject/factom" 17 | ) 18 | 19 | func main() { 20 | e := factom.NewEntry() 21 | e.ChainID = "5c337e9010600c415d2cd259ed0bf904e35666483277664d869a98189b35ca81" 22 | e.ExtIDs = append(e.ExtIDs, []byte("hello")) 23 | e.Content = []byte("Hello Factom!") 24 | 25 | if err := factom.CommitEntry(e, "App-01"); err != nil { 26 | log.Fatal(err) 27 | } 28 | time.Sleep(10 * time.Second) 29 | if err := factom.RevealEntry(e); err != nil { 30 | log.Fatal(err) 31 | } 32 | } 33 | 34 | Create a new ``factom.Entry`` and fill in the relevent data. We will be adding this Entry to a testing Chain ``5c337e9010600c415d2cd259ed0bf904e35666483277664d869a98189b35ca81``. The first External ID for the Entry will be "hello" and the Entry Content will be "Hello Factom!". 35 | 36 | e := factom.NewEntry() 37 | e.ChainID = "5c337e9010600c415d2cd259ed0bf904e35666483277664d869a98189b35ca81" 38 | e.ExtIDs = append(e.ExtIDs, []byte("hello")) 39 | e.Content = []byte("Hello Factom!") 40 | 41 | Once the Entry is ready we send the Commit Message to the Factom network. The Commit is process by fctwallet and signed with the Entry Credit Address specified here. 42 | 43 | if err := factom.CommitEntry(e, "App-01"); err != nil { 44 | log.Fatal(err) 45 | } 46 | 47 | It is not strictly nessesary to wait between the Commit Message and the Reveal, but waiting reduces the chance of errors. When we are ready we reveal the Entry. 48 | 49 | if err := factom.RevealEntry(e); err != nil { 50 | log.Fatal(err) 51 | } 52 | 53 | If there are no errors, the Entry will be included in the current 10 minute Entry Block for the specified chain. After the end of the current 10 minutes the Entry Block containing the Entry will be hashed and included into the Directory Block which will be anchored into the Bitcoin Blockchain. 54 | 55 | Creating a new Factom Chain 56 | --- 57 | A new Factom Chain is created by constructing an Entry to be the first Entry of the new Chain, then constructing the Chain from the Entry. The Chain is then commited and revealed to the Factom network. 58 | 59 | package main 60 | 61 | import ( 62 | "log" 63 | "time" 64 | 65 | "github.com/FactomProject/factom" 66 | ) 67 | 68 | func main() { 69 | e := factom.NewEntry() 70 | e.ExtIDs = append(e.ExtIDs, []byte("MyChain"), []byte("12345")) 71 | e.Content = []byte("Hello Factom!") 72 | 73 | c := factom.NewChain(e) 74 | log.Println("Creating new Chain:", c.ChainID) 75 | 76 | if err := factom.CommitChain(c, "App-01"); err != nil { 77 | log.Fatal(err) 78 | } 79 | time.Sleep(10 * time.Second) 80 | if err := factom.RevealChain(c); err != nil { 81 | log.Fatal(err) 82 | } 83 | } 84 | 85 | Since a new Chain is being created the Entry may be constructed without the ChainID field. The new ChainID will be computed using the ExtIDs of the Entry. Remember that the ExtIDs of the first Entry of a Chain must be unique among all first Entries (A new Chain cannot be created if a Chain with the same ID already exists). 86 | 87 | e := factom.NewEntry() 88 | e.ExtIDs = append(e.ExtIDs, []byte("MyChain"), []byte("12345")) 89 | e.Content = []byte("Hello Factom!") 90 | 91 | c := factom.NewChain(e) 92 | 93 | The ChainID will be printed to the screen. 94 | 95 | log.Println("Creating new Chain:", c.ChainID) 96 | 97 | ``Creating new Chain: cfa35f22d4790a3f3121d6cc192da26813ee29cb0f8ad220fbe3563fa9d351d1`` 98 | -------------------------------------------------------------------------------- /DeveloperGuide/install.md: -------------------------------------------------------------------------------- 1 | Installing Factom 2 | === 3 | The fastest way to install Factom is to use the Factom installation package provided by [factom.org](http://factom.org). The package contains binaries for factomd, factom-walletd, and factom-cli. 4 | 5 | Download the factom [installer package](https://github.com/FactomProject/distribution) for Debian GNU/Linux. 6 | 7 | $ wget https://github.com/FactomProject/distribution/releases/download/v0.3.7.0/factom.deb 8 | 9 | Run the Factom Installer. The binaries have been built for 32 bit systems to ensure compatability with older hardware, so on 64 bit systems you must add the ``--force-architecture`` option when installing. 10 | 11 | $ sudo dpkg --force-architecture -i factom.deb 12 | 13 | Check that the packages have been installed into their correct locations. 14 | 15 | $ which factomd 16 | /usr/bin/factomd 17 | 18 | $ which fctwallet 19 | /usr/bin/fctwallet 20 | 21 | $ which factom-cli 22 | /usr/bin/factom-cli 23 | 24 | Once the Factom Binaries have been installed successfully, run ``$ factomd`` and let it sync with the Factom network. This may take some time if it is the first time running factomd on a new machine. 25 | 26 | You are now running a factom client on your machine! 27 | 28 | Installing on a Mac 29 | --- 30 | TODO 31 | -------------------------------------------------------------------------------- /DeveloperGuide/intro.md: -------------------------------------------------------------------------------- 1 | Getting Started with Factom 2 | === 3 | 4 | This guide is for developers and technical user who are interested in learning about building Factom applications and scripts. By following this guide you will learn the basics of using Factom to build simple applications that read and write data to and from the Factom Blockchain. 5 | 6 | In this guide you will learn how to: 7 | * install Factom 8 | * understand Factom data structures and design patterns 9 | * buy Factoids 10 | * convert Factoids into Entry Credits 11 | * create Factom Chains and Entries 12 | * read data from Factom 13 | * create a simple Factom application 14 | 15 | Make sure you understand... 16 | --- 17 | This guide uses factom-cli commands on a command shell as well as library/api calls in some example applications. You will need to be familier with opening a shell and issuing commands to use the factom-cli to create and read Factom Entries. You do not need to be an expert programmer but you will need to understand some common programming concepts to create and run applications that interact with Factom. 18 | -------------------------------------------------------------------------------- /DistributedPseudonymousOracles.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/DistributedPseudonymousOracles.pdf -------------------------------------------------------------------------------- /FactoidAPI.md: -------------------------------------------------------------------------------- 1 | Factoid API 2 | =========== 3 | 4 | Note: This documentation is outdated. The latest documentation is located here: https://docs.factom.com/api 5 | 6 | 7 | This document does a quick summary of the API for Factoids and the Factoid wallet. At this point in time 8 | the wallet is a commandline driven program, intended to demonstrate the API more than to be a viable 9 | commerical wallet solution. 10 | 11 | The first step is to install the factom client and factom wallet helpers. See the [How To](http://factom.org/howto) 12 | guides for setting up in your environment. You will need to run factomd and fctwallet. Note that from time to 13 | time over the next few months you will need to update factomd to continue to communicate 14 | with the network. Watch our [technical blog](http://blog.factom.org/) for notifications and updates. 15 | 16 | The two APIs that are of interest are implemented by factomd and fctwallet. The first, **factomd**, is the client 17 | program that actually participates in the Factom Network. The second, **fctwallet**, provides common wallet 18 | functions, and it maintains the address book where private keys are kept. A third program, **walletapp**, provides 19 | for cold wallets, the generation of offline transactions, and the submission of offline transactions to 20 | the factom network. 21 | 22 | The factom client **factomd** provides a RESTful interface found at http://localhost:8088 by default. None of the calls to 23 | factomd present any security issues, so factomd does not have to be colocated with programs creating and 24 | submitting transactions. 25 | 26 | The factom wallet **fctwallet** provides a RESTful interface found at http://localhost:8089 by default. Calls to 27 | fctwallet allow for the creation of transactions against factoid addresses held in its wallet. Access to the 28 | API then must be kept secure. 29 | 30 | The factom wallet **walletapp** is an alternative that only supports factoid functions. It communicates only 31 | with factomd. The *walletapp* supports cold storage, construction of offline transactions, and the submission 32 | of offline transaction to the factom network. We will soon be releasing a GUI that will run on top of the 33 | *walletapp* that will provide support for general factoid users. 34 | 35 | The factom commandline wallet **factom-cli** is a wallet that supports factoid transactions, as well as 36 | general access to the Factom protocol. *factom-cli* uses the interfaces to *factomd* and *fctwallet* to 37 | implement its functionality. The main purpose of this program is to demonstrate the use of the factom 38 | APIs. It can also be used to script transaction processes against Factom. 39 | 40 | Note: Examples of the API calls provided below can be executed in command line directly if curl is installed. The API calls have been prefixed with curl -X POST or curl -X GET depending on method. 41 | 42 | factomd 43 | ------- 44 | 45 | This is a summary of the factomd API as pertains to trading Factoids. We will add detail on other calls as we go forward. 46 | 47 | + Post **http://localhost:8088/v1/commit-chain/?** 48 | 49 | Commits a chain. The first step towards creating a new chain. 50 | 51 | fctwallet API 'compose-chain-submit' needs to be called first to get the CommitChainMsg which is the input for this API. 52 | For Example: 53 | 54 | A call to compose-entry-submit API returns a JSON object 55 | 56 | ``` 57 | $ curl -X POST -H 'Content-Type: application/json' -d '{"ExtIDs":["466972737421", "7365636F6E64"], "Content":"48656C6C6F20466163746F6D21"}' localhost:8089/v1/compose-chain-submit/entrycreditaddressname 58 | ``` 59 | Returns 60 | 61 | {"ChainID":"28590424cc9dbe8957e576c492befff899274757658e2db14b3b34c646b47610","ChainCommit":{"CommitChainMsg":"00015386f1252f4f0db4ade591a7669451540daaaa77b21fef2881989729725c94a9ab44675e6a6e26695e5aa298fa3a7454d95960336c9ecb1b9a2fb30fba95996e193e26b8cc9e9a6f90bd86564bcc453055eac484a67794714a573dd969df4526daf0a971f80b3b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da2986deafdec8e0933e755e884fc16f71d52febcb3f0e6f00b1642b3332afac0f78c755b1588793cd4ce103c91031e73aed381c7cb55c5585640524123fd00e6c00"},"EntryReveal":{"Entry":"0028590424cc9dbe8957e576c492befff899274757658e2db14b3b34c646b476100010000646697273742100067365636f6e6448656c6c6f20466163746f6d21"}} 62 | 63 | The return value contains both the ChainCommit and the Entry Reveal. 64 | To Commit the Entry: 65 | 66 | $ curl -i -X POST -H 'Content-Type: application/json' -d '{"CommitChainMsg":"00015386f1252f4f0db4ade591a7669451540daaaa77b21fef2881989729725c94a9ab44675e6a6e26695e5aa298fa3a7454d95960336c9ecb1b9a2fb30fba95996e193e26b8cc9e9a6f90bd86564bcc453055eac484a67794714a573dd969df4526daf0a971f80b3b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da2986deafdec8e0933e755e884fc16f71d52febcb3f0e6f00b1642b3332afac0f78c755b1588793cd4ce103c91031e73aed381c7cb55c5585640524123fd00e6c00"}' localhost:8088/v1/commit-chain 67 | 68 | To Reveal the First Entry: 69 | 70 | $ curl -i -X POST -H 'Content-Type: application/json' -d '{"Entry":"0028590424cc9dbe8957e576c492befff899274757658e2db14b3b34c646b476100010000646697273742100067365636f6e6448656c6c6f20466163746f6d21"}' localhost:8088/v1/reveal-entry 71 | 72 | The Chain gets committed and first entry is made. 73 | 74 | + Post **http://localhost:8088/v1/reveal-chain/?** 75 | 76 | Reveal the first entry in a chain. Required to complete the construction of a new chain. 77 | The format of the API call is covered above. 78 | 79 | + Post **http://localhost:8088/v1/commit-entry/?** 80 | 81 | Commits an entry. The first step in writing an entry to a chain. 82 | 83 | fctwallet API 'compose-entry-submit' needs to be called first to get the CommitEntryMsg which is the input for this API. 84 | For Example: 85 | 86 | A call to compose-entry-submit API returns a JSON object 87 | 88 | ``` 89 | $ curl -i -X POST -H 'Content-Type: application/json' -d '{"ChainID":"28590424cc9dbe8957e576c492befff899274757658e2db14b3b34c646b47610", "ExtIDs":["657831", "657832"], "Content":"48656C6C6F20466163746F6D21"}' localhost:8089/v1/compose-entry-submit/entrycreditaddressname 90 | ``` 91 | 92 | Returns 93 | 94 | {"EntryCommit":{"CommitEntryMsg":"000153872b030f7ad8b3722c6f72508df028d0f2563cc711e0ccd7da749160e3d385216237b065013b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da29102270e0584dbe4c872980b7d6cb569d4fc35310b81219253b5b1e333d44ede92418fcddc61f9149cda737dcb6ebf3f5742327b42e9ce8bce08c697e6fdcda0b"},"EntryReveal":{"Entry":"0028590424cc9dbe8957e576c492befff899274757658e2db14b3b34c646b47610000a0003657831000365783248656c6c6f20466163746f6d21"}} 95 | 96 | The return value contains both the EntryCommit and the Entry Reveal. 97 | To Commit the Entry: 98 | 99 | $ curl -i -X POST -H 'Content-Type: application/json' -d '{"CommitEntryMsg":"000153872b030f7ad8b3722c6f72508df028d0f2563cc711e0ccd7da749160e3d385216237b065013b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da29102270e0584dbe4c872980b7d6cb569d4fc35310b81219253b5b1e333d44ede92418fcddc61f9149cda737dcb6ebf3f5742327b42e9ce8bce08c697e6fdcda0b"}' localhost:8088/v1/commit-entry 100 | 101 | Then Reveal the Entry: 102 | 103 | $ curl -i -X POST -H 'Content-Type: application/json' -d '{"Entry":"0028590424cc9dbe8957e576c492befff899274757658e2db14b3b34c646b47610000a0003657831000365783248656c6c6f20466163746f6d21"}' localhost:8088/v1/reveal-entry 104 | 105 | The entries are made to the ChainID provided. 106 | 107 | Note: ChainName can be provided instead of ChainID. However if the ChainID field has data, the ChainName field will be ignored. 108 | 109 | example json entry: 110 | {"ChainName":["466972737421", "7365636F6E64"], "ExtIDs":["657831", "657832"], "Content":"48656C6C6F20466163746F6D21"} 111 | 112 | is the same as 113 | 114 | {"ChainID":"28590424cc9dbe8957e576c492befff899274757658e2db14b3b34c646b47610", "ExtIDs":["657831", "657832"], "Content":"48656C6C6F20466163746F6D21"} 115 | 116 | + Post **http://localhost:8088/v1/reveal-entry/?** 117 | 118 | Reveal a new entry. Required to complete the writing of an entry into a chain. 119 | Format of the API call is covered above. 120 | 121 | + Post **http://localhost:8088/v1/factoid-submit/?** 122 | 123 | Submit transaction. Requires the encoded transaction as part of the call. For example, creating a transaction that sends 10 factoids from xxx to yyy might be encoded as: 124 | ``` 125 | curl -X POST -H 'Content-Type: application/json' -d '{"Transaction":"0201538741213601000183e0d3b160646f3e8750c550e4582eca5047546ffef89c13a175985e320232bacac81cc42883dceb94003b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da2901718b5edd2914acc2e4677f336c1a32736e5e9bde13663e6413894f57ec272e2830312c70f7aafecb55846014600f08eb8fe39b97e977ade4d86e1d6a6164af9ee1bda806fbdfc04db9bcc6c1bece954cfd9ed41defadf3505c14a532191f4d09"}' http://localhost:8088/v1/factoid-submit/ 126 | ``` 127 | That seems like a pretty complex construction of data. Most users will use fctwallet to construct this call. 128 | 129 | + Get **http://localhost:8088/v1/directory-block-head/?** 130 | 131 | Returns the hash of the directory block head. No parameters are needed. Returns a JSON string of the form: 132 | ``` 133 | {"KeyMR":"f7eb0456b30b1a4b50867a5307532e92ddee7279ffc955ce1284cd142f94d642"} 134 | ``` 135 | + Get **http://localhost:8088/v1/directory-block-height/?** 136 | 137 | Returns the current directory block height. 138 | ``` 139 | curl -X GET http://localhost:8088/v1/directory-block-height/ 140 | ``` 141 | Returned at the time of writing: 142 | ``` 143 | {"Height":4585} 144 | ``` 145 | 146 | + Get **http://localhost:8088/v1/get-raw-data/([^/]+)** 147 | 148 | Returns the block assoicated with the given hash. 149 | ``` 150 | curl -X GET http://localhost:8088/v1/get-raw-data/f7eb0456b30b1a4b50867a5307532e92ddee7279ffc955ce1284cd142f94d642 151 | ``` 152 | returns: 153 | ``` 154 | {"Data":"00fa92e5a291592f5f78c547560edceb8bc5ef142f20e9689fcd587557a2f3d18406d6e5ece9eacaa1c31d1371af60d6a9d5ea65654d1ff5698f7fb181d0ae4bc8582c093186dd2a14e83bbf53bb7cab230b1d0e2cefbb0d93d16c09c39ea13e338d0a8c0a016f279a000010c100000004000000000000000000000000000000000000000000000000000000000000000a98f7817976ed8ff9aa306834d98c145d7c0334d7057f89dd2f035df1b37946ae000000000000000000000000000000000000000000000000000000000000000c9432448e6c7f56450804b42ed9c1653182efb6f48a5d8da2c22d1789e7dbff44000000000000000000000000000000000000000000000000000000000000000fb642daa292af42dda109bc87cddd31647da6fef9f3f25129c3740ef4d72761a0df3ade9eec4b08d5379cc64270c30ea7315d8a8a1a69efe2b98a60ecdd69e604789b0103e5f8358d7f8402264837986a2b29ac59be8a796dbbe75eecf6a853d9"} 155 | ``` 156 | This data can be unmarshalled into the directory block struct used by Factom. 157 | 158 | + Get **http://localhost:8088/v1/directory-block-by-keymr/([^/]+)** 159 | 160 | Returns the directory block assoicated with the given hash. 161 | ``` 162 | curl -X GET http://localhost:8088/v1/directory-block-by-keymr/f7eb0456b30b1a4b50867a5307532e92ddee7279ffc955ce1284cd142f94d642 163 | ``` 164 | returns: 165 | ``` 166 | {"Header":{ 167 | "PrevBlockKeyMR":"e9eacaa1c31d1371af60d6a9d5ea65654d1ff5698f7fb181d0ae4bc8582c0931", 168 | "SequenceNumber":4289, 169 | "Timestamp":1443711000}, 170 | "EntryBlockList":[ 171 | {"ChainID":"000000000000000000000000000000000000000000000000000000000000000a", 172 | "KeyMR":"98f7817976ed8ff9aa306834d98c145d7c0334d7057f89dd2f035df1b37946ae"}, 173 | {"ChainID":"000000000000000000000000000000000000000000000000000000000000000c", 174 | "KeyMR":"9432448e6c7f56450804b42ed9c1653182efb6f48a5d8da2c22d1789e7dbff44"}, 175 | {"ChainID":"000000000000000000000000000000000000000000000000000000000000000f", 176 | "KeyMR":"b642daa292af42dda109bc87cddd31647da6fef9f3f25129c3740ef4d72761a0"}, 177 | {"ChainID":"df3ade9eec4b08d5379cc64270c30ea7315d8a8a1a69efe2b98a60ecdd69e604", 178 | "KeyMR":"789b0103e5f8358d7f8402264837986a2b29ac59be8a796dbbe75eecf6a853d9"} 179 | ] 180 | } 181 | ``` 182 | This call returns the data held in a Directory Block digested into a JSON structure. 183 | 184 | + Get **http://localhost:8088/v1/entry-block-by-keymr/([^/]+)** 185 | 186 | Returns an Entry Block structure. The call: 187 | ``` 188 | curl -X GET http://localhost:8088/v1/entry-block-by-keymr/789b0103e5f8358d7f8402264837986a2b29ac59be8a796dbbe75eecf6a853d9 189 | ``` 190 | Returns 191 | ``` 192 | { 193 | "Header":{ 194 | "BlockSequenceNumber":2479, 195 | "ChainID":"df3ade9eec4b08d5379cc64270c30ea7315d8a8a1a69efe2b98a60ecdd69e604", 196 | "PrevKeyMR":"63833701a61a846ebe8d38a1c6ede6bf5d5516990c34372c7f7936812ec09bde", 197 | "Timestamp":1443711000 198 | }, 199 | "EntryList":[ 200 | { "EntryHash":"c8f4936962836cda0d8bf712653d97f8d8b5cbe675e495b6dfab6b2395c8b80a", 201 | "Timestamp":1443711360 202 | } 203 | ] 204 | } 205 | ``` 206 | This is the structure of an Entry block, broken out into JSON. 207 | 208 | + Get **http://localhost:8088/v1/entry-by-hash/([^/]+)", handleEntry)** 209 | 210 | Returns an Entry broken out into JSON. The following call: 211 | ``` 212 | curl -X GET http://localhost:8088/v1/entry-by-hash/c8f4936962836cda0d8bf712653d97f8d8b5cbe675e495b6dfab6b2395c8b80a 213 | ``` 214 | Returns: 215 | ``` 216 | {"ChainID":"df3ade9eec4b08d5379cc64270c30ea7315d8a8a1a69efe2b98a60ecdd69e604", 217 | "Content":"7b22416e63686f725265636f7264566572223a312c224442486569676874223a343238382c224b65794d52223a2265396561636161316333316431333731616636306436613964356561363536353464316666353639386637666231383164306165346263383538326330393331222c225265636f7264486569676874223a343238382c22426974636f696e223a7b2241646472657373223a22314b3253586741706d6f39755a6f79616876736253616e705657627a5a5756564d46222c2254584944223a2263323363623932303764356266643863376539656565303438316338333563663463373665626132363565393832656330623032353964636666323536636134222c22426c6f636b486569676874223a3337373031312c22426c6f636b48617368223a2230303030303030303030303030303030303466396138653735343065383135316336373231653131646264343166633936663931653432313661373161356334222c224f6666736574223a3835317d7d6234643966633530343564653635313532353664623337316463633138636266653761616537383664326262336565633466316334373966636132393762373266363330633261313439366436653737653139633631626165663030326233396133633064656534636439323963396335393836326331366639646136353033","ExtIDs":null} 218 | ``` 219 | Returns a particiular Entry's construction broken out into JSON. 220 | 221 | + Get **http://localhost:8088/v1/chain-head/([^/]+)** 222 | 223 | Returns the KeyMR of the first Entry in an Entry Chain. The call: 224 | ``` 225 | curl -X GET http://localhost:8088/v1/chain-head/df3ade9eec4b08d5379cc64270c30ea7315d8a8a1a69efe2b98a60ecdd69e604 226 | ``` 227 | Returns 228 | ``` 229 | {"ChainHead":"bfd814a3b9a4356e04c816fe4ce1a53198953ab321912d60dacba766950e5591"} 230 | ``` 231 | 232 | + Get **http://localhost:8088/v1/entry-credit-balance/([^/]+)** 233 | 234 | Returns the balance at the given Entry Credit address. For example, the call: 235 | ``` 236 | curl -X GET http://localhost:8088/v1/entry-credit-balance/748be8327d20fee4365e6b5a3dca7df1e59da47e9ebd99129ba84d58d4d0726b 237 | ``` 238 | Might return (depending on the balance at that address at the time): 239 | ``` 240 | {"Response":"4000","Success":true} 241 | ``` 242 | This would indicate that the decoded Entry Credit address (EC2eUoDPupuQXm5gxs1sCBCv3bbZBCYFDTjaFQ6iRaAKfyXNqjEJ) decodes to the hex: 748be8327d20fee4365e6b5a3dca7df1e59da47e9ebd99129ba84d58d4d0726b and has a balance of 4000 entry credits. 243 | 244 | + Get **http://localhost:8088/v1/factoid-balance/([^/]+)** 245 | 246 | Returns the Factoid balance at the given address. For example, the call: 247 | ``` 248 | curl -X GET http://localhost:8088/v1/factoid-balance/f6e117ea838cb652e9cfc3b29552d5887800a7ba614df0bd8c13e171eddc5897 249 | ``` 250 | Returns: 251 | ``` 252 | {"Response":"1210268000","Success":true} 253 | ``` 254 | Note that, like Bitcoin, Factoids use fixed point to indicate parts of a coin. so 1210268000 represents 12.10268 factoids. 255 | 256 | + Get **http://localhost:8088/v1/factoid-get-fee/** 257 | 258 | Returns the current exchange rate for Entry Credits. So the call: 259 | ``` 260 | curl -X GET http://localhost:8088/v1/factoid-get-fee/ 261 | ``` 262 | might return 263 | ``` 264 | {"Fee":100000} 265 | ``` 266 | indicating that .001 Factoids will purchase 1 Entry Credit. 267 | 268 | + Get **http://localhost:8088/v1/properties/",handleProperties)** 269 | 270 | Returns the version numbers of various components of Factom. For example at the time of writing, the call: 271 | ``` 272 | curl -X GET http://localhost:8088/v1/properties/ 273 | ``` 274 | Returns: 275 | ``` 276 | { 277 | "Protocol_Version":1005, 278 | "Factomd_Version":3002, 279 | "Fctwallet_Version":0 280 | } 281 | ``` 282 | 283 | fctwallet 284 | --------- 285 | 286 | + Get **http://localhost:8089/v1/factoid-balance/([^/]+)** 287 | 288 | Return the factoid balance at the given Factoid address. The call can take an address name known by your wallet, a Factoid address, or a hex representation of the address (less base 58 and checksums). 289 | 290 | For example, for a given wallet, the following calls: 291 | ``` 292 | curl -X GET "http://localhost:8089/v1/factoid-balance/FAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" 293 | curl -X GET "http://localhost:8089/v1/factoid-balance/9e72fa1dbdac30b557c857a1dcdca04b4ae748e52dc492e1f85f6af6f29f6534" 294 | curl -X GET "http://localhost:8089/v1/factoid-balance/FactomAddress01" 295 | ``` 296 | Will return: 297 | ``` 298 | {"Response":"1210680000","Success":true} 299 | ``` 300 | Should all retrieve the same balance from the same address, assuming that your address book had an entry FactomAddress01 with the private key for FA3ArvkijVcgrFVj45PBgGBfWm1MWAEjV1SbVxSFiUNT6s9F7AQb. 301 | 302 | + Get **http://localhost:8089/v1/entry-credit-balance/([^/]+)** 303 | 304 | Return the Entry Credit balance for the specified address. The call can take an address name known by your wallet, an Entry Credit address, or a hex representation of the address (less base 58 and checksum). 305 | 306 | For example, for a given wallet and Entry Credit address, the calls: 307 | ``` 308 | curl -X GET "http://localhost:8089/v1/entry-credit-balance/ECxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" 309 | curl -X GET "http://localhost:8089/v1/entry-credit-balance/748be8327d20fee4365e6b5a3dca7df1e59da47e9ebd99129ba84d58d4d0726b" 310 | curl -X GET "http://localhost:8090/EntryCreditAddress001" 311 | ``` 312 | Will Return 313 | ``` 314 | {"Response":"4000","Success":true} 315 | ``` 316 | Assuming that your wallet had an entry EntryCreditAddress001 with the private key for the given public address. 317 | 318 | + Get **http://localhost:8089/v1/factoid-generate-address/([^/]+)** 319 | 320 | Generate an address, and create an entry in your wallet to hold said address. Addresses are created from a deterministic hash, so if you back up your wallet, then your wallet can be restored even if some of the addresses were created after the backup. 321 | 322 | The call: 323 | ``` 324 | curl -X GET "http://localhost:8089/v1/factoid-generate-address/fctAddress0001" 325 | ``` 326 | will create an address fctAddress0001, and assign it a new private key. 327 | 328 | + Get **http://localhost:8089/v1/factoid-generate-ec-address/([^/]+)** 329 | 330 | Generate an Entry Credit address, and create an entry in your wallet to hold said address. Addresses are created from a deterministic hash, so if you back up your wallet, then your wallet can be restored even if some of the addresses were created after the backup. 331 | 332 | The call: 333 | ``` 334 | curl -X GET "http://localhost:8089/v1/factoid-generate-ec-address/ECAddress0001" 335 | ``` 336 | will create an address ECAddress0001, and assign it a new private key. 337 | 338 | + Get **http://localhost:8089/v1/factoid-generate-address-from-private-key/(.*)** 339 | 340 | This call is used to import a factoid private key in hex from another source. Provided a private key and a name. For example: 341 | 342 | ``` 343 | curl -X GET "http://localhost:8089/v1/factoid-generate-address-from-private-key/?name=addr001&privateKey=85d6755c286c6f139b1696ca74b0c14da473beadc37b2ec6273f2a92ce8d7c88" 344 | ``` 345 | would import the given private key, and store it in the wallet under addr001 and return the public key. Note that importing private keys in this fashion requires a fresh backup of the wallet for safety. 346 | 347 | + Get **http://localhost:8089/v1/factoid-generate-ec-address-from-private-key/(.*)** 348 | 349 | This call is used to import an entry credit private key in hex from another source. Provided a private key and a name. For example: 350 | 351 | ``` 352 | curl -X GET "http://localhost:8089/v1/factoid-generate-ec-address-from-private-key/?name=addr001&privateKey=3ffa892f2445286a06c0dc591d7fa557d16701e44ec1cbee2930f7d7dfb62d57" 353 | ``` 354 | would import the given private key, and store it in the wallet under addr001 and return the public key. Note that importing private keys in this fashion requires a fresh backup of the wallet for safety. 355 | 356 | + Get **http://localhost:8089/v1/factoid-generate-address-from-human-readable-private-key/(.*)** 357 | 358 | This call is used to import a factoid private key in human readable form from another source. Provided a private key and a name. For example: 359 | 360 | ``` 361 | curl -X GET "http://localhost:8089/v1/factoid-generate-address-from-human-readable-private-key/?name=addr001&privateKey=Fsxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" 362 | ``` 363 | 364 | would import the given private key, and store it in the wallet under addr001 and return the public key. Note that importing private keys in this fashion requires a fresh backup of the wallet for safety. 365 | 366 | + Get **http://localhost:8089/v1/factoid-generate-ec-address-from-human-readable-private-key/(.*)** 367 | 368 | This call is used to import an Entry Credit private key in human readable form from another source. Provided a private key and a name. For example: 369 | ``` 370 | curl -X GET "http://localhost:8089/v1/factoid-generate-address-from-human-readable-private-key/?name=addr001&privateKey=Esxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" 371 | ``` 372 | would import the given private key, and store it in the wallet under addr001 and return the public key. Note that importing private keys in this fashion requires a fresh backup of the wallet for safety. 373 | 374 | + Get **http://localhost:8089/v1/factoid-generate-address-from-token-sale/(.*)** 375 | 376 | Accepts the 12 words provided by Koinify during the crowd sale, and generates the corresponding entry in the wallet. For example: 377 | ``` 378 | curl -X GET "http://localhost:8089/v1/factoid-generate-address-from-token-sale/?name=koinifyAddr&mnemonic=<12 words separated by %20>" 379 | ``` 380 | Returns the public key 381 | 382 | + Post **http://localhost:8089/v1/factoid-new-transaction/([^/]+)** 383 | 384 | Creates a new transaction, and assoicates that transaction with a key. This key is used in other operations to add inputs, add outputs, add entry credit outputs, pay the fee, sign the transaction, and submit it. Example: 385 | ``` 386 | curl -X POST "http://localhost:8089/v1/factoid-new-transaction/trans" 387 | ``` 388 | Response 389 | ``` 390 | {"Response":"Success building a transaction","Success":true} 391 | ``` 392 | Which creates a transaction named 'trans'. We will use this transaction in the following commands. 393 | 394 | + Post **http://localhost:8089/v1/factoid-delete-transaction/([^/]+)** 395 | 396 | Delete the specified transaction under construction by name. 397 | ``` 398 | curl -X POST "http://localhost:8089/v1/factoid-delete-transaction/trans" 399 | ``` 400 | Response 401 | ``` 402 | {"Response":"Success deleting transaction","Success":true} 403 | ``` 404 | 405 | Removes the transaction 'trans'. To continue to build a transaction named trans, you would need to recreate 'trans'. 406 | 407 | + Post **http://localhost:8089/v1/factoid-add-fee/(.*)** 408 | 409 | Add the needed fee to the given transaction. This call calculates the needed fee, and adds it to the specified input. The inputs and outputs must be exactly balanced, because this call isn't going to mess with unbalanced transactions as how to balance can be tricky. 410 | ``` 411 | curl -X POST http://localhost:8089/v1/factoid-add-fee/ -d "key=trans&name=FAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" 412 | ``` 413 | Response 414 | ``` 415 | {"Response":"Added 0.153318 to FAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","Success":true} 416 | ``` 417 | 418 | Assuming the given Factoid address is an input to trans, this adds the fee to that address. 419 | 420 | + Post **http://localhost:8089/v1/factoid-add-input/(.*)** 421 | 422 | Add the given input to the transaction specified. 423 | ``` 424 | curl -X POST http://localhost:8089/v1/factoid-add-input/ -d "key=trans&name=FAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&amount=10000000" 425 | ``` 426 | Response 427 | ``` 428 | {"Response":"Success adding Input","Success":true} 429 | ``` 430 | Adds an input from the given address to the transaction trans. The number of factoids (12) will be presented in fixpoint notation, i.e. (1200000000) 431 | 432 | + Post **http://localhost:8089/v1/factoid-add-output/(.*)** 433 | 434 | Add the given output to the transaction specified. 435 | ``` 436 | curl -X POST http://localhost:8089/v1/factoid-add-output/ -d "key=trans&name=FAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&amount=10000000" 437 | ``` 438 | Response 439 | ``` 440 | {"Response":"Success adding output","Success":true} 441 | ``` 442 | 443 | Adds an output to the given address to the transaction trans. The number of factoids (13) will be presented in fixpoint notation, i.e. (1300000000) 444 | 445 | + Post **http://localhost:8089/v1/factoid-add-ecoutput/(.*)** 446 | 447 | Add the given Entry Credit Output to the transaction specified. Note that Entry Credit Outputs are denominated in Factoids. How many Entry Credits are alloted depends upon the exchage rate of factoids to entry credits in place at the time of the transaction. For example: 448 | ``` 449 | curl -X POST http://localhost:8089/v1/factoid-add-ecoutput/ -d "key=trans&name=ECxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&amount=10000000" 450 | ``` 451 | Response 452 | ``` 453 | {"Response":"Success adding Entry Credit Output","Success":true} 454 | ``` 455 | Adds an ecoutput to the given entry credit address to the transaction trans. Assume a factoid to Entry Credit exchange rate of .001. Then the number of Entry Credits (1000) will be determined by the factoids in the output (1) divided by the factoid to entry credit rate (.001). The factoids converted to entry credits will be presented in fixpoint notation, i.e. (100000000 == 1 factoid) 456 | 457 | + Post **http://localhost:8089/v1/factoid-sign-transaction/(.*)** 458 | 459 | Sign the given transaction. 460 | ``` 461 | curl -X POST "http://localhost:8089/v1/factoid-sign-transaction/trans" 462 | ``` 463 | Response 464 | ``` 465 | {"Response":"Success signing transaction","Success":true} 466 | ``` 467 | Signs the transaction 'trans'. 468 | 469 | + Post **http://localhost:8089/v1/compose-chain-submit/([^/]+)** 470 | 471 | Create a JSON object that may be used in the factomd calls to commit-chain and reveal-chain 472 | 473 | $ curl -X POST -H 'Content-Type: application/json' -d '{"ExtIDs":["466972737421", "7365636F6E64"], "Content":"48656C6C6F20466163746F6D21"}' localhost:8089/v1/compose-chain-submit/app 474 | 475 | Returns 476 | 477 | {"ChainID":"28590424cc9dbe8957e576c492befff899274757658e2db14b3b34c646b47610","ChainCommit":{"CommitChainMsg":"0001538758c38a4f0db4ade591a7669451540daaaa77b21fef2881989729725c94a9ab44675e6a6e26695e5aa298fa3a7454d95960336c9ecb1b9a2fb30fba95996e193e26b8cc9e9a6f90bd86564bcc453055eac484a67794714a573dd969df4526daf0a971f80b3b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da292a6501852426d8ebc44b74bc0da4e99bd4a50faa383cf0c4ea6f5d7dfb4561829614c9932cec66eb588becc2cab874cc17649f6fb67f87b9b5b45aa0503db90f"},"EntryReveal":{"Entry":"0028590424cc9dbe8957e576c492befff899274757658e2db14b3b34c646b476100010000646697273742100067365636f6e6448656c6c6f20466163746f6d21"}} 478 | 479 | + Post **http://localhost:8089/v1/compose-entry-submit/([^/]+)** 480 | 481 | Create a JSON object that may be used in the factomd calls to commit-entry and reveal-entry 482 | 483 | $ curl -i -X POST -H 'Content-Type: application/json' -d '{"ChainID":"28590424cc9dbe8957e576c492befff899274757658e2db14b3b34c646b47610", "ExtIDs":["657831", "657832"], "Content":"48656C6C6F20466163746F6D21"}' localhost:8089/v1/compose-entry-submit/app 484 | 485 | Returns 486 | 487 | {"EntryCommit":{"CommitEntryMsg":"000153876694327ad8b3722c6f72508df028d0f2563cc711e0ccd7da749160e3d385216237b065013b6a27bcceb6a42d62a3a8d02a6f0d73653215771de243a63ac048a18b59da297a7a050663fd071f2d61c7fbdddfc5f47364a03767110cd20dfd59112d5c470f150a7a281a84e784680a7be7cc45ceee516eebb7a199a0d77cafcb9ef7fa5809"},"EntryReveal":{"Entry":"0028590424cc9dbe8957e576c492befff899274757658e2db14b3b34c646b47610000a0003657831000365783248656c6c6f20466163746f6d21"}} 488 | 489 | + Post **http://localhost:8089/v1/commit-chain/([^/]+)** 490 | 491 | Sign a binary Chain Commit with the specified entry credit key and submit it to the factomd server 492 | 493 | + Post **http://localhost:8089/v1/commit-entry/([^/]+)** 494 | 495 | Commit an entry to an Entry Chain 496 | 497 | + Post **http://localhost:8089/v1/factoid-submit/(.*)** 498 | 499 | Submit a transaction to Factom. This call takes a named JSON parameter. For example, to submit a transaction named trans, you need the following call: 500 | ``` 501 | curl -X POST http://localhost:8089/v1/factoid-submit/\\{\"Transaction\":\"trans\"\\} 502 | ``` 503 | Response 504 | ``` 505 | {"Response":"Success Submitting transaction","Success":true} 506 | ``` 507 | 508 | + Get **http://localhost:8089/v1/factoid-validate/(.*)** 509 | 510 | Not currently implemented. 511 | 512 | + Get **http://localhost:8089"/v1/factoid-get-fee/(.*)** 513 | 514 | Get the current exchange rate in number of Factoids per Entry Credit 515 | For example: 516 | ``` 517 | curl -X GET "http://localhost:8089/v1/factoid-get-fee/" 518 | ``` 519 | Response 520 | ``` 521 | {"Response":"0.006666","Success":true} 522 | ``` 523 | 524 | + Get **http://localhost:8089"/v1/properties/** 525 | 526 | Get the version numbers of all the components of the Factom client, fctwallet, factomd, and the protocol 527 | For example: 528 | ``` 529 | curl -X GET "http://localhost:8089/v1/properties/" 530 | ``` 531 | Response 532 | ``` 533 | {"Response":"Protocol Version: 0.1.5\nfactomd Version: 0.3.4\nfctwallet Version: 0.1.4\n","Success":true} 534 | ``` 535 | 536 | + Get **http://localhost:8089/v1/factoid-get-addresses/** 537 | 538 | Get the address list held in the wallet 539 | For example: 540 | ``` 541 | curl -X GET "http://localhost:8089/v1/factoid-get-addresses/" 542 | ``` 543 | 544 | + Get **http://localhost:8089/v1/factoid-get-transactions/** 545 | 546 | Get all the transactions currently under construction, along with the key used to reference them. 547 | For example: 548 | ``` 549 | curl -X GET "http://localhost:8089/v1/factoid-get-transactions/" 550 | ``` 551 | 552 | + Post **http://localhost:8089/v1/factoid-get-processed-transactions/(.*)** 553 | 554 | If pass in 'all' then all transactions are returned. If an address, then all the transactions that use the address as an input, output, or entry credit output will be returned. The transactions are returned as text. 555 | For example: 556 | ``` 557 | curl -X POST http://localhost:8089/v1/factoid-get-processed-transactions/ -d "address=FAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" 558 | curl -X POST http://localhost:8089/v1/factoid-get-processed-transactions/ -d "address=" 559 | curl -X POST http://localhost:8089/v1/factoid-get-processed-transactions/ -d "cmd=all" 560 | ``` 561 | 562 | + Post **http://localhost:8089/v1/factoid-get-processed-transactionsj/(.*)** 563 | 564 | If pass in 'all' then all transactions are returned. If an address, then all the transactions that use the address as an input, output, or entry credit output will be returned. The transactions are returned as an array of JSON objects. The block range can also be optionally specified with start and end block heights. 565 | For example: 566 | ``` 567 | curl -X POST http://localhost:8089/v1/factoid-get-processed-transactionsj/ -d "address=FAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" 568 | curl -X POST http://localhost:8089/v1/factoid-get-processed-transactionsj/ -d "address=" 569 | curl -X POST http://localhost:8089/v1/factoid-get-processed-transactionsj/ -d "cmd=all" 570 | curl -X POST http://localhost:8089/v1/factoid-get-processed-transactionsj/ -d "cmd=all&start=25400&end=25415" 571 | ``` 572 | -------------------------------------------------------------------------------- /FactomAPI.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/FactomAPI.pdf -------------------------------------------------------------------------------- /FactomAPI_Chinese.md: -------------------------------------------------------------------------------- 1 | 2 | Factoid 应用程序接口(API) 3 | =========== 4 | 5 | 这份是关于Factoids币和Facoid钱包的应用程序接口(API)的摘要。此处，钱包(Wallet)是一个命令行驱动程序，旨在演示API而非商业钱包解决方案。 6 | 7 | 第一步需要安装Factom客户端和Factom钱包帮手。参见[如何安装]指引，设定你的运行环境(http://factom.org/howto) 并需要运行Factomd和Fctwallet。请注意在今后的几个月内，可能需要对Factomd不定期的进行更新，以持续与网络对接。具体通知更新，请参见我们的[技术博客](http://blog.factom.org/) 8 | 9 | 关于这两个应用程序的接口，**Factomd**是加入Factom网络的客户端，另一个**fctwallet**提供通用的钱包功能，并维护私钥所存放的地址簿。此外，第三个程序**walletapp**提供线下钱包(cold wallet)功能，生成线下交易并其上传Factom网络。 10 | 11 | Fatcom客户端**Factomd**提供表征性状态传输(RESTful)接口,默认存放地址http://localhost:8088 任何向Factomd发出的请求都不会产生安全性问题，因此Factomd无需位于同一位置进行程序创建和提交事务。 12 | 13 | Factom钱包**Fctwallet**亦提供表征性状态传输(RESTful)接口,默认存放地址http://localhost:8089 针对钱包中的Factoid地址，向Fctwallet发出请求会产生并建立交易，因此需要保证安全的访问接口。 14 | 15 | Factom钱包**walletapp**是替代方案，仅支持Factoid功能，并只与Factomd进行通信。*walletapp*用于冷存储，创建线下交易，并将线下交易传输到Factom网络。我们很快会基于*walletapp*发布图形用户界面(GUI),向Factoid用户提供支持。 16 | 17 | Factom钱包命令行**factom-cli**用于支持Factoid的交易，并接入Factom通用协议。*factom-cli*通过连接到*factomd*和*fctwallet*的接口，执行相应的功能。这个程序的主要用来证明Factom API的使用，也可以作为Factom脚本交易处理。 18 | 19 | 请注意：如果安装了curl，以下API调用的案例可以在命令行中直接运行，并根据具体情况，API的调用以curl -X POST 或者 curl -X GET作为前缀。 20 | 21 | factomd 22 | ------- 23 | 24 | 这份摘要，有关Factoids交易的factomd应用程序接口。我们在今后将会添加更多的细节。 25 | 26 | + Post **http://localhost:8088/v1/commit-chain/?** 27 | 28 | 生成链，创建一个新链的第一步 29 | 30 | 首先需要调用 fctwallet API 'compose-chain-submit' ，以获取作为该API输入的CommitChainMsg 31 | 例如： 32 | 33 | 向compose-entry-submit API发送请求，返回一个JSON对象 34 | 35 | ``` 36 | $ curl -X POST -H 'Content-Type: application/json' -d '{"ExtIDs":["foo", "bar"], "Content":"Hello Factom!"}' localhost:8089/v1/compose-chain-submit/entrycreditaddressname 37 | ``` 38 | 返回 39 | 40 | {"ChainID":"92475004e70f41b94750f4a77bf7b430551113b25d3d57169eadca5692bb043d","ChainCommit":{"CommitChainMsg":"0001521deb5c7891ac03adffe815c64088dc98ef281de1891c0f99a63c55369c1727dc73580cbcc309ee55fa780ce406722b7a074138c994c859e2eda619bbad59b41775b51176464cb77fc08b6ef6767dcc315b4729a871071053cfe4af5a6397f66fbe01042f0b79a1ad273d890287e5d4f16d2669c06c523b9e48673de1bfde3ea2fda309ac92b393f12e48b277932e9af0599071298a24be285184e03d0b79576d1d6473342e48fcb21b2ca99e41b4919ef790db9f5a526b4d150d20e1c2e25237249db2e109"},"EntryReveal":{"Entry":"0092475004e70f41b94750f4a77bf7b430551113b25d3d57169eadca5692bb043d000a0003666f6f000362617248656c6c6f20466163746f6d21"}} 41 | 42 | 返回值包括ChainCommit和 Entry Reveal. 43 | 生成记录: 44 | 45 | $ curl -i -X POST -H 'Content-Type: application/json' -d '{"CommitChainMsg":"0001521deb5c7891ac03adffe815c64088dc98ef281de1891c0f99a63c55369c1727dc73580cbcc309ee55fa780ce406722b7a074138c994c859e2eda619bbad59b41775b51176464cb77fc08b6ef6767dcc315b4729a871071053cfe4af5a6397f66fbe01042f0b79a1ad273d890287e5d4f16d2669c06c523b9e48673de1bfde3ea2fda309ac92b393f12e48b277932e9af0599071298a24be285184e03d0b79576d1d6473342e48fcb21b2ca99e41b4919ef790db9f5a526b4d150d20e1c2e25237249db2e109"}' localhost:8088/v1/commit-chain 46 | 47 | 显示第一项记录: 48 | 49 | $ curl -i -X POST -H 'Content-Type: application/json' -d '{"Entry":"0092475004e70f41b94750f4a77bf7b430551113b25d3d57169eadca5692bb043d000a0003666f6f000362617248656c6c6f20466163746f6d21"}' localhost:8088/v1/reveal-entry 50 | 51 | 生成链并记录第一项记录 52 | 53 | + Post **http://localhost:8088/v1/reveal-chain/?** 54 | 55 | 在链中显示第一项记录。需要完成链的构建。API调用的格式如上所示 56 | 57 | + Post **http://localhost:8088/v1/commit-entry/?** 58 | 59 | 生成记录 在链中写入记录的第一步 60 | 61 | 需要首先调用fctwallet API 'compose-entry-submit'，以获取作为该API输入的CommitEntryMsg 62 | 例如: 63 | 64 | 向compose-entry-submit API发送请求，返回一个JSON对象 65 | 66 | ``` 67 | $ curl -i -X POST -H 'Content-Type: application/json' -d '{"ChainID":"5c337e9010600c415d2cd259ed0bf904e35666483277664d869a98189b35ca81", "ExtIDs":["foo", "bar"], "Content":"Hello Factom!"}' localhost:8089/v1/compose-entry-submit/entrycreditaddressname 68 | ``` 69 | 70 | 返回 71 | 72 | {"EntryCommit":{"CommitEntryMsg":"0001521dc2d47d32cbdd3fc21889e22cc408ae0b0c120662c0873331cc5ce8ebdc1b6722968ce20179a1ad273d890287e5d4f16d2669c06c523b9e48673de1bfde3ea2fda309ac92f4f4b4d52cc6b228b9b621b1b1969ab46bfa4f80379e14df15e4d48aefa72db6dd835fc7a70d2c79cc9e01eb9ca5be33875439c97c791a1b57f191df03a44008"},"EntryReveal":{"Entry":"005c337e9010600c415d2cd259ed0bf904e35666483277664d869a98189b35ca81000a0003666f6f000362617248656c6c6f20466163746f6d21"}} 73 | 74 | 返回值包括生成记录和显示记录. 75 | 生成记录: 76 | 77 | $ curl -i -X POST -H 'Content-Type: application/json' -d '{"CommitEntryMsg":"0001521dc2d47d32cbdd3fc21889e22cc408ae0b0c120662c0873331cc5ce8ebdc1b6722968ce20179a1ad273d890287e5d4f16d2669c06c523b9e48673de1bfde3ea2fda309ac92f4f4b4d52cc6b228b9b621b1b1969ab46bfa4f80379e14df15e4d48aefa72db6dd835fc7a70d2c79cc9e01eb9ca5be33875439c97c791a1b57f191df03a44008"}' localhost:8088/v1/commit-entry 78 | 79 | 显示记录: 80 | 81 | $ curl -i -X POST -H 'Content-Type: application/json' -d '{"Entry":"005c337e9010600c415d2cd259ed0bf904e35666483277664d869a98189b35ca81000a0003666f6f000362617248656c6c6f20466163746f6d21"}' localhost:8088/v1/reveal-entry 82 | 83 | 根据提供的ChainID写入记录 84 | 85 | 请注意：ChainName可用来替代ChainID。但如果ChainID的域有数据，ChainName的域会被忽略。 86 | 87 | 例如 json 记录: 88 | {"ChainName":["foo", "bar"], "ExtIDs":["ex1", "ex2"], "Content":"Hello Factom!"} 89 | 90 | 与以下一致： 91 | 92 | {"ChainID":"92475004e70f41b94750f4a77bf7b430551113b25d3d57169eadca5692bb043d", "ExtIDs":["ex1", "ex2"], "Content":"Hello Factom!"} 93 | 94 | + Post **http://localhost:8088/v1/reveal-entry/?** 95 | 96 | 显示新的条目，需要完成写入链中的记录 97 | 98 | + Post **http://localhost:8088/v1/factoid-submit/?** 99 | 100 | 提交事务。需要对交易进行编码，作为请求的一部分。例如，生成一个从xxx账户向yyy账户转10个Factoids币的一项交易，可以编码为 101 | ``` 102 | curl -X GET http://localhost:8088/v1/factoid-submit/httpp02015023e2886901010083ddb4b3006302ac3d 103 | a1a1e5eac31af88cdbb886f34470cc0415d1968d8637814cfac482f283dceb940025edb8b25808b6e6d 104 | 48ad5ba67d0843eaf962c40f63c9b4df91b8fe7364ae872014b776d236585f2ed658ec9d24a4a65e08e 105 | f6074573f570b8b25a9d424b1d955d2caaa4d2cfe30eb8217844f8b28b8a47ce6dc3e5eecd03f30954c 106 | a3f0b64a63e0687f667bc3300bb33a0638953d442db2cd6fb4d27045318ec09463542c66305 107 | ``` 108 | 这看上去是很复杂的数据结构。很多用户会使用fctwallet建立这项请求。 109 | 110 | + Get **http://localhost:8088/v1/directory-block-head/?** 111 | 112 | 返回目录区块头目的哈希值。无需任何参数，返回一个JSON形式的字符串。 113 | ``` 114 | {"KeyMR":"f7eb0456b30b1a4b50867a5307532e92ddee7279ffc955ce1284cd142f94d642"} 115 | ``` 116 | + Get **http://localhost:8088/v1/directory-block-height/?** 117 | 118 | 返回当前目录区块的高度： 119 | ``` 120 | curl -X GET http://localhost:8088/v1/directory-block-height/ 121 | ``` 122 | 返回写入时间： 123 | ``` 124 | {"Height":4585} 125 | ``` 126 | 127 | + Get **http://localhost:8088/v1/get-raw-data/([^/]+)** 128 | 129 | 返回指定哈希值的区块 130 | ``` 131 | curl -X GET http://localhost:8088/v1/get-raw-data/f7eb0456b30b1a4b50867a5307532e92ddee7279ffc955ce1284cd142f94d642 132 | ``` 133 | 返回： 134 | ``` 135 | {"Data":"00fa92e5a291592f5f78c547560edceb8bc5ef142f20e9689fcd587557a2f3d18406d6e5ece9eacaa1c31d1371af60d6a9d5ea65654d1ff5698f7fb181d0ae4bc8582c093186dd2a14e83bbf53bb7cab230b1d0e2cefbb0d93d16c09c39ea13e338d0a8c0a016f279a000010c100000004000000000000000000000000000000000000000000000000000000000000000a98f7817976ed8ff9aa306834d98c145d7c0334d7057f89dd2f035df1b37946ae000000000000000000000000000000000000000000000000000000000000000c9432448e6c7f56450804b42ed9c1653182efb6f48a5d8da2c22d1789e7dbff44000000000000000000000000000000000000000000000000000000000000000fb642daa292af42dda109bc87cddd31647da6fef9f3f25129c3740ef4d72761a0df3ade9eec4b08d5379cc64270c30ea7315d8a8a1a69efe2b98a60ecdd69e604789b0103e5f8358d7f8402264837986a2b29ac59be8a796dbbe75eecf6a853d9"} 136 | ``` 137 | 这些数据能被分散到Factom的目录区块机构中。 138 | 139 | + Get **http://localhost:8088/v1/directory-block-by-keymr/([^/]+)** 140 | 141 | 返回指定哈希值的区块 142 | ``` 143 | curl -X GET http://localhost:8088/v1/directory-block-by-keymr/f7eb0456b30b1a4b50867a5307532e92ddee7279ffc955ce1284cd142f94d642 144 | ``` 145 | 返回： 146 | ``` 147 | {"Header":{ 148 | "PrevBlockKeyMR":"e9eacaa1c31d1371af60d6a9d5ea65654d1ff5698f7fb181d0ae4bc8582c0931", 149 | "SequenceNumber":4289, 150 | "Timestamp":1443711000}, 151 | "EntryBlockList":[ 152 | {"ChainID":"000000000000000000000000000000000000000000000000000000000000000a", 153 | "KeyMR":"98f7817976ed8ff9aa306834d98c145d7c0334d7057f89dd2f035df1b37946ae"}, 154 | {"ChainID":"000000000000000000000000000000000000000000000000000000000000000c", 155 | "KeyMR":"9432448e6c7f56450804b42ed9c1653182efb6f48a5d8da2c22d1789e7dbff44"}, 156 | {"ChainID":"000000000000000000000000000000000000000000000000000000000000000f", 157 | "KeyMR":"b642daa292af42dda109bc87cddd31647da6fef9f3f25129c3740ef4d72761a0"}, 158 | {"ChainID":"df3ade9eec4b08d5379cc64270c30ea7315d8a8a1a69efe2b98a60ecdd69e604", 159 | "KeyMR":"789b0103e5f8358d7f8402264837986a2b29ac59be8a796dbbe75eecf6a853d9"} 160 | ] 161 | } 162 | ``` 163 | 这项调用返回目录区块中的数据，并转化为JSON结构。 164 | 165 | + Get **http://localhost:8088/v1/entry-block-by-keymr/([^/]+)** 166 | 167 | 返回记录区块机构。这项调用为： 168 | ``` 169 | curl -X GET http://localhost:8088/v1/entry-block-by-keymr/789b0103e5f8358d7f8402264837986a2b29ac59be8a796dbbe75eecf6a853d9 170 | ``` 171 | 返回 172 | ``` 173 | { 174 | "Header":{ 175 | "BlockSequenceNumber":2479, 176 | "ChainID":"df3ade9eec4b08d5379cc64270c30ea7315d8a8a1a69efe2b98a60ecdd69e604", 177 | "PrevKeyMR":"63833701a61a846ebe8d38a1c6ede6bf5d5516990c34372c7f7936812ec09bde", 178 | "Timestamp":1443711000 179 | }, 180 | "EntryList":[ 181 | { "EntryHash":"c8f4936962836cda0d8bf712653d97f8d8b5cbe675e495b6dfab6b2395c8b80a", 182 | "Timestamp":1443711360 183 | } 184 | ] 185 | } 186 | ``` 187 | 这是一个记录区块的结构，分拆成JSON结构 188 | 189 | + Get **http://localhost:8088/v1/entry-by-hash/([^/]+)", handleEntry)** 190 | 191 | 返回一项分拆成JSON的记录： 192 | ``` 193 | curl -X GET http://localhost:8088/v1/entry-by-hash/c8f4936962836cda0d8bf712653d97f8d8b5cbe675e495b6dfab6b2395c8b80a 194 | ``` 195 | 返回: 196 | ``` 197 | {"ChainID":"df3ade9eec4b08d5379cc64270c30ea7315d8a8a1a69efe2b98a60ecdd69e604", 198 | "Content":"7b22416e63686f725265636f7264566572223a312c224442486569676874223a343238382c224b65794d52223a2265396561636161316333316431333731616636306436613964356561363536353464316666353639386637666231383164306165346263383538326330393331222c225265636f7264486569676874223a343238382c22426974636f696e223a7b2241646472657373223a22314b3253586741706d6f39755a6f79616876736253616e705657627a5a5756564d46222c2254584944223a2263323363623932303764356266643863376539656565303438316338333563663463373665626132363565393832656330623032353964636666323536636134222c22426c6f636b486569676874223a3337373031312c22426c6f636b48617368223a2230303030303030303030303030303030303466396138653735343065383135316336373231653131646264343166633936663931653432313661373161356334222c224f6666736574223a3835317d7d6234643966633530343564653635313532353664623337316463633138636266653761616537383664326262336565633466316334373966636132393762373266363330633261313439366436653737653139633631626165663030326233396133633064656534636439323963396335393836326331366639646136353033","ExtIDs":null} 199 | ``` 200 | 返回一项特定记录，并分拆成JSON格式 201 | 202 | + Get **http://localhost:8088/v1/chain-head/([^/]+)** 203 | 204 | 返回条目链中第一项记录的梅克尔根(KeyMR)。请求： 205 | ``` 206 | curl -X GET http://localhost:8088/v1/chain-head/df3ade9eec4b08d5379cc64270c30ea7315d8a8a1a69efe2b98a60ecdd69e604 207 | ``` 208 | 返回： 209 | ``` 210 | {"ChainHead":"bfd814a3b9a4356e04c816fe4ce1a53198953ab321912d60dacba766950e5591"} 211 | ``` 212 | 213 | + Get **http://localhost:8088/v1/entry-credit-balance/([^/]+)** 214 | 215 | 返回指定数据条目信用地址的余额。例如，请求: 216 | ``` 217 | curl -X GET http://localhost:8088/v1/entry-credit-balance/748be8327d20fee4365e6b5a3dca7df1e59da47e9ebd99129ba84d58d4d0726b 218 | ``` 219 | 可能返回（取决于该地址该时刻的余额）: 220 | ``` 221 | {"Response":"4000","Success":true} 222 | ``` 223 | 这表明该数据条目信用地址 (EC2eUoDPupuQXm5gxs1sCBCv3bbZBCYFDTjaFQ6iRaAKfyXNqjEJ)解码为:748be8327d20fee4365e6b5a3dca7df1e59da47e9ebd99129ba84d58d4d0726b 并有4000的条目信用积分。 224 | 225 | + Get **http://localhost:8088/v1/factoid-balance/([^/]+)** 226 | 227 | 返回指定地址的Factoid余额。例如，该项请求： 228 | ``` 229 | curl -X GET http://localhost:8088/v1/factoid-balance/f6e117ea838cb652e9cfc3b29552d5887800a7ba614df0bd8c13e171eddc5897 230 | ``` 231 | 返回: 232 | ``` 233 | {"Response":"1210268000","Success":true} 234 | ``` 235 | 需要注意的是，类似于比特币，Factoids使用固定小数点反映货币数量。如 12.10268000 表示 12.10268 枚factoids币. 236 | 237 | + Get **http://localhost:8088/v1/factoid-get-fee/** 238 | 239 | 返回数据条目信用与Factoids币的现行折换率: 240 | ``` 241 | curl -X GET http://localhost:8088/v1/factoid-get-fee/ 242 | ``` 243 | 或许返回 244 | ``` 245 | {"Fee":100000} 246 | ``` 247 | 表明.001 Factoids 可以购买1条条目信用. 248 | 249 | + Get **http://localhost:8088/v1/properties/",handleProperties)** 250 | 251 | 返回Factom不同组成部分版本号： 252 | ``` 253 | curl -X GET http://localhost:8088/v1/properties/ 254 | ``` 255 | 返回: 256 | ``` 257 | { 258 | "Protocol_Version":1005, 259 | "Factomd_Version":3002, 260 | "Fctwallet_Version":0 261 | } 262 | ``` 263 | 264 | fctwallet 265 | --------- 266 | 267 | + Get **http://localhost:8089/v1/factoid-balance/([^/]+)** 268 | 269 | 返回指定Factoid地址的Factoid的余额。这项请求可以使用钱包地址名，Factoid地址，或者该地址对应的16进制 270 | 271 | 举例: 272 | ``` 273 | curl -X GET "http://localhost:8089/v1/factoid-balance/FAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" 274 | curl -X GET "http://localhost:8089/v1/factoid-balance/9e72fa1dbdac30b557c857a1dcdca04b4ae748e52dc492e1f85f6af6f29f6534" 275 | curl -X GET "http://localhost:8089/v1/factoid-balance/FactomAddress01" 276 | ``` 277 | 会返回: 278 | ``` 279 | {"Response":"1210680000","Success":true} 280 | ``` 281 | 若从以上相同地址返回的余额相等，表明你的地址簿有一项记录FactomAddress01，它的私钥是FA3ArvkijVcgrFVj45PBgGBfWm1MWAEjV1SbVxSFiUNT6s9F7AQb. 282 | 283 | + Get **http://localhost:8089/v1/entry-credit-balance/([^/]+)** 284 | 285 | 返回指定地址的条目信用余额。这项请求可以使用已知的钱包的地址名，条目信用的地址，或者该地址对应的16进制 286 | 287 | 举例：对于一个指定的钱包和条目信用地址: 288 | ``` 289 | curl -X GET "http://localhost:8089/v1/entry-credit-balance/ECxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" 290 | curl -X GET "http://localhost:8089/v1/entry-credit-balance/748be8327d20fee4365e6b5a3dca7df1e59da47e9ebd99129ba84d58d4d0726b" 291 | curl -X GET "http://localhost:8090/EntryCreditAddress001" 292 | ``` 293 | 将返回 294 | ``` 295 | {"Response":"4000","Success":true} 296 | ``` 297 | 假定你的钱包有一项条目记录 EntryCreditAddress001 对应所给定的公共地址的私钥。 298 | 299 | + Get **http://localhost:8089/v1/factoid-generate-address/([^/]+)** 300 | 301 | 生成地址，并在钱包中创建一个条目保存该地址。地址是从确定的散列中创建。因此，当你备份钱包时，即使有些地址是备份后被创建，但是你的钱包也能够有效恢复。 302 | 303 | 调用: 304 | ``` 305 | curl -X GET http://localhost:8089/v1/factoid-generate-address/fctAddress0001 306 | ``` 307 | 会生成一个新的地址fctAddress0001, 并为其分配一个新的私钥。 308 | 309 | + Get **http://localhost:8089/v1/factoid-generate-ec-address/([^/]+)** 310 | 311 | 生成信用条目地址，并在钱包中创建一个条目保存该地址。地址是从确定的散列中创建。因此，当你备份钱包时，即使有些地址是备份后被创建，但是你的钱包也能够有效恢复。 312 | 313 | 调用: 314 | ``` 315 | curl -X GET http://localhost:8089/v1/factoid-generate-ec-address/ECAddress0001 316 | ``` 317 | 会生成一个新的地址 ECAddress0001, 并为其分配一个新的私钥。 318 | 319 | + Get **http://localhost:8089/v1/factoid-generate-address-from-private-key/(.*)** 320 | 321 | 这项请求是从另一个源导入十六进制的factoid私钥，提供了一个私钥和名字。例如： 322 | 323 | ``` 324 | curl -X GET http://localhost:8089/v1/factoid-generate-address-from-private-key/?name=addr01&privateKey=85d6755c286c6f139b1696ca74b0c14da473beadc37b2ec6273f2a92ce8d7c88 325 | ``` 326 | 会导入给定的私钥，保存在钱包地址addr001下，并返回一个公钥。需要注意的是,以这种形式导入的私钥需要立即备份，以保证安全性。 327 | 328 | + Get **http://localhost:8089/v1/factoid-generate-ec-address-from-private-key/(.*)** 329 | 330 | 这项请求是从另一个源导入十六进制的信用条目私钥，提供了一个私钥和名字。例如： 331 | 332 | ``` 333 | curl -X GET http://localhost:8089/v1/factoid-generate-ec-address-from-private-key/?name=addr001&privateKey=3ffa892f2445286a06c0dc591d7fa557d16701e44ec1cbee2930f7d7dfb62d57 334 | ``` 335 | 会导入给定的私钥，保存在钱包地址addr001下，并返回一个公钥。需要注意的是,以这种形式导入的私钥需要立即备份，以保证安全性。 336 | 337 | + Get **http://localhost:8089/v1/factoid-generate-address-from-human-readable-private-key/(.*)** 338 | 339 | 这项请求是从另一个源导入可读的factoid私钥，提供了一个私钥和名字。例如： 340 | 341 | ``` 342 | curl -X GET "http://localhost:8089/v1/factoid-generate-address-from-human-readable-private-key/?name=addr001&privateKey=Fsxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" 343 | ``` 344 | 345 | 会导入给定的私钥，保存在钱包地址addr001下，并返回一个公钥。需要注意的是,以这种形式导入的私钥需要立即备份，以保证安全性。 346 | 347 | + Get **http://localhost:8089/v1/factoid-generate-ec-address-from-human-readable-private-key/(.*)** 348 | 349 | 这项请求是从另一个源导入可读的信用条目私钥，提供了一个私钥和名字。例如： 350 | ``` 351 | curl -X GET "http://localhost:8089/v1/factoid-generate-address-from-human-readable-private-key/?name=addr001&privateKey=Esxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" 352 | ``` 353 | 会导入给定的私钥，保存在钱包地址addr001下，并返回一个公钥。需要注意的是,以这种形式导入的私钥需要立即备份，以保证安全性。 354 | 355 | + Get **http://localhost:8089/v1/factoid-generate-address-from-token-sale/(.*)** 356 | 357 | 在销售过程中接受Koinfiy的信息，并在钱包中生成相应的记录，例如： 358 | ``` 359 | curl -X GET http://localhost:8089/v1/factoid-generate-address-from-token-sale/?name=koinifyAddr&mnemonic=<12 words separated by %20> 360 | ``` 361 | 返回公钥 362 | 363 | + Post **http://localhost:8089/v1/factoid-new-transaction/([^/]+)** 364 | 365 | 创建一项新的交易以及对应的钥匙，该钥匙将在其他操作过程中用于添加输入或输出，添加信用条目输出，支付费用，签署交易，以及传递。例如： 366 | ``` 367 | curl -X POST http://localhost:8089/v1/factoid-new-transaction/trans 368 | ``` 369 | 返回 370 | ``` 371 | {"Response":"Success building a transaction","Success":true} 372 | ``` 373 | 生成了一项新交易，交易名为‘trans’ 我们将在接下来的命令中使用该项交易。 374 | 375 | + Post **http://localhost:8089/v1/factoid-delete-transaction/([^/]+)** 376 | 377 | 根据名字删除特定的交易 378 | ``` 379 | curl -X POST http://localhost:8089/v1/factoid-delete-transaction/trans 380 | ``` 381 | 返回 382 | ``` 383 | {"Response":"Success deleting transaction","Success":true} 384 | ``` 385 | 386 | 移除‘trans’交易后。若要继续以trans交易名进行交易，需要重新创造交易‘trans’。 387 | 388 | + Post **http://localhost:8089/v1/factoid-add-fee/(.*)** 389 | 390 | 对于指定交易增添费用。这项请求计算需要支付的费用，并把它添入特定的输入。输入和输出必须完全相等，因为这项调用不会处理不等的交易，由于校对金额一致会相当的棘手。 391 | ``` 392 | curl -X POST http://localhost:8089/v1/factoid-add-fee/ -d "key=trans&name=FA3EPZYqodgyEGXNMbiZKE5TS2x2J9wF8J9MvPZb52iGR78xMgCb" 393 | ``` 394 | 返回 395 | ``` 396 | {"Response":"Added 0.153318 to FA3EPZYqodgyEGXNMbiZKE5TS2x2J9wF8J9MvPZb52iGR78xMgCb","Success":true} 397 | ``` 398 | 399 | 假定Factoid地址是该项交易的输入，那么所需要的费用将会被添加到该地址 400 | 401 | + Post **http://localhost:8089/v1/factoid-add-input/(.*)** 402 | 403 | 添加给定的输入信息到特定的交易 404 | ``` 405 | curl -X POST http://localhost:8089/v1/factoid-add-input/ -d "key=trans&name=FA3EPZYqodgyEGXNMbiZKE5TS2x2J9wF8J9MvPZb52iGR78xMgCb&amount=10000000" 406 | ``` 407 | 返回 408 | ``` 409 | {"Response":"Success adding Input","Success":true} 410 | ``` 411 | 添加某项给定地址的输入信息到“trans”交易， Factoids数量 (12)将会以定点表示法列示 (1200000000) 412 | 413 | + Post **http://localhost:8089/v1/factoid-add-output/(.*)** 414 | 415 | 将给定的输出信息添加到特定的交易 416 | ``` 417 | curl -X POST http://localhost:8089/v1/factoid-add-output/ -d "key=trans&name=FA3SXWH3x3HJCjNd3LGrvZnZKJhmdSFKEYd1BgjeHeFPiTvwfw8N&amount=10000000" 418 | ``` 419 | 返回 420 | ``` 421 | {"Response":"Success adding output","Success":true} 422 | ``` 423 | 424 | 将一项给定地址的输出信息添加到trans交易。Factoids数量 (13)将会以定点表示法列示 (1300000000) 425 | 426 | + Post **http://localhost:8089/v1/factoid-add-ecoutput/(.*)** 427 | 428 | 添加条目信用输出信息到特定的交易。需要注意的是，条目信用信息的固定输出形式是Factoids。具体分配的条目信用的数量取决于交易发生时factoid转换为条目信用的折换率。 429 | ``` 430 | curl -X POST http://localhost:8089/v1/factoid-add-ecoutput/ -d "key=trans&name=EC2ENydo4tjz5rMiZVDiM1k315m3ZanSm6LFDYcQyn5edBXNnrva&amount=10000000" 431 | ``` 432 | 返回 433 | ``` 434 | {"Response":"Success adding Entry Credit Output","Success":true} 435 | ``` 436 | 添加某个给定条目信用地址的输出信息到trans交易。假定factoid与条目信用的转换率.001。那么1000条条目信用将转换为1个factoid作为输出信息1000，factoids以固定形式列示(100000000 == 1 factoid) 437 | 438 | + Post **http://localhost:8089/v1/factoid-sign-transaction/(.*)** 439 | 440 | 对特定交易签名. 441 | ``` 442 | http://localhost:8089/v1/factoid-sign-transaction/trans 443 | ``` 444 | 返回 445 | ``` 446 | {"Response":"Success signing transaction","Success":true} 447 | ``` 448 | 对trans交易签名. 449 | 450 | + Post **http://localhost:8089/v1/compose-chain-submit/([^/]+)** 451 | 452 | 创建一个JSON对象，用于通过Factomd请求，生成链和显示链。请注意把app改成你自己的EC名字！ 453 | 454 | $ curl -X POST -H 'Content-Type: application/json' -d '{"ExtIDs":["foo", "bar"], "Content":"Hello Factom!"}' localhost:8089/v1/compose-chain-submit/app 455 | 456 | 返回 457 | 458 | {"ChainID":"92475004e70f41b94750f4a77bf7b430551113b25d3d57169eadca5692bb043d","ChainCommit":{"CommitChainMsg":"0001521deb5c7891ac03adffe815c64088dc98ef281de1891c0f99a63c55369c1727dc73580cbcc309ee55fa780ce406722b7a074138c994c859e2eda619bbad59b41775b51176464cb77fc08b6ef6767dcc315b4729a871071053cfe4af5a6397f66fbe01042f0b79a1ad273d890287e5d4f16d2669c06c523b9e48673de1bfde3ea2fda309ac92b393f12e48b277932e9af0599071298a24be285184e03d0b79576d1d6473342e48fcb21b2ca99e41b4919ef790db9f5a526b4d150d20e1c2e25237249db2e109"},"EntryReveal":{"Entry":"0092475004e70f41b94750f4a77bf7b430551113b25d3d57169eadca5692bb043d000a0003666f6f000362617248656c6c6f20466163746f6d21"}} 459 | 460 | + Post **http://localhost:8089/v1/compose-entry-submit/([^/]+)** 461 | 462 | 创建一个JSON对象，用于通过Factomd请求，生成记录和显示记录。请注意把app改成你自己的EC名字！ 463 | 464 | $ curl -i -X POST -H 'Content-Type: application/json' -d '{"ChainID":"5c337e9010600c415d2cd259ed0bf904e35666483277664d869a98189b35ca81", "ExtIDs":["foo", "bar"], "Content":"Hello Factom!"}' localhost:8089/v1/compose-entry-submit/app 465 | 466 | 返回 467 | 468 | {"EntryCommit":{"CommitEntryMsg":"0001521dc2d47d32cbdd3fc21889e22cc408ae0b0c120662c0873331cc5ce8ebdc1b6722968ce20179a1ad273d890287e5d4f16d2669c06c523b9e48673de1bfde3ea2fda309ac92f4f4b4d52cc6b228b9b621b1b1969ab46bfa4f80379e14df15e4d48aefa72db6dd835fc7a70d2c79cc9e01eb9ca5be33875439c97c791a1b57f191df03a44008"},"EntryReveal":{"Entry":"005c337e9010600c415d2cd259ed0bf904e35666483277664d869a98189b35ca81000a0003666f6f000362617248656c6c6f20466163746f6d21"}} 469 | 470 | 471 | + Post **http://localhost:8089/v1/commit-chain/([^/]+)** 472 | 473 | 对一个特定的条目信用钥匙以二进制形式签署，并递交至Factomd服务器 474 | 475 | + Post **http://localhost:8089/v1/commit-entry/([^/]+)** 476 | 477 | 在记录链中提交记录 478 | 479 | + Post **http://localhost:8089/v1/factoid-submit/(.*)** 480 | 481 | 向Factom递交交易。该请求需要一个JSON参数。例如：递交一个名为trans的交易: 482 | ``` 483 | curl -X POST http://localhost:8089/v1/factoid-submit/{"Transaction":"trans"} 484 | ``` 485 | 返回 486 | ``` 487 | {"Response":"Success Submitting transaction","Success":true} 488 | ``` 489 | 490 | + Get **http://localhost:8089/v1/factoid-validate/(.*)** 491 | 492 | 目前未实现 493 | 494 | + Get **http://localhost:8089"/v1/factoid-get-fee/(.*)** 495 | 496 | 获取每条信用条目对应的Factoid的换算率 497 | 例如： 498 | ``` 499 | curl -X GET http://localhost:8089/v1/factoid-get-fee/ 500 | ``` 501 | 返回 502 | ``` 503 | {"Response":"0.006666","Success":true} 504 | ``` 505 | 506 | + Get **http://localhost:8089"/v1/properties/** 507 | 508 | 获取Factom客户端，fctwallet，factomd和协议的版本号 509 | 例如: 510 | ``` 511 | http://localhost:8089/v1/properties/ 512 | ``` 513 | 返回 514 | ``` 515 | {"Response":"Protocol Version: 0.1.5\nfactomd Version: 0.3.4\nfctwallet Version: 0.1.4\n","Success":true} 516 | ``` 517 | 518 | + Get **http://localhost:8089/v1/factoid-get-addresses/** 519 | 520 | 获取钱包的地址列表 521 | 例如: 522 | ``` 523 | curl -X GET http://localhost:8089/v1/factoid-get-addresses/ 524 | ``` 525 | 526 | + Get **http://localhost:8089/v1/factoid-get-transactions/** 527 | 528 | 获取在建过程中的交易以及对应的钥匙 529 | 例如： 530 | ``` 531 | curl -X GET http://localhost:8089/v1/factoid-get-transactions/ 532 | ``` 533 | 534 | + Post **http://localhost:8089/v1/factoid-get-processed-transactions/(.*)** 535 | 536 | 如果键入‘all’，会返回所有交易。如果键入一个地址，会返回所有使用该地址作为输入信息，输出信息，或作为信用条目输出的交易，并以文本形式返回。 537 | 例如: 538 | ``` 539 | curl -X POST http://localhost:8089/v1/factoid-get-processed-transactions/ -d "address=FA2opZ5tRQET3LNRPfXFR2dWDRD1Sgc1aEYNStTXtkPWQtEvoAiY" 540 | curl -X POST http://localhost:8089/v1/factoid-get-processed-transactions/ -d "address=" 541 | curl -X POST http://localhost:8089/v1/factoid-get-processed-transactions/ -d "cmd=all" 542 | ``` 543 | 544 | + Post **http://localhost:8089/v1/factoid-get-processed-transactionsj/(.*)** 545 | 546 | 如果键入‘all’，会返回所有交易。如果键入一个地址，会返回所有使用该地址作为输入信息，输出信息，或作为信用条目输出的交易，并以一串JSON对象的数组返回。 547 | 例如: 548 | ``` 549 | curl -X POST http://localhost:8089/v1/factoid-get-processed-transactionsj/ -d "address=FA3RrKWJLQeDuzC9YzxcSwenU1qDzzwjR1uHMpp1SQbs8wH9Qbbr" 550 | curl -X POST http://localhost:8089/v1/factoid-get-processed-transactionsj/ -d "address=" 551 | curl -X POST http://localhost:8089/v1/factoid-get-processed-transactionsj/ -d "cmd=all" 552 | ``` 553 | -------------------------------------------------------------------------------- /FactomAPI_Chinese.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/FactomAPI_Chinese.pdf -------------------------------------------------------------------------------- /FactomLedgerbyConsensus.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/FactomLedgerbyConsensus.pdf -------------------------------------------------------------------------------- /FactomOracle.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/FactomOracle.pdf -------------------------------------------------------------------------------- /Factom_FAQ.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/Factom_FAQ.pdf -------------------------------------------------------------------------------- /Factom_Whitepaper.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/Factom_Whitepaper.pdf -------------------------------------------------------------------------------- /Factom_Whitepaper_Errata.md: -------------------------------------------------------------------------------- 1 | Factom Whitepaper Errata 2 | ============= 3 | 4 | 5 | Design Changes 6 | -------- 7 | Some minor details about Factom have changed since the Whitepaper was published. 8 | 9 | 10 | ### Block Times 11 | 12 | The whitepaper describes Directory Blocks, as being 1 minute long. They have been changed to be 10 minutes long. Minute level resolution is maintained in the lower level blocks by adding demarcation structures. Merkle Roots are still placed into Bitcoin every 10 minutes. 13 | 14 | 15 | ### Denial of Chain 16 | 17 | The whitepaper describes this attack denying for 10 minutes. The attack is actually 1 hour long. The time a Chain Commit gives for exclusivity was increased to give time to recover from network errors. 18 | see: https://github.com/FactomProject/WorkItems/issues/368 19 | 20 | Changes in the Teachings 21 | -------- 22 | Some minor details describing other systems is updated here. 23 | 24 | ### Bitcoin Headers 25 | 26 | 27 | The Whitepaper describes the Bitcoin coinbase as being in the header. It is not in the header, but instead is the first thing after the header in a block. 28 | -------------------------------------------------------------------------------- /Factom_Whitepaper_Japanese.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/Factom_Whitepaper_Japanese.pdf -------------------------------------------------------------------------------- /Factom_Whitepaper_v1.2.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/Factom_Whitepaper_v1.2.pdf -------------------------------------------------------------------------------- /Factom_Whitepaper_v1.2_FR.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/Factom_Whitepaper_v1.2_FR.pdf -------------------------------------------------------------------------------- /Identity.md: -------------------------------------------------------------------------------- 1 | Identity in Factom 2 | =============== 3 | 4 | Factom Servers and Users who vote for them must create an identity. The identity is contained within a set of chains. This document describes an identity system primarily intended for internal management. Identity in general is a powerful concept useful for numerous applications, and tying time to it is also very powerful. For example, it solves problems of authenticity of signed data after private keys are compromised. Data signed before the compromise can still be relied on. Old data does not need to be resigned with the new key to maintain authenticity. Identities from other contexts, like software distribution signing, should use independent identity schemes, but can model them on this design. Other identity systems probably don't need the chainID mining aspects, since that is primarily to consolidate internal identity chains into future network segments. Eliminating mining also would allow a deterministic directory structure with the extIDs as folder paths. 5 | 6 | An Identity Chain 7 | ----------------- 8 | 9 | To establish an identity, a user needs to create several private keys, combine the public key hashes into a Chain Name, mine to get an appropriate prefix, then create a new chain with that Chain Name. Entry Credit keys are then linked to that identity. The identity then lends support to other identities, then ultimately to a server candidate, which may be a Federated or Audit server. 10 | 11 | #### Root Factom Identity 12 | 13 | A Factom identity is bootstrapped with a series of keys. Different logical identity subchains are associated with the root identity to catalog specific functions. The subchains segregate various types of data, so it does not need to be downloaded if the data is ignorable. 14 | 15 | ### Human Readable Identity Keys 16 | 17 | The first step in creating an identity is to create 4 levels of private keys, with level 1 being the lowest security online key. 18 | 19 | The Factom identities are managed by ed25519 digital signatures. The keys can be represented in base58 form with checksums to allow for human interfacing. 20 | 21 | Four different private keys are created, each a 32 byte random number. The 4 different levels are presented to the user with 4 different prefixes, resulting in address that start with sk1, sk2, sk3, and sk4. 22 | 23 | The conversion to human readable form is very similar to Entry Credit keys, and only differs by having an extra byte in the prefix. The prefix is prepended to the private key, then that is hashed with SHA256d, and the first 4 bytes of the SHA256d is appended to the end of the key. The entire thing is converted to base58. 24 | 25 | The prefixes and key ranges are shown here: 26 | 27 | The secret part of the identity keys: 28 | 29 | | prefix | All Zeros | All Ones | 30 | | ----------------- | ---------------- | --------------- | 31 | | 4db6c9 | sk11pz4AG9XgB1eNVkbppYAWsgyg7sftDXqBASsagKJqvVRKYodCU | sk13mjEPiBP6rEnC5TWQSY7qUTtnjbKb4QcpEZ7jNDJVvsupCg9DV | 32 | | 4db6e7 | sk229KM7j76STogyvuoDSWn8rvT6bRB1VoSMHgC5KD8W88E26iQM3 | sk2464XMB8ws92poWcho4WjTThNDD8piLgDzMnSE178A8WiU46gJy | 33 | | 4db705 | sk32Tee5C4fCkbjbN4zc4VPkr9vX4xg8n53XQuWZx6xAKm2cAP7gv | sk34QPpJe6WdRpsQwmuBgVM5SvqdggKqcwqAV1kidzwpL9X86sVi9 | 34 | | 4db723 | sk42myw2f2Dy3PnCoEBzgU1NqPPwYWBG4LehY8q4azmpXPqGY6Bqu | sk44ij7G745Picv2Nw6aJTxhSAK4ADpxuDSLcF5DGtmUXnKs6XT1F | 35 | 36 | 37 | The public part of the identity keys: 38 | 39 | | prefix | All Zeros | All Ones | 40 | | ----------------- | ---------------- | --------------- | 41 | | 3fbeba | id11qFJ7fe26N29hrY3f1gUQC7UYArUg2GEy1rpPp2ExbnJdSj3mN | id13mzUM7fsX3FHXSExEdgRintPena8Ns92c5y4YVvEccAoEttNTG | 42 | | 3fbed8 | id229ab58barepCKHhF3df62BLwxePyoJXr9968tSv4coR7LbtoFL | id246KmJadSHL3L8sQ9dFf3Ln7s5G7dW9QdnDCP38p4GoobsaTCHN | 43 | | 3fbef6 | id32Tut2bZ9cwcEvirSSFdheAaRP7wUvaoTKGKTP5otH13uzjcHTd | id34Qf4G3b13cqNkJZM1sdexmMLVjf8dRgExLRhXmhsw1SQSzthdm | 44 | | 3fbf14 | id42nFAz4WiPEQHYA1dpscKG9otobUz3s54VPYmsihhwCgibnEPW5 | id44izMDWYZoudRMjiYQVcGakaovDCdkhwr8Tf22QbhbD5D934waE | 45 | 46 | 47 | 48 | ### Factom Identity Chain Creation 49 | 50 | Messages and updates for an identity occur within an identity chain. There is a single root chain per identity, and the 32 byte ChainID of the identity is how the identity is referenced. A Factom identity is not explicitly tied to any real world human/organizational entity. A real world entity can claim an identity, but it is not necessary. 51 | 52 | An identity is established with the first entry in the chain. It is updated with entries signed by keys placed in the first entry. The public keys are placed in the Chain Name, so the initial identity keys largely make up the identity. 53 | 54 | There is something akin to mining in the identity creation. This marginally rate limits identity creation. It also makes future P2P network segmentation possible based solely on the ChainID. All the chains related to voting would share the first few bytes and be on the same network segment. All the ChainIDs related to identity start with 0x888888. 55 | 56 | First, 4 random 32 bytes are chosen. These are the 4 different private keys of the different levels. 57 | 58 | | Level | Four Private Keys | Human Readable Equivalent | 59 | | ---- | ----------------- | ----------------- | 60 | | 1 | f84a80f204c8e5e4369a80336919f55885d0b093505d84b80d12f9c08b81cd5e | sk13iLKJfxNQg8vpSmjacEgEQAnXkn7rbjd5ewexc1Un5wVPa7KTk | 61 | | 2 | 2bb967a78b081fafef17818c2a4c2ba8dbefcd89664ff18f6ba926b55e00b601 | sk22UaDys2Mzg2pUCsToo9aKgxubJFnZN5Bc2LXfV59VxMvXXKwXa | 62 | | 3 | 09d51ae7cc0dbc597356ab1ada078457277875c81989c5db0ae6f4bf86ccea5f | sk32Xyo9kmjtNqRUfRd3ZhU56NZd8M1nR61tdBaCLSQRdhUCk4yiM | 63 | | 4 | 72644033bdd70b8fec7aa1fea50b0c5f7dfadb1bce76aa15d9564bf71c62b160 | sk43eMusQuvvChoGNn1VZZwbAH8BtKJSZNC7ZWoz1Vc4Y3greLA45 | 64 | 65 | Raw public keys are created from those private keys. These are treated similar to Factoid RCDs. The pubkeys are prepended with a byte 0x01 and hashed with SHA256d. 66 | 67 | The four keys above would result in these identity keys: 68 | 69 | | Level | Four Identity Keys | Human Readable Equivalent | 70 | | ---- | ----------------- | ----------------- | 71 | | 1 | 3f2b77bca02392c95149dc769a78bc758b1037b6a546011b163af0d492b1bcc0 | id12K4tCXKcJJYxJmZ1UY9EuKPvtGVAjo32xySMKNUahbmRcsqFgW | 72 | | 2 | 58190cd60b8a3dd32f3e836e8f1f0b13e9ca1afff16416806c798f8d944c2c72 | id22pNvsaMWf9qxWFrmfQpwFJiKQoWfKmBwVgQtdvqVZuqzGmrFNY | 73 | | 3 | b246833125481636108cedc2961338c1368c41c73e2c6e016e224dfe41f0ac23 | id33pRgpm8ufXNGxtW7n5FgdGP6afXKjU4LfVmgfC8Yaq6LyYq2wA | 74 | | 4 | 12db35739303a13861c14862424e90f116a594eaee25811955423dce33e500b6 | id42vYqBB63eoSz8DHozEwtCaLbEwvBTG9pWgD3D5CCaHWy1gCjF5 | 75 | 76 | A Chain Name is constructed with 7 elements. The first element is a binary string 0 signifying the version. The second element is ASCII bytes "Identity Chain". The third element is the level 1 identity key in binary form. Elements 4-6 are levels 2-4. The 7th element is a nonce which is iterated until the first 3 bytes match 0x888888. The Entry content is not defined, and does not affect the Chain Name. On a 5 year old laptop the search took about 1 minute per core. 77 | 78 | Chain Name = [00] [4964656E7469747920436861696E] [3f2b77bca02392c95149dc769a78bc758b1037b6a546011b163af0d492b1bcc0] [58190cd60b8a3dd32f3e836e8f1f0b13e9ca1afff16416806c798f8d944c2c72] [b246833125481636108cedc2961338c1368c41c73e2c6e016e224dfe41f0ac23] [12db35739303a13861c14862424e90f116a594eaee25811955423dce33e500b6] [nonce] 79 | 80 | After iterating and finding a nonce 0000000000c512c7 we have a chainID 888888d027c59579fc47a6fc6c4a5c0409c7c39bc38a86cb5fc0069978493762 81 | 82 | 83 | 84 | ### Factom Identity Registration 85 | 86 | In order for Factom to pay attention to any individual identity, the identity must register itself. The registration should occur after the chain creation to prevent a 12 hour long denial-of-chain attack (detailed elsewhere). For the registration to take effect, the corresponding identity chain must be created within 144 blocks (normally 24 hours). Any updates to the identity (such as adding EC keys or updating keys) must occur during or after the block it was registered in. This prevents events being reinterpreted retroactively. 87 | 88 | An identity only needs to be registered once, and cannot be unregistered. 89 | 90 | The registration message has 5 ExtIDs. The first ExtID is a binary string 0 signifying the version. The second ExtID has 24 ASCII bytes "Register Factom Identity". It is a long string so there is no overlap in message interpretation with other message types. It also makes it clear that a hash is not being signed, and can be filtered on this string in potential future messages. The third ExtID is the binary encoded ChainID of the identity. It will start with 888888. The 4th ExtID is the preimage to the identity key. It includes the type prefix (0x01) and the raw ed25519 pubkey. The 5th ExtID is the signature of the first, second, and third ExtIDs serialized together. 91 | 92 | The entry would consist of only ExtIDs and look like this: 93 | 94 | [0 (version)] [Register Factom Identity] [identity ChainID] [identity key preimage] [signature of version through ChainID] 95 | 96 | [00] [526567697374657220466163746F6D204964656E74697479] [888888d027c59579fc47a6fc6c4a5c0409c7c39bc38a86cb5fc0069978493762] [0125b0e7fd5e68b4dec40ca0cd2db66be84c02fe6404b696c396e3909079820f61] [764974ae61de0d57507b80da61a809382e699cf0e31be44a5d357bd6c93d12fa6746b29c80f7184bd3c715eb910035d4dac2d8ecb1c4b731692e68631c69a503] 97 | 98 | The identity registration chainID is 888888001750ede0eff4b05f0c3f557890b256450cabbb84cada937f9c258327 with a chain name of "Factom Identity Registration Chain" and "44079090249". 99 | 100 | 101 | ### Coinbase Address 102 | 103 | When an identity desires to receive a reward from the protocol, they need to provide an address for any Factoids that they receive. This example registers a factoid address with all zeros as the private key. The Factoid address being registered is an RCD hash. 104 | 105 | This Entry goes into the Root Factom Identity Chain. 106 | 107 | The message is a Factom Entry with several extIDs holding the various parts. The first part is a version binary string 0. The second is the ASCII string "Coinbase Address". The third is the root identity ChainID. Forth is the new Factoid address being asserted. 5th is the timestamp with an 8 byte epoch time. Next is the identity key preimage of the lowest level identity key (id1). 7th is the signature of the serialized version, text, chainID, new factoid address, and the timestamp. 108 | 109 | [0 (version)] [Coinbase Address] [identity ChainID] [new factoid address] [timestamp] [identity key preimage] [signature of version through timestamp] 110 | 111 | [00] [436F696E626173652041646472657373] [888888d027c59579fc47a6fc6c4a5c0409c7c39bc38a86cb5fc0069978493762] [031cce24bcc43b596af105167de2c03603c20ada3314a7cfb47befcad4883e6f] [00000000495EAA80] [0125b0e7fd5e68b4dec40ca0cd2db66be84c02fe6404b696c396e3909079820f61] [e08f8c763b1512d05bb6a6cf503e884a24ea6b7af0d30df1dff30444a9b9ba2db20d40555afddfcd5e03f737afaa7be78b6129787d9a561417531d263eaabb04] 112 | 113 | 114 | 115 | #### Server Management Subchain 116 | 117 | Messages related to being a Federated, Audit, or Candidate server would live in this subchain. The root identity chain links to it. This chain is only needed if the identity wants to be a server. It adds keys which are used to sign the Bitcoin anchors as well as keys to sign the directory blocks. 118 | 119 | ### Server Management Subchain Creation 120 | 121 | This chain is created after the identity chain is known. The Chain Name first element is a version, 0. The second is the ASCII string "Server Management". The 3rd consists of the root identity chainID. The 4th is a nonce which makes the first 6 bytes of the chainID match 0x888888. Since the root identity chainID would be known at this point, the management subchain would be susceptible to a denial-of-chain attack. To counter this, a random starting value for the nonce can be chosen. This makes it far less likely that an attacker could predict which subchain you are about to create. 122 | 123 | Chain Name = [00] [536572766572204D616E6167656D656E74] [888888d027c59579fc47a6fc6c4a5c0409c7c39bc38a86cb5fc0069978493762] [nonce] 124 | 125 | After iterating and finding a nonce 98765432103e2fbb we have a chainID 8888881d59de393d9acc2b89116bc5a2dd0d0377af7a5e04bc7394149a6dbe23 126 | 127 | ### Server Management Subchain Registration 128 | 129 | The Server Management subchain needs to be discoverable. The identity will place a signed Entry in their root identity chain which points to the subchain. 130 | 131 | It is very similar to the Factom identity registration message. 132 | 133 | [0 (version)] [Register Server Management] [subchain ChainID] [identity key preimage] [signature of version through ChainID] 134 | 135 | [00] [526567697374657220536572766572204D616E6167656D656E74] [8888881d59de393d9acc2b89116bc5a2dd0d0377af7a5e04bc7394149a6dbe23] [0125b0e7fd5e68b4dec40ca0cd2db66be84c02fe6404b696c396e3909079820f61] [fcb3b9dd3cc9f09b61a07e859d13a569d481508f0d5e672f9412080255ee398428fb2c488e0c3d291218f573612badf84efa63439bbcdd3ca265a31074107e04] 136 | 137 | This message is then placed into the root identity chain. Only one server management subchain is allowed. In the case of multiple messages, the valid one is the first message that also has a Chain which exists. For example, if there are two messages registering Chain B and A in that order, but Chain A is created first, then Chain A is considered the valid one. The chain must be created within 144 blocks (normally 24 hours) of being registered. In case of a tie (both chains created in the same block, the first entry in the registration chain will be the winning subchain.) 138 | 139 | ### Add New Block Signing Key 140 | 141 | The Factom blockchain is signed with a key by each server. This key signs the Directory blocks, and those signatures are held in the Admin blocks. They are associated with the identity, but do not sign things other than the blocks. The public key is added to the Admin block by the Federated servers as part of the server promotion process. Before promotion, the key needs to be published to the server management subchain. Keys are not removed, but new keys replace older keys. To prevent replay attacks, a timestamp is included. To be valid, the key update must be the latest one seen. It also needs to be included in the blockchain between 12 hours +- of the message timestamp. (note: backup block signing key authorizations can be presigned offline in advance. Only 365 pre-prepared, signed messages would need to be held ready for broadcast to cover a year.) 142 | 143 | The message is a Factom Entry with several extIDs holding the various parts. The first part is a version binary string 0. The second is the ASCII string "New Block Signing Key". The third is the root identity ChainID. Forth is the new public key being asserted. 5th is the timestamp with an 8 byte epoch time. Next is the identity key preimage. 7th is the signature of the serialized version, text, chainID, new key, and the timestamp. 144 | 145 | [0 (version)] [New Block Signing Key] [identity ChainID] [new key] [timestamp] [identity key preimage] [signature of version through timestamp] 146 | 147 | [00] [4E657720426C6F636B205369676E696E67204B6579] [888888d027c59579fc47a6fc6c4a5c0409c7c39bc38a86cb5fc0069978493762] [8473745873ec04073ecf005b0d2b6cfe2f05f88f025e0c0a83a40d1de696a9cb] [00000000495EAA80] [0125b0e7fd5e68b4dec40ca0cd2db66be84c02fe6404b696c396e3909079820f61] [0bb2cab2904a014bd915b276c350821620edb432ddfbceed3896e87e591a412712b7db6d8dad1a8313138ea919bbc9b7a1bd4ffe1d84d558b8a78ef7746f480d] 148 | 149 | 150 | ### Add New Bitcoin Key 151 | 152 | Factom uses the Bitcoin blockchain as a sibyl resistant communication channel, as well as a method to detect alterations to history. The bitcoin keys are published in the identity's server management subchain. When the server is promoted, or when a new key is added, the new Bitcoin key is published in the Admin block. If a Federated server publishes an update to its chain, the Federated servers place it in the next Admin block. Factom doesn't use this in M2 or on the launch of M3, although these are present in the blockchain. 153 | 154 | Like the identity keys, there are multiple levels of authority for the Bitcoin keys. This allows servers to have an out of band backup signaling method when Bitcoin keys are stolen. Anchors placed by higher level keys will alert clients that the lower level Bitcoin key(s) are considered compromised, and not to trust anchors from lower level keys. 155 | 156 | Multiple levels of bitcoin keys are specified, but only 1 level is need initially. The max is 4. The same rules for timing and priority level apply to this message as apply to the New Block Signing message. 157 | 158 | Bitcoin keys can either be P2PKH or P2SH. The address type byte is set as follows: 0=P2PKH 1=P2SH. 159 | 160 | The message is an entry with multiple extIDs. It has a version, a text string saying "New Bitcoin Key". It specifies the root identity chainID. Next is a byte signifying the bitcoin key level. It is 0 origin indexed, so with only 1 key it would be 0x00. The next extID specifies what type of Bitcoin key is used, P2PKH or P2SH. Next is the 20 byte Bitcoin key. Seventh is a timestamp, which prevents replay attacks. Eighth is the identity key preimage. Last is the signature of the serialized version through the timestamp. 161 | 162 | [0 (version)] [New Bitcoin Key] [identity ChainID] [Bitcoin key level] [type byte] [new key] [timestamp] [identity key preimage] [signature of version through timestamp] 163 | 164 | [00] [4e657720426974636f696e204b6579] [888888d027c59579fc47a6fc6c4a5c0409c7c39bc38a86cb5fc0069978493762] [00] [00] [c5b7fd920dce5f61934e792c7e6fcc829aff533d] [00000000495EAA80] [0125b0e7fd5e68b4dec40ca0cd2db66be84c02fe6404b696c396e3909079820f61] [379d64dd36ba724539ce19adb05b9a6a98cc3e3171785553e2985f5542a3ce3bf470ef78a884eee2ba75c9f2cfa64f21d3ace4dc981daeb3c00352dbb19a1e0c] 165 | 166 | 167 | 168 | ### Add New Matryoshka Hash 169 | 170 | Factom gets a set of randomness from a series of revealed SHA256 hash preimages. To enforce these to be hash preimages, the last hash in a long hash chain is published. A server will reveal sequential preimages, which are called Matryoshka hashes or M-hashes. This message publishes the outermost hash, which is placed in the Admin block when the server is promoted. Factom doesn't use this in M2 or on the launch of M3, although these are present in the blockchain. 171 | 172 | The new M-hash message has the same timing and priority level rules at the block signing key message. 173 | 174 | It starts with the version and the text "New Matryoshka Hash". Next is the root identity chainID. Forth is the outermost M-hash. Fifth is a timestamp. Sixth is the root identity key preimage. Last is the signature of the version through the timestamp. 175 | 176 | [0 (version)] [New Matryoshka Hash] [identity ChainID] [new SHA256 M-hash] [timestamp] [identity key preimage] [signature of version through timestamp] 177 | 178 | [00] [4e6577204d617472796f73686b612048617368] [888888d027c59579fc47a6fc6c4a5c0409c7c39bc38a86cb5fc0069978493762] [bf1e78e5755851242a2ebf703e8bf6aca1af9dbae09ebc495cd2da220e5d370f] [00000000495EAA80] [0125b0e7fd5e68b4dec40ca0cd2db66be84c02fe6404b696c396e3909079820f61] [b1bc034cf75d4ebf7c4025a6b6b15c8f11a4384dcb043160711f19da9f4efb1315d84811b2247bb703732c2116b464781daf5efe75efd4adc641fee220ec660c] 179 | 180 | 181 | 182 | ### Add Server Efficiency 183 | 184 | The Factom Authority servers are rewarded with new Factoids as part of their service to the protocol. They are each rewarded up to 6.4 Factoids every 25 blocks. As part of being good stewards of the protocol, Authority Servers can run a more efficient operation. They can opt to yeild some percentage of their reward to the Grant Pool. They would define that efficiency with this message. A 100% efficiency leaves all the Factoids in the protocol, while 0% puts the entire reward into the coinbase. 185 | 186 | This message needs to be in the server management subchain. If it is not, the default is 100% efficiency. If the message specifies >100% efficiency, the coinbase descriptor defaults to 100% efficiency. Later Server Efficiency messages update older messages. To prevent replay attacks, a timestamp is included. To be valid, the efficiency update must be the latest one seen. It also needs to be included in the blockchain between 12 hours +- of the message timestamp. 187 | 188 | The efficiency is serialized as a 16 bit unsigned integer. The percentage is in fixed point format with 2 decimals, so the maximum efficiency of 100% = 10000. An efficency of 49.52% = 4952 = 0x1358. 189 | 190 | With a 49.52% efficiency almost half of the 6.4 Factoid Authority reward is yeilded to the Grant Pool. The coinbase would have an output of 3.23072 Factoids for this server. The Grant Pool would increase by 3.16928 FCT from this server. 191 | 192 | The message is a Factom Entry with several extIDs holding the various parts. The first part is a version binary string 0. The second is the ASCII string "Server Efficiency". The third is the root identity ChainID. Forth is the new efficiency being asserted. 5th is the timestamp with an 8 byte epoch time. Next is the identity key preimage of the lowest level identity key (id1). 7th is the signature of the serialized version, text, chainID, new efficiency, and the timestamp. 193 | 194 | [0 (version)] [Server Efficiency] [identity ChainID] [new efficiency] [timestamp] [identity key preimage] [signature of version through timestamp] 195 | 196 | [00] [53657276657220456666696369656E6379] [888888d027c59579fc47a6fc6c4a5c0409c7c39bc38a86cb5fc0069978493762] [1358] [00000000495EAA80] [0125b0e7fd5e68b4dec40ca0cd2db66be84c02fe6404b696c396e3909079820f61] [2954c40f889d49a561d0ac419741f7efd11e145a99b67485fb8f7c3e3c42d3c698d50866beffbc09032243ab3d375b4c962745c09d1a184d91e5ba69762b4e09] 197 | 198 | 199 | 200 | ### Coinbase Cancel 201 | 202 | There is a chance that a Coinbase Descriptor gets created which is detrimental to the protocol. In order to protect the protocol against economic damage, a pending coinbase transaction can be modified. Since the 1000 block delay between the Coinbase Descriptor and the Coinbase was designed to give the community time to react to unexpected new Factoids. As such, the only change that can be made to a pending coinbase is to reduce one of the outputs to zero, removing it as an output. The canceled output would be retained by the Grant Pool. This means that the system doesn't support generating more Factoids than were described, only fewer. An individual line in a particular coinbase descriptor at a block height is the unit which is addressed. 203 | 204 | The process begins with an Authority node discovering that a coinbase descriptor is wrong. After forming social consensus with several other Authority nodes, they will create the Coinbase Cancel message and write it to their Server Management Subchain. The message specifies a block height containing the Admin block with the offending output. It also specifies an index into the coinbase descriptor of the specific output to be canceled (0 origin indexed). Both fields are 4 bytes and big endian unsigned integers. 205 | 206 | The message is only valid when it appears in an entry block after the block that the coinbase descriptor appears in and the block just before the coinbase. 207 | 208 | 209 | The message is a Factom Entry with several extIDs holding the various parts. The first part is a version binary string 0. The second is the ASCII string "Coinbase Cancel". The third is the root identity ChainID. Fourth is the Coinbase Descriptor Height with a cancelation. 5th is the index into the Coinbase Descriptor. Next is the identity key preimage of the lowest level identity key (id1). 7th is the signature of the serialized version, text, chainID, Coinbase Descriptor height, and the index into the Coinbase Descriptor. 210 | 211 | [0 (version)] [Coinbase Cancel] [identity ChainID] [Descriptor height] [Descriptor index] [identity key preimage] [signature of version through timestamp] 212 | 213 | [00] [436f696e626173652043616e63656c] [888888d027c59579fc47a6fc6c4a5c0409c7c39bc38a86cb5fc0069978493762] [00030d40] [00000005] [0125b0e7fd5e68b4dec40ca0cd2db66be84c02fe6404b696c396e3909079820f61] [68c06b195771f801ff216c0ba98de485e54410c0765d662118aac389e319dcfdee12d11915206ab7d35f6f028584406156840fc30219111750bb1b0bc2b06106] 214 | 215 | 216 | 217 | 218 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | This is free and unencumbered software released into the public domain. 2 | 3 | Anyone is free to copy, modify, publish, use, compile, sell, or 4 | distribute this software, either in source code form or as a compiled 5 | binary, for any purpose, commercial or non-commercial, and by any 6 | means. 7 | 8 | In jurisdictions that recognize copyright laws, the author or authors 9 | of this software dedicate any and all copyright interest in the 10 | software to the public domain. We make this dedication for the benefit 11 | of the public at large and to the detriment of our heirs and 12 | successors. We intend this dedication to be an overt act of 13 | relinquishment in perpetuity of all present and future rights to this 14 | software under copyright law. 15 | 16 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 17 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 18 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 19 | IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR 20 | OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 21 | ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 22 | OTHER DEALINGS IN THE SOFTWARE. 23 | 24 | For more information, please refer to -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | Factom 2 | ============= 3 | 4 | Overview 5 | -------- 6 | 7 | Factom is an extension to the Bitcoin blockchain that solves the three core problems of all Bitcoin 2.0 applications: Speed, Cost, and Bloat. 8 | 9 | The Bitcoin blockchain is a trustless, permanent system of record for Bitcoin transactions, secured by 10,000+ nodes across the world. Factom is a simple way to extend this technology to support Bitcoin 2.0, or applications that need such a system of record, but whose transactions do not primarily involve Bitcoin. These applications often encode their information into Bitcoin transactions, which may be slower, more expensive, and add many transactions to the Bitcoin blockchain that are not actually Bitcoin transactions (something many call "blockchain bloat"). 10 | 11 | Instead of writing every transaction directly to the blockchain, Factom allows Bitcoin 2.0 applications to write unlimited numbers of entries to many distinct Factom chains. These entries are organized into hierarchical sets of blocks. These blocks are then used to compute a single hash every 10 minutes, which is stored in the Bitcoin blockchain. This design allows applications to write transactions faster, at much a lower cost, and with nearly no blockchain bloat. 12 | 13 | At the most basic level, Factom provides "Proof of Existence." Any digital artifact can be reduced to a hash, a relatively small 32 byte number, that proves an artifact's existence. Adding that hash to the Bitcoin blockchain proves the existence of that artifact at a known point in time. Factom extends this idea. Each Factom subsystem in the group provides a "Proof of Process." Proof of each step in a process can be entered into a "Factom chain" of provable events. One obvious sort of Factom chain is a log. A security camera can log a stream of signatures, proving video was taken at a point in time, and that the video has not be altered. A Coin is also a process, one proving that coins existed and were exchanged. The steps in processing a title for Real Estate is a process, and one where a clear timeline of process can be very helpful. 14 | 15 | Factom Chains are constructed from entries crafted to support a wide range of applications. An entry can be used to prove data existed at a point in time. And other Factom Chains and demonstrate their reaction to such data. In other words, a Factom chain is a sequence of entries that define some progression of state, and the data that drove that progression. Each Factom chain has its own rules, and entries in these Chains are constrained by those rules. 16 | 17 | The architecture for Factom allows for the easy construction of tokens or coins, securities, smart contracts, etc. 18 | -------------------------------------------------------------------------------- /SpecialChains.md: -------------------------------------------------------------------------------- 1 | # Special Chains 2 | 3 | We have a few chains we handle in a special fashion, which must have valid entries to include in these chains. 4 | 5 | * Factoid Chain -- chain of all Factoid transactions 6 | * Entry Credit Chain -- chain of all Entry Credit transactions 7 | * System Chain -- Parameters driving Factom 8 | * Software Sale Chain -- Documents the Factoids purchased during the software sale. 9 | 10 | ## Software Sale Chain 11 | 12 | A special chain used to document the Factom software sale. Validates the genesis block. Entries will include: 13 | 14 | Each entry is the UTC timestamp to start the period, followed by the BTC price. The next Entry start 15 | is the end of the previous. A 0 price marks the end of the sale. The sale starts on March 31, 2015 at 16 | 10:00 am CDT. There are 5 one week periods, and the last period last 10 days ending on May 15, 2015 at 10:00 am 17 | CDT. 18 | 19 | The followint entry will be made in the Software Sale Chain 20 | 21 | ```JSON 22 | { 23 | "1427814000" : 2000, 24 | "1428418800" : 1900, 25 | "1429023600" : 1800, 26 | "1429628400" : 1700, 27 | "1430233200" : 1600, 28 | "1431097200" : 1500 , 29 | "1431702000" : 0 30 | } 31 | ``` 32 | 33 | A Summary Entry will document the totals for the sale: 34 | 35 | ```JSON 36 | { 37 | "Sale Summary" : { 38 | "total software sale BTC" : "#BTC", 39 | "total software sale factoids" : "#factoids", 40 | "total issued to contributors" : "#factoids", 41 | "total software sold to early purchasers" : "#factoids" 42 | } 43 | } 44 | ``` 45 | 46 | The actual distribution will be documented with a list of the purchases and the destination addresses. Any number of the entries of the following form will document the sales: 47 | 48 | ```JSON 49 | { 50 | "factoidSales" : [ 51 | [ "", "" , "", "" ] 52 | [ "", "" , "", "" ] 53 | ] 54 | } 55 | ``` 56 | 57 | Any number of contributor records of the form: 58 | 59 | ```JSON 60 | { 61 | "contributors" : [ 62 | [ "", "" ] 63 | ] 64 | } 65 | ``` 66 | 67 | Any number of early buyer records of the form: 68 | 69 | ```JSON 70 | { 71 | "earlyBuyer" : [ 72 | [ "", "" ], 73 | [ "", "" ] 74 | ] 75 | } 76 | ``` 77 | 78 | ## Factoid Chain 79 | 80 | Contains only valid Factoid Transactions. The Genesis Block for Factom will do a mass generation of Factoids to all the Factoid Addresses as defined by the crowd sale. Individuals participating in the presale will have to provide addresses, and people who were initial contributors will need to provide addresses in order to receive their Factoids. For individuals who have not provided addresses by the time we generate the Genesis Block, the Factom Foundation will create address, and transfer the Factoids once notified of the proper address. 81 | 82 | 83 | ## System Chain 84 | 85 | Discussed elsewhere 86 | 87 | ## Identity Chain 88 | 89 | Each Federated Server, or voter, must have an identity chain. This serves as the user’s identity, defines their public keys, their Entry Credit keys for voting, and more. 90 | 91 | An Identity is defined by a Factom Chain, and a series of Entries holding JSON data. 92 | 93 | The first Entry must define the security for the Identity. The JSON must include: 94 | 95 | * Version -- Version of the Identity, if it is to be used with Factom 96 | * Key Type -- What type of key used. For now we support ECDSA and Ed25519. More key types may be supported in the future. 97 | * Four keys, by priority. The higher priority keys can be used to regain control of an identity should an identity be compromised, or make changes to the Identity. 98 | 99 | 100 | ### Example Identity: 101 | 102 | “Server” “Factom Server 1” has a Chain ID of 103 | 104 | e367cebf263e8f2d1d56a38287ccbf051be853eea44333cb8b8c52678ea66b5e 105 | 106 | And the first Entry is: 107 | 108 | ```JSON 109 | { 110 | "Key List Type" : "Identity" , 111 | "type" : "Ed25519", 112 | "1" : "de8634289a978df57c5b07a3423b01e1a1c37263506c43b739d770e6d5924d92", 113 | "type" : "ECDSA", 114 | "2" : "5dbfc8221051e0ce6a26e518ba7b0f2d0291e8a1ede150c51695470f2c2a1423", 115 | "3" : "b90b0c1f73b142faabeb3113bfbf26a8156b0e6d2c5897675a9b9dd1443822e1", 116 | "4" : "41d21362bd5f2c07a316defa69d19ce41ab0bbd96bd0b0a27792a6ad7d7e44f8" 117 | } 118 | ``` 119 | 120 | The 4th level signature would be the one used to sign additional entries to the Identity. These additional entries can be used to change the keys, change the security, add a set of Bitcoin addresses, etc. 121 | 122 | The Entry to add Bitcoin addresses would look like this: 123 | 124 | ```JSON 125 | { 126 | "Key List Type" : "Bitcoin", 127 | "1" : "1EYP7NzhfugjKvJH3BQTU7J6cQhCWWVYHx", 128 | "2" : "19jPEV4sf4sahupcawFD5vZ4Z3811HZB6i", 129 | "3" : "1GTALs4J3tzyknyY2k7DdGDFLTPTKnHYyk", 130 | "4" : "16NZ2R5YrMn1C9n5PcrFB1QrMoFWCmbNim" 131 | } 132 | ``` 133 | 134 | Any Identity used to back a server must have a Bitcoin Entry. The 4th level address is what is used to write entries into Factom, and the higher priority addresses are used to manage situations where the 4th level address has been compromised. 135 | 136 | Other entry types are possible. 137 | -------------------------------------------------------------------------------- /communityTesterDirections.md: -------------------------------------------------------------------------------- 1 | Factom Community Tester Install Guide 2 | ========== 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | **Note: These are outdated instructions. Please see the new instructions located [here](installFromSourceDirections.md).** 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | To see how factom is doing, go to http://factomstatus.com/ 22 | 23 | To examine your local factomd status, point your browser to: http://localhost:8090/controlpanel 24 | 25 | 26 | ### Prepare Operating System 27 | 28 | The most testing to date has been done under Linux. To get the best testing experience, it should be done on Linux. That will also help us recreate the bugs you experience better. If you are running Windows, please install a virtual machine to run Factom. On a Mac, the only differences are with installing Hg and Git. Installing on Windows has been known to work, but is not covered here. 29 | 30 | Here are some good directions to get a virtual machine installed with Linux. http://www.instructables.com/id/Introduction-38/?ALLSTEPS 31 | 32 | The following are assuming you are using the 64 bit version of Ubuntu, or one of its descendant projects like xubuntu or mint. 33 | 34 | #### Install the go language and dependencies, then setup GOPATH 35 | 36 | ###### Install Package Managers 37 | 38 | In a terminal window, install Git and Mercurial 39 | 40 | On Linux: 41 | ``` 42 | sudo apt-get install git mercurial 43 | ``` 44 | 45 | On Mac: 46 | Steps 1 and 3 should be enough in this tutuorial: 47 | https://confluence.atlassian.com/pages/viewpage.action?pageId=269981802 48 | 49 | ###### Install Golang 50 | 51 | Download latest version of go https://golang.org/dl/ This example uses 64 bit Linux and 1.5.1 is the latest version. 52 | ``` 53 | sudo tar -C /usr/local -xzf go1.5.1.linux-amd64.tar.gz 54 | ``` 55 | 56 | On Mac, installing go this way should work: 57 | http://www.cyberciti.biz/faq/installing-go-programming-language-on-mac-os-x/ 58 | 59 | 60 | ###### Setup Paths 61 | 62 | Put the go binary directory in you path. 63 | Open the file `~/.profile` and add these lines to the bottom. If they are not exact, then your Linux may not be bootable. 64 | ``` 65 | export PATH=$PATH:/usr/local/go/bin 66 | ``` 67 | Now setup GOPATH 68 | In the same `~/.profile` file and add these lines to the bottom. If they are not exact, then your Linux may not be bootable. 69 | ``` 70 | export GOPATH=$HOME/go 71 | export PATH=$PATH:$GOPATH/bin 72 | ``` 73 | **logout and login**. This is the most straightforward way to run/test these changes. 74 | 75 | 76 | ### Install Factom 77 | 78 | Factom is currently developed in two different channels in Github. The bleeding edge is in the development branch, which may not even compile. The version intended for testing is in the master branch. These directions install the master branch. 79 | ``` 80 | go get -v -u github.com/FactomProject/FactomCode/factomd 81 | go get -v -u github.com/FactomProject/fctwallet 82 | go get -v -u github.com/FactomProject/factom-cli 83 | go get -v -u github.com/FactomProject/walletapp 84 | ``` 85 | copy the config file 86 | ``` 87 | mkdir ~/.factom 88 | cp ~/go/src/github.com/FactomProject/FactomCode/factomd/factomd.conf ~/.factom/factomd.conf 89 | ``` 90 | 91 | ### Run Factom 92 | 93 | Factom is run as 3 command line programs for this version. First, there is factomd. It connects to the server and handles connections to the internet. Second there is fctwallet. It handles the complexity of preparing the factoid transactions. Third is factom-cli. It is currently how users are expected to interact with Factom. Also factom-cli serves as an example of how to make API calls. Proper API documentation is forthcoming. 94 | 95 | Open 3 command line windows. In the first one, run `factomd`. It should show lots of technical outputs showing what it is doing. Leave it running. 96 | ![factomd](/images/factomd.png) 97 | If factomd complains about not connecting, make sure your firewall allows connections out to port 8108 (1FAC in hex). 98 | 99 | 100 | In the second command line window, run `fctwallet`. It will have very little output. It will show more output after factom-cli is run though. 101 | ![fctwallet](/images/fctwallet.png) 102 | 103 | In a sandbox, run this script to purchase ECs: 104 | `~/go/src/github.com/FactomProject/factom-cli/setup.sh`. After the time passes a 10 minute mark (ie 11:39 -> 11:40) run `factom-cli balances` to see if your zeros EC address has a balance. This is the number of Entry Credits you can use to place Entries. This may take a while to parse the blockchain. 105 | ![factom-cli](/images/factom-cli.png) 106 | 107 | After the script has been run, you can now create your own Chains: 108 | 109 | `echo "hello world" | factom-cli mkchain -e thisIsAChainName -e moreChainNameHere zeros` makes a new Chain with Chain Name "thisIsAChainName" combined with "moreChainNameHere", paid for with the Entry Credit key named zeros. In the Entry's payload is the text string "hello world". It returns "Creating Chain: 23985c922e9cdd5ec09c7f52a7c715bc9e26295778ead5d54e30a0a6215783c8" which is the ChainID for the chain name "thisIsAChainName" + "moreChainNameHere". 110 | 111 | Wait until a 10 minute window passes on the clock. 112 | 113 | `factom-cli get chain 23985c922e9cdd5ec09c7f52a7c715bc9e26295778ead5d54e30a0a6215783c8` asks for the hash of the latest Entry Block with the ChainID of 23985c922e9cdd5ec09c7f52a7c715bc9e26295778ead5d54e30a0a6215783c8. In this example it returned 791e3308911d7076ea2d8732f6ba723eaa027a51e76fca42fd9355062e4fe5d5. 114 | 115 | `factom-cli get eblock 791e3308911d7076ea2d8732f6ba723eaa027a51e76fca42fd9355062e4fe5d5` asks for the Entry Block with a hash of 791e3308911d7076ea2d8732f6ba723eaa027a51e76fca42fd9355062e4fe5d5. It returns: "BlockSequenceNumber: 0 116 | ChainID: 23985c922e9cdd5ec09c7f52a7c715bc9e26295778ead5d54e30a0a6215783c8 117 | PrevKeyMR: 0000000000000000000000000000000000000000000000000000000000000000 118 | TimeStamp: 1439967000 119 | EBEntry { 120 | TimeStamp 1439967420 121 | EntryHash 162fbef6320b28281b585f03a7d38e46ea7d9df14c7a7672df189c6fb0620c68 122 | } 123 | " with 2398... being the ChainID, 000... being the previous Entry Block hash. This value would be used with get eblock again to retrieve the preceeding block. It is 000... in this case because it is the first block in this Chain. 162f... is the Entry Hash of the Entry in this block. 124 | 125 | `factom-cli get entry 162fbef6320b28281b585f03a7d38e46ea7d9df14c7a7672df189c6fb0620c68` asks for the Entry learned about querying the Entry Block. It returns "ChainID: 23985c922e9cdd5ec09c7f52a7c715bc9e26295778ead5d54e30a0a6215783c8 126 | ExtID: 74686973497341436861696e4e616d65 127 | ExtID: 6d6f7265436861696e4e616d6548657265 128 | Content: 129 | 68 65 6c 6c 6f 20 77 6f | 72 6c 64 0a || "hello world\n" 130 | " 131 | 132 | `echo "hello2" | factom-cli put -e newextid -e anotherextid -c 23985c922e9cdd5ec09c7f52a7c715bc9e26295778ead5d54e30a0a6215783c8 zeros` adds another Entry into the Chain 239... It returns "Creating Entry: 7e25ca2e41cd03782aa3337a98f4a261aa2c00b904b7da2e67d96262a2f5a034". 133 | 134 | 135 | ##### More Examples 136 | 137 | When we reset the genesis block after a few days, these hashes wont work, but the basic commands still will. 138 | 139 | `factom-cli get head` gets a handle to the latest [Directory Block](https://github.com/FactomProject/FactomDocs/blob/master/factomDataStructureDetails.md#directory-block). It will return a hash like f32af3c2b7e91df83c2eb887c822776e6480bcc2dd04a5ddb1ce28dd57808f59 140 | 141 | 142 | It will also be anchored in the blockchain too. [Here](https://www.blocktrail.com/tBTC/tx/13c3d8bf7fded24918e291d8d535c452dde3b64d7f2e027121a1ddf78abe16b4) is the anchor for the above Directory Block. The op_return value gives 46610000000007faf32af3c2b7e91df83c2eb887c822776e6480bcc2dd04a5ddb1ce28dd57808f59. The rightmost 32 bytes are the dblock keymr (hash). the rightmost two bytes are Fa in ASCII. The bytes 0000000007fa decode to 2042. 143 | 144 | 145 | `factom-cli get dblock f32af3c2b7e91df83c2eb887c822776e6480bcc2dd04a5ddb1ce28dd57808f59` returns the data contained in the directory block. It will return something like: 146 | `&{ {abfddf912f66ecda3bbca5d7f72195d48f5cf9a9948346ad5090599b17c133df 0 2042} [{000000000000000000000000000000000000000000000000000000000000000a 39f8e58f86e6fb080ea938acc27129d84cb0518b136e63301f45bfd566191147} {000000000000000000000000000000000000000000000000000000000000000c 5174993458604fc9f036c10fdc421038544cfeac37a060dae1555cd47de8a302} {000000000000000000000000000000000000000000000000000000000000000f 826c33c79bde2a8082edb705fd8dd8e451b1d3dc67e3ad35f5ce5c4569c6b842}]}` 147 | 148 | The value abfddf912f66ecda3bbca5d7f72195d48f5cf9a9948346ad5090599b17c133df is the dblock hash of the previous block. `factom-cli get dblock abfddf912f66ecda3bbca5d7f72195d48f5cf9a9948346ad5090599b17c133df` will get the previous block, which can be repeated all the way to the genesis block. 149 | 150 | The 2042 value is the block height. There have been 2042 previous dblocks (first one is zero). 151 | 152 | The return value also shows 3 sub blocks which are referenced by this dblock. The 3 pairs that end in 000a, 000c, and 000f are the adminstrative, entry credit, and factoid blocks. They are not viewable at this time. 153 | 154 | When you make a new chain, it tells you the ChainID the Chain Name hashes to. `echo "hello" | factom-cli mkchain -e chainNameGoesHere zeros` returns Chain: 13ea4eb2b62c3bc5049746d964a64b4cbbe764a3f62a5fa2ec410542285c638a. 155 | 156 | After a minute, When you run `factom-cli get dblock 7e2e77727019369585e9ac0299110e90393f2edb9b078633467409e73d4027c9` it returns 157 | `&{ {907a6d004ed5a3b651af1ac80ff993bdebfc27abbb7f85f75e539bf4345a9e3f 0 2166} [{000000000000000000000000000000000000000000000000000000000000000a c8a29586d51b23a56fecbea15843ff65c77b05943c4286a35eb7a6dc751f0e83} {000000000000000000000000000000000000000000000000000000000000000c 775ed96b2868042a4b51986fd5bc2b6fc80581ba4076b461502511ad35e3e481} {000000000000000000000000000000000000000000000000000000000000000f af87dedc714127df084642be7930e4664b0374dddad2bb0d1cef17a4a15a122f} {13ea4eb2b62c3bc5049746d964a64b4cbbe764a3f62a5fa2ec410542285c638a 0d52effcd5d1a0542ce7fdac352ef5242c2827ee9406deae8b5cec60264683d4}]}` 158 | 159 | The value 13ea4eb2b6...42285c638a is paired with 0d52eff...60264683d4, which is the keymr of the Entry Block of the 13ea... chainID for that minute (eventually 10 minutes). 160 | 161 | #### Notes 162 | 163 | explorer.factom.org shows entries into the system. It is a good method of diagnosing problems and seeing what the system is doing. 164 | 165 | the factom-cli operations mkchain and put both wait 10 seconds between commit and reveal operations. 166 | 167 | Intra-block acknowledgements are not generated and passed back to the local factomd yet. The local node waits for finished blocks before showing results. Wait until the 10 minute has passed between a mkchain or put and when reading the data back. 168 | 169 | 170 | #### If Factom is Crashing 171 | 172 | This version of factomd downloads the blockchain from the server. The server is restarted regularly and the blockchain is reset. Local factomd does not work when the blockchain is reset on the server. The way to fix this is to delete the Factom database files from the /tmp/ directory. Run this code to delete the databases run `~/go/src/github.com/FactomProject/FactomCode/cleandb.sh` 173 | 174 | Backup the factoid_wallet_bolt.db in the .factom directory if you made any new Entry Credit or Factoid addresses. It is a good practice to backup this file after creating every address. 175 | 176 | 177 | 178 | 179 | 180 | -------------------------------------------------------------------------------- /developerSandboxSetup.md: -------------------------------------------------------------------------------- 1 | Factom Developer Sandbox Setup Guide 2 | ========== 3 | 4 | This is the Factom equivalent of Testnet3 in bitcoin, but doesn't require finding testnet coins. 5 | 6 | Use Factoids with private key `Fs3E9gV6DXsYzf7Fqx1fVBQPQXV695eP3k5XbmHEZVRLkMdD9qCK` 7 | 8 | 9 | There are three options for running a sandbox. 10 | 11 | 12 | 1. Run only a local sandbox server 13 | * Minimal setup 14 | * good for quickly testing APIs 15 | * Better feedback metrics 16 | 17 | 18 | 2. Run a test server and client 19 | * Much closer to production experience 20 | * Needed if multiple clients are used 21 | * Factom setup needed on two different computers 22 | 23 | 3. Run a Dockerized Factom sandbox 24 | * Zero setup 25 | * Good if you are already familiar with Docker 26 | * Almost the same as running a local sandbox server 27 | 28 | ### Setup a Local Sandbox Factom Server 29 | 30 | #### Install Factom Binaries 31 | 32 | Download the appropriate Factom binary package from factom.org 33 | 34 | Directions for installing Factom Federation may be found [here](https://docs.factom.com/#install-factom-federation-ff) 35 | 36 | Installers for for Windows, Mac, and Linux are hosted at https://github.com/FactomProject/distribution 37 | 38 | Install the binaries like you would any other for your OS. The install directions walk you through various operating systems. Do not run them yet, as you will be making your own fresh blockchain instead of using the public one. If you did run factomd before setup, follow the directions below for resetting the blockchain. 39 | 40 | Three programs are installed: factomd, factom-walletd, and factom-cli. You may also wish to install the GUI [Enterprise Wallet](https://docs.factom.com/#enterprise-wallet). 41 | 42 | * Factomd is the main program. It manages the blockchain, connects to the public network, and enforces the network rules. 43 | * factom-walletd is an application for holding private keys. It builds Factoid transactions and handles crypto related operations to add user data into Factom. 44 | * Factom-cli is a program for users to interface with factomd and factom-walletd. It may be used to create Chains, Entries, and Factoid transactions. 45 | 46 | #### Configure Factomd for Sandbox use 47 | 48 | Create a folder in your user home folder. The folder should be called `.factom`. If factomd has been run on your computer before this folder will already exist and may already contain part of the factom blockchain. 49 | 50 | In a terminal Linux and Mac: `mkdir -p ~/.factom/m2`or Windows: `mkdir %HOMEDRIVE%%HOMEPATH%\.factom\m2` 51 | 52 | Save the configuration file [factomd.conf](https://raw.githubusercontent.com/FactomProject/factomd/master/factomd.conf) to your `.factom/m2` directory. 53 | 54 | * Open `factomd.conf` 55 | * Change the line `Network` from `MAIN` to `LOCAL` 56 | * This will cause factomd to run on its own local network rather than the factom main network. 57 | * Change the line `NodeMode` from `FULL` to `SERVER` 58 | * This will make factomd create a blockchain 59 | * Optionally adjust `DirectoryBlockInSeconds`. 600 gives 10 minute blocks, which is more realistic 60 | * The default is for 6 second blocks which is easier to develop with, but may cuase some strange behavior and errors. 61 | 62 | For easier debugging, change the `logLevel` to `debug`. This exports pointers to data which is added into factom to the ~/.factom/data/export/ directory. Adding new entries will add new files to the directory with the specified ChainID. 63 | 64 | #### Run Factomd in sandbox mode 65 | 66 | In a terminal window, run `factomd -network=CUSTOM -customnet="mycustomnet" -exclusive=true`. (Windows users have a desktop shortcut) 67 | 68 | In a new terminal window, run `factom-walletd`. (Windows users have a desktop shortcut) 69 | 70 | In a new terminal window, run `factom-cli properties` (Windows users may have to browse to the install location of factom-cli, or it might be in the path) 71 | 72 | ``` 73 | % factom-cli properties 74 | CLI Version: 0.2.0.2 75 | Factomd Version: 0.4.0.2 76 | Factomd API Version: 2.0 77 | Wallet Version: 0.2.0.2 78 | Wallet API Version: 2.0 79 | ``` 80 | 81 | Once factomd is running you can use an internet browser and navigate to [](http://localhost:8090) to view the factomd Control Panel. 82 | 83 | #### Charge an Entry Credit key 84 | 85 | We use a Factoid key which has a balance of 40000 in the genesis block. It has since been depleted on mainnet, but can be used on sandbox systems. 86 | The private key is: `Fs3E9gV6DXsYzf7Fqx1fVBQPQXV695eP3k5XbmHEZVRLkMdD9qCK` 87 | The public key is: `FA2jK2HcLnRdS94dEcU27rF3meoJfpUcZPSinpb7AwQvPRY6RL1Q` 88 | 89 | ``` 90 | % factom-cli importaddress Fs3E9gV6DXsYzf7Fqx1fVBQPQXV695eP3k5XbmHEZVRLkMdD9qCK 91 | FA2jK2HcLnRdS94dEcU27rF3meoJfpUcZPSinpb7AwQvPRY6RL1Q 92 | ``` 93 | 94 | We will generate a new Entry Credit address. 95 | 96 | ``` 97 | % factom-cli newecaddress 98 | EC2kMjtY5jB5sLLzFtfzaA2rU92fqdNeiWNWjvtKmYQoG7fXFTmG 99 | ``` 100 | 101 | ``` 102 | % factom-cli listaddresses 103 | FA2jK2HcLnRdS94dEcU27rF3meoJfpUcZPSinpb7AwQvPRY6RL1Q 40000 104 | EC2kMjtY5jB5sLLzFtfzaA2rU92fqdNeiWNWjvtKmYQoG7fXFTmG 0 105 | 106 | % fa1=FA2jK2HcLnRdS94dEcU27rF3meoJfpUcZPSinpb7AwQvPRY6RL1Q 107 | % ec1=EC2kMjtY5jB5sLLzFtfzaA2rU92fqdNeiWNWjvtKmYQoG7fXFTmG 108 | ``` 109 | 110 | Then purchase Entry Credits using our Factoid address. 111 | 112 | ``` 113 | % factom-cli buyec $fa1 $ec1 10000 114 | TxID: ce18d00316508dd44a02d20bb3d9ee15f909bd9a099dd1b9b4576e2688f8f42a 115 | Status: TransactionACK 116 | % factom-cli balance $ec1 117 | 10000 118 | ``` 119 | 120 | #### Make Entries into Factom 121 | 122 | All Entries in Factom need to be in a Chain. First, make a Chain for your entries to live in. 123 | 124 | ``` 125 | % echo "This is the payload of the first Entry in my chain" | factom-cli addchain -n thisIsAChainName -n moreChainNameHere $ec1 126 | CommitTxID: e8950db51f6c15e10fdc6cc928cd40a5b9438b775708bdf4cabb266b0c1ffb5a 127 | ChainID: 23985c922e9cdd5ec09c7f52a7c715bc9e26295778ead5d54e30a0a6215783c8 128 | Entryhash: e8a838f95c1fe873e0c7faae401cef31d6273644c32aa2324946613a594c0c77 129 | ``` 130 | 131 | It makes the chain `23985c922e9cdd5ec09c7f52a7c715bc9e26295778ead5d54e30a0a6215783c8` 132 | 133 | Check the status of the Chain. 134 | 135 | ``` 136 | % factom-cli get chainhead 23985c922e9cdd5ec09c7f52a7c715bc9e26295778ead5d54e30a0a6215783c8 137 | EBlock: c18bf1688d20b145d53f6e995ff8dfe91c2d73a422a625eb68c712ccc7988cd2 138 | BlockSequenceNumber: 0 139 | ChainID: 23985c922e9cdd5ec09c7f52a7c715bc9e26295778ead5d54e30a0a6215783c8 140 | PrevKeyMR: 0000000000000000000000000000000000000000000000000000000000000000 141 | Timestamp: 1489718700 142 | DBHeight: 130 143 | EBEntry { 144 | Timestamp 1489718940 145 | EntryHash e8a838f95c1fe873e0c7faae401cef31d6273644c32aa2324946613a594c0c77 146 | } 147 | ``` 148 | 149 | You can now place Entries into this Chain. 150 | 151 | ``` 152 | % echo "This is the payload of an Entry" | factom-cli addentry -e newextid -e anotherextid -c 23985c922e9cdd5ec09c7f52a7c715bc9e26295778ead5d54e30a0a6215783c8 $ec1 153 | CommitTxID: 0e6513528212b476297355207d619807f1b6bf2379f707c84cb0066ad2d4a920 154 | ChainID: 23985c922e9cdd5ec09c7f52a7c715bc9e26295778ead5d54e30a0a6215783c8 155 | Entryhash: 0a9fee6636ab71466a8716ba3715cc01582174d8ffab9e830e9f4ce4f1ea8890 156 | ``` 157 | 158 | Query your entries in factom. 159 | 160 | ``` 161 | % factom-cli get entry 0a9fee6636ab71466a8716ba3715cc01582174d8ffab9e830e9f4ce4f1ea8890 162 | EntryHash: 0a9fee6636ab71466a8716ba3715cc01582174d8ffab9e830e9f4ce4f1ea8890 163 | ChainID: 23985c922e9cdd5ec09c7f52a7c715bc9e26295778ead5d54e30a0a6215783c8 164 | ExtID: newextid 165 | ExtID: anotherextid 166 | Content: 167 | "This is the payload of an Entry" 168 | 169 | ``` 170 | 171 | And get information about the chain and its entries 172 | 173 | ``` 174 | % factom-cli get firstentry 23985c922e9cdd5ec09c7f52a7c715bc9e26295778ead5d54e30a0a6215783c8 175 | EntryHash: e8a838f95c1fe873e0c7faae401cef31d6273644c32aa2324946613a594c0c77 176 | ChainID: 23985c922e9cdd5ec09c7f52a7c715bc9e26295778ead5d54e30a0a6215783c8 177 | ExtID: thisIsAChainName 178 | ExtID: moreChainNameHere 179 | Content: 180 | "This is the payload of the first Entry in my chain" 181 | 182 | 183 | % factom-cli get allentries 23985c922e9cdd5ec09c7f52a7c715bc9e26295778ead5d54e30a0a6215783c8 184 | Entry [0] { 185 | EntryHash: e8a838f95c1fe873e0c7faae401cef31d6273644c32aa2324946613a594c0c77 186 | ChainID: 23985c922e9cdd5ec09c7f52a7c715bc9e26295778ead5d54e30a0a6215783c8 187 | ExtID: thisIsAChainName 188 | ExtID: moreChainNameHere 189 | Content: 190 | "This is the payload of the first Entry in my chain" 191 | 192 | } 193 | Entry [1] { 194 | EntryHash: 0a9fee6636ab71466a8716ba3715cc01582174d8ffab9e830e9f4ce4f1ea8890 195 | ChainID: 23985c922e9cdd5ec09c7f52a7c715bc9e26295778ead5d54e30a0a6215783c8 196 | ExtID: newextid 197 | ExtID: anotherextid 198 | Content: 199 | "This is the payload of an Entry" 200 | 201 | } 202 | ``` 203 | 204 | #### Make Entries into Factom Programmatically 205 | 206 | Now that your EC key has been charged, you no longer need the wallet. You can run API calls against factomd, as the crypto is simple enough to do when we get to submitting Entries. 207 | [Here](https://github.com/FactomProject/Testing/tree/master/examples/) are some examples for using Factom. 208 | 209 | [This](https://github.com/FactomProject/Testing/blob/master/examples/python/writeFactomEntryAPI.py) is a good example python script which commits and reveals Entries to Factom. 210 | 211 | If you have python installed, first install the needed libraries. On Ubuntu this is enough: 212 | ``` 213 | sudo apt-get install python-pip 214 | sudo apt-get install python-dev 215 | sudo pip install ed25519 216 | sudo pip install base58 217 | ``` 218 | Then run the script on the command line with `python writeFactomEntryAPI.py` 219 | 220 | Edit some of the values at the top of the python script to make different Entries. Specifically, modify entryContent and externalIDs. (Note the same Entry can be made multiple times) 221 | 222 | #### Evaluating Success 223 | 224 | You can get some diagnostic info from the control panel (which incidentally doesn't control anything). Browse to http://localhost:8090 225 | 226 | ![controlpanel](/images/controlpanel.png) 227 | 228 | #### Setup a Factom Remote Server 229 | 230 | On a remote machine, setup a Factom server. Both the client and server must be run of different machines. 231 | Use the same directions as [Install Factom Binaries](https://github.com/FactomProject/FactomDocs/blob/master/developerSandboxSetup.md#setup-a-local-sandbox-factom-server) and [Configure Factomd for Sandbox use](https://github.com/FactomProject/FactomDocs/blob/master/developerSandboxSetup.md#configure-factomd-for-sandbox-use). Run factomd. Make sure that port 8110 is open on the server. Only factomd needs to be running on the remote server. 232 | 233 | #### Setup Client to use Sandbox Server 234 | 235 | Create a folder in your user home folder. The folder should be called `.factom/m2`. 236 | 237 | In a terminal Linux and Mac: `mkdir -p ~/.factom/m2`or Windows: `mkdir -p %HOMEDRIVE%%HOMEPATH%\.factom\m2` 238 | 239 | Save the configuration file [factomd.conf](https://raw.githubusercontent.com/FactomProject/factomd/master/factomd.conf) to your `.factom/m2` directory. 240 | 241 | * Open `factomd.conf` 242 | * Change the line `ServerPubKey` from `"0426a802617848d4d16d87830fc521f4d136bb2d0c352850919c2679f189613a"` to `"8cee85c62a9e48039d4ac294da97943c2001be1539809ea5f54721f0c5477a0a"` 243 | * This will make factomd recognize the sandbox public key instead of the official public key. 244 | * Make sure you are using the default NodeMode = FULL for the client node. 245 | 246 | ##### Connect Local Factomd to Sandbox Server 247 | 248 | The local machine should be set as a client in the factomd.conf, which is default. 249 | 250 | run factomd this way, but use the remote factom server's IP address. 251 | ``` 252 | factomd -network=CUSTOM -customnet="mycustomnet" -exclusive=true -peers="serverip:8110" -prefix="notaserver" 253 | ``` 254 | 255 | The rest of the steps with [factom-walletd and factom-cli](https://github.com/FactomProject/FactomDocs/blob/master/developerSandboxSetup.md#run-factomd) should work on the local machine. 256 | 257 | ### Run a Dockerized Factom sandbox 258 | 259 | A community member graciously maintains a docker image for a Factom sandbox. 260 | 261 | Just execute 262 | ``` 263 | docker run -d --name factom-sandbox 31z4/factom-sandbox 264 | ``` 265 | and you are all set. You can now for example use `factom-cli`: 266 | ``` 267 | docker exec -it factom-sandbox factom-cli properties 268 | ``` 269 | See other details [here](https://github.com/31z4/factom-sandbox-docker). 270 | 271 | 272 | ### Resetting the Blockchain 273 | 274 | By default, Factom holds all the blockchain, wallet, etc data in the user's home directory in a folder called ".factom/m2/custom-database". This may be a hidden folder, so make sure to display hidden folders on your OS. 275 | 276 | To reset the blockchain, first close factomd and factom-walletd. Delete all the folders and files in ``.factom/m2/custom-database except`` `factomd.conf` 277 | -------------------------------------------------------------------------------- /examples/tax/ERS_privatekey.txt: -------------------------------------------------------------------------------- 1 | 2 | 3 | -----BEGIN PGP PRIVATE KEY BLOCK----- 4 | Version: GnuPG v1 5 | 6 | lQHYBFTbxAMBBADMUCGZ4InTMw3120g9d81/yWtPSL6AKi8tnVs7AumsjMi1ntRa 7 | 8CKXyMyi9sD5AP4BflZvpx9YyoVWvfoiJA/JVO9eY0tbp3ziTO0cf29wItketj6y 8 | hKZaYFIYvK4m2/XtIFrJN5cLls2YaVkwgKbkoQ4tBIZv9YmJyQq7QSXw+wARAQAB 9 | AAP7Btm0SyghH8mM1KsaRgeP6hKPpwl/iFchwChldoTJURPUddvSL0YqDIsiFWAO 10 | +1UFrz/prQQlbqSntGvLeqBZPm24fxSVBiFsO4M0k5e5VD8LpAcTts4OJbQ+1XOt 11 | SFXLZ1mrhnmcgy+Y4P64SvyKYzJqyWtvxQBuMhpjlqyzLoECAN3Xsuip+Du7VvVb 12 | wliG3Rp3cVYNdHzpEd/e+HbDjqr34Bd7UagXUA7U8sIwEwPJAvsLcsoyRym3y61V 13 | PNblV3sCAOvFeZtoNoJY89n83jyS8uwFIJwPIkpy4s02rWufbGj4OM4Nz7k/Ns9L 14 | lfCJRRrYVTcaTJzDheCXhs4l7HZ51IEB/1o77voAXvzvH6H+q7T1B9dapP2O0Csq 15 | vZSYZc3NpV4slWSwVBp3uL2puNIFVkiqiV7AAwyoxyQyBNtAIaaSiR+fHLQdRXhh 16 | bXBsZSBSZXZlbnVlIFNlcnZpY2UgKEVSUymIvgQTAQIAKAUCVNvEAwIbAwUJAasm 17 | AAYLCQgHAwIGFQgCCQoLBBYCAwECHgECF4AACgkQKA2KkleSKLleegQAkBdiKumV 18 | iMAV9oQArIBHCF7600otTQAvz4L1SaRiJ/7vMTW8ogbfeHYrgYpFQfR7FYjfPYFg 19 | pyqja0MVYIXb6MSHuHVygbXK3sT7bLTkxgKH8saDQP1hXPK26bXeUo4PuFmbMMNb 20 | fk8MbDNHraXMtnyz9rEiuiO4J3eEu1Z5a5SdAdgEVNvEAwEEAKxMMLoEXFSXjKXI 21 | irlEL9q2HefvT/6llLvlPgrnUhbi/e+dVJrl7332vDdpYW37mAhlG45HaL31EgUc 22 | lWYO+cDh4824F6FVj1da0ESnvrI14IeU4hN0QRNcVBAA5sf0/NOj0ils+jKeLGel 23 | 7wBetgVZIJ1w6qBMcj0BH2p8TlHhABEBAAEAA/kBKAUUXS7LczWX7+fHxNviBrfe 24 | VHOqfKz/XSip77x+zSjcIKeuicguMGePTaSVlYst1JPh7rvBY/F/hEjCZcD/q2Zs 25 | BangczgSW209blhbYU8APkJ9fCl2Uzd+EsELjGHoCT95ndQyTeQgFOJkXW81VfTW 26 | cCpTTDY5mo+uzNAGswIAxDEhbxGGLtmnCYcRAszp/Wn7nGDAF5+RpBCN62MdrTuC 27 | zuF66vGb19mx4++o7umVRfci3sBhgn9oExEeQhQgWwIA4NJXpVX5JKjvwroaX4Ol 28 | TIQAITWEpkociO8KbbimDd5eOdICb4RjgRn6JEfB21YHmZvpKBSiZJBIlsb7U6Wr 29 | cwIAhiiryk9kRgODXZHhA72gy6/iSRQxmL/wkZmL1L+ooGsFA6cDQOiUiL+1XqNt 30 | xwmslCnLF/w2ea0obFTSf5bV0aAgiKUEGAECAA8FAlTbxAMCGwwFCQGrJgAACgkQ 31 | KA2KkleSKLke0QP+Nm6b4mMldb2RWVgd2vP+zwFnnuFt1W2/g0glqLSRWVHf1+KO 32 | tcMZSltz5Wj+L0JuG57gxKfcYZjwvGdKs5Ocj5maBoVYbavho3MMmFclhPTnbm0b 33 | DJHAcvV8c3ZdtvTu/8untZp+R7Py4YIeoIYiDJjjKcQyAIKXbeFchDBAX9A= 34 | =JzWM 35 | -----END PGP PRIVATE KEY BLOCK----- 36 | 37 | 38 | 39 | -------------------------------------------------------------------------------- /examples/tax/ERS_publickey.txt: -------------------------------------------------------------------------------- 1 | 2 | 3 | -----BEGIN PGP PUBLIC KEY BLOCK----- 4 | Version: GnuPG v1 5 | 6 | mI0EVNvEAwEEAMxQIZngidMzDfXbSD13zX/Ja09IvoAqLy2dWzsC6ayMyLWe1Frw 7 | IpfIzKL2wPkA/gF+Vm+nH1jKhVa9+iIkD8lU715jS1unfOJM7Rx/b3Ai2R62PrKE 8 | plpgUhi8ribb9e0gWsk3lwuWzZhpWTCApuShDi0Ehm/1iYnJCrtBJfD7ABEBAAG0 9 | HUV4YW1wbGUgUmV2ZW51ZSBTZXJ2aWNlIChFUlMpiL4EEwECACgFAlTbxAMCGwMF 10 | CQGrJgAGCwkIBwMCBhUIAgkKCwQWAgMBAh4BAheAAAoJECgNipJXkii5XnoEAJAX 11 | YirplYjAFfaEAKyARwhe+tNKLU0AL8+C9UmkYif+7zE1vKIG33h2K4GKRUH0exWI 12 | 3z2BYKcqo2tDFWCF2+jEh7h1coG1yt7E+2y05MYCh/LGg0D9YVzytum13lKOD7hZ 13 | mzDDW35PDGwzR62lzLZ8s/axIrojuCd3hLtWeWuUuI0EVNvEAwEEAKxMMLoEXFSX 14 | jKXIirlEL9q2HefvT/6llLvlPgrnUhbi/e+dVJrl7332vDdpYW37mAhlG45HaL31 15 | EgUclWYO+cDh4824F6FVj1da0ESnvrI14IeU4hN0QRNcVBAA5sf0/NOj0ils+jKe 16 | LGel7wBetgVZIJ1w6qBMcj0BH2p8TlHhABEBAAGIpQQYAQIADwUCVNvEAwIbDAUJ 17 | AasmAAAKCRAoDYqSV5IouR7RA/42bpviYyV1vZFZWB3a8/7PAWee4W3Vbb+DSCWo 18 | tJFZUd/X4o61wxlKW3PlaP4vQm4bnuDEp9xhmPC8Z0qzk5yPmZoGhVhtq+GjcwyY 19 | VyWE9OdubRsMkcBy9Xxzdl229O7/y6e1mn5Hs/Lhgh6ghiIMmOMpxDIAgpdt4VyE 20 | MEBf0A== 21 | =J4P0 22 | -----END PGP PUBLIC KEY BLOCK----- 23 | 24 | -------------------------------------------------------------------------------- /examples/tax/Encrypted_Biden_Tax_Return.txt: -------------------------------------------------------------------------------- 1 | -----BEGIN PGP MESSAGE----- 2 | Version: GnuPG v1 3 | 4 | hIwD6PpMMooTjhsBA/9VzRF63BryoUkZfeEyUlf+yymZLJZKnCsF/pMGHvVwsf0f 5 | 1CA1GXc80zsSdB+7/75cn5koG/6XchIX4TXY0UKUuUyWeiK2v6pAVJDwzQYWFv8L 6 | DksvWkLBYzPfckdD7Q8Rrw5ufrx63OjJb9pzt4bvlofqmUTIoQuqAgXjIoCcQNLq 7 | AZhvU3EeaCYmXE4wOnObihl0toZQD7kSC8GgRa0JCTYzbLnAp+ee8nXSPale6d0o 8 | adWqh471biVnnUwg8n3FU1x39UyeL7ACpCkwYtmz0nexVD4Ey0F11LZdnPJ1SuS8 9 | jlqfZemHWUD/hxyrTNlKdaSvAZpvM0py87G1SvQEBPPXM8pKUksRF6+lHYuNjjfJ 10 | 8qq+7GS/7mY2LEWVf1YI1a3RpdnOKd+nbyxlJXI2xFt3DKAbwnbZwIl8aGglJNQt 11 | +7YIDX6ZinfmnEHO+zTiivSghgZsZFZUPpMK4ZBkF1bCKDID4oHt/nFyWkNf1I9w 12 | 9Wa4b16jGLdh78G8SQg+L8POYIOSGu2sxpOl+IjLJoqwehYs/2rS+CnTADebjBbk 13 | a4EsafWtuiI8rdADZsdOMmG/0o6fWbKI/qQ7C0nk5EZrB0D/ftY9IYimUasXIerj 14 | jTP25TChXUbKPo/QqSAtK37P6wa3N+/fsmAw6PCf9cpBRM+vbeiYgmZ2TM6FTB3q 15 | wWmY3XEvMVFrA397zp4D8gbtyVwOUotHWjaxh/ZcbRB0j0HPqlloxuz6vgKNtr+d 16 | wb52/POHqPr9DA/WK0poQ3osUlyx2UgSWKRB3rvGxVrNSlkJ+Z2I+0rOjehbMImP 17 | hHrP5DFbC2uznnY9lrp39/ykESYwGv1PAtg188SVeyFTfin8IgZ6Y5BfNXtMYAkC 18 | YjTBTrQZLj+uWd+EAiHkMbyaRRIGZRIAPCEhrC1bX7vZPMpl3ZTalwhL5H2QAmL1 19 | pgxvpDZJgqBXVm89N3OEIM7BUqK4rnQQFNNUEJQavyfUh2NnTJ34EHPbV3GabSXr 20 | UZYo0whFpkjj6eCPvkRps5YxbrTa73PaATcwNeK9NyS5jJpgPXt1MPyJ9XtlERkl 21 | GwpzeHmUWapdytRVlfsCuXBbTycNLOsCOKrga/Ma0H9UJsX8vfYearHLLV8onYoP 22 | 4oClNNSCIs0LjwxDJq1rZIksKB8zuIVGXh+xyjxj67ZZce5tFsAHU2wyjPT60bH1 23 | bwDIfKKKhbm0kp0iQPm+6XUwEfynJa3+sI2uAN3yBPPh8gbLq+OOHVer23uwVj6c 24 | jftmPDMKy9kflJRkg3Ebjz5LmyVEa09Nky/GFlcZQg3+jIuKzJ9nDB2tac/1NIT2 25 | x3wfpw8viJfo986eFlu26RuZfcB5tu8vFir4uSF/t9MU9lWppDfV3iVvY3+YFpzV 26 | S8bz+cuIBpSsgbkxAlLQC6BDV/xt0FGwiNc6z7PUVNwU7qtqlqrka3szQOzkgkwV 27 | +bGBhK/gEPjrVeKS7j1OuZgZu8XKi6Er+ljD9BS0JUz91Gz7oOukCOU9hMpGTqpq 28 | ohBf69X61hVqOhPu3hvxBunhYc8l50g9sJe09RpzLdQoKqp1l0S9Fkiq0DRmyoq6 29 | gEHRgCNrcHXt6JBLkzhX0YtbajVeHLeVpgS5ZFwet7s92H1O4Y298Ld7ZGK99qwu 30 | 9GNzwuWSQHTQH46kVKE3aq9Yjz+XbWvsuE/rx3xx7h+IUdcArGsq5U0QnDAMDG40 31 | VNKFNWgwtc1JHi6NP37Wblk3cUDvwCkDB2Ordw/WN8pmNKLTPKbGm6HGOsojKKek 32 | JNXW8JAqfSu26ALigB3stqx4qp/9zWl4Y8LjmdKLsWjGk16F4aEaHOLW0aD6hwkK 33 | Vx7SHPaPfgldb7duxtUeLHx2ksLckBrc/TmIih4fi2O3vAfOh3zId41CHjJslshz 34 | KaZcsz6elrFfrSnItwWKBcRbztSykKaX6nmMbDtQ0XTN++wleBbaz0NoqsZC1E+d 35 | cArHayweXcXs3iNyGlDDbsJW+yx8Ob8B+1+ekfW7yv66M2OGusTXdEwZJFIL1iyf 36 | AGkcZlSRJgV79fQ+brRH6e2xSi/roJBio7cnk/h7AG/a/FR2pA3xwthE9aqW9S0r 37 | u7fVFCjv+E/cWz0DUMHKTKNeE4LqN30zTvIpdbiFGTwKrxw74wcEsmEQ/8yNNoiY 38 | 4rewl+/HF6XB6loPomFb6FQjNX8DLrgmab9HJ+9uoVLAnwXOnh/ipvmFkbhdpPg6 39 | kMEjhF0jWVv6FWwXuz6L6mWgwIh2d1HuishbZRTiiSm33699iCA/InnSRqMtYdtt 40 | 8fppwXugmXmIKJ466m593SZ/DBWCGmHP2TexMUy0ubOhGvHumI90RkJucaWDgPJK 41 | 0ohJhUGJCojLXtkQiWEJIsX+hCCsupP0dScC18w7n0HmiBByNc2vlXN61XJRbS7F 42 | FT98kWHtw3fPA7V5u4w5tq4H/hzw9GG3TfyUZoesnui3Djzr9NOCVkvfVeAfVNrp 43 | xKGxB/oG5Y4sAL37JhYLDYQCTkVUkayZfaif8/jrJf5abDZXjrWuku8TraTekjJW 44 | VDuQGqBKwXD55F2XL40rb36UY8QNN9MMkZPCmnsmqpbtcUU96w3Bk28VAGSMIHB6 45 | Ejo4w/WzjspPx4IZbkWUdYLtYGFzXIaHx0uyCLjcihMGOrSmM4Mx0+7J4O9YazZ6 46 | ABz3gIscuRD3KuDNEbf2N1UOKpOv+p6W2jmsPxJaI6AUke/Z1O2Te+ld6c7/Grvg 47 | 0BX/Dp09rBVHchHMs3jSpkOdQz3z4XW809yutxkuE9HsMGZWg/MKX94ulMsGTzvd 48 | OO3EC9cL5q8ErPXgkHhrpq1ztuZFU27O0y5PyEPmEuqXS2ngDsmWpegJ7v8L4kjW 49 | Tfl00rI8 50 | =0Akv 51 | -----END PGP MESSAGE----- 52 | -------------------------------------------------------------------------------- /examples/tax/Encrypted_Obama_Tax_Return.txt: -------------------------------------------------------------------------------- 1 | -----BEGIN PGP MESSAGE----- 2 | Version: GnuPG v1 3 | 4 | hIwD6PpMMooTjhsBBACR2g4KMg6k7dzTvg/8xJGa62YW1O3eXKPR05aRuZbJvFyW 5 | 70caMU+GgKgfjgzyafJNkc/ZDCbyl0MqZhCfeFOW66cNJ+GrQFwutVvFaZ9aIU2K 6 | x0rUhU/9D6MSDZduVEz0IcnXIwO06BkSkUNVzMPIrRNcKMUvF9S+CiSBicKvwtLr 7 | AVavY1zYy+WDYeK4zEWj9ZwyADJiImBS9s+dAfQatCkkx4h/i+9CWYPn5GxwQpPR 8 | r3WH7C9O/mo++MBxn6mSGXG6xwwB3sKi4PexRC8lU3JHGjtXZ0ygJcllVImv7rCO 9 | 0FnbH1BI+S/IRurXcr7To0JZRR/PyKJqqRJxO/o6kOgtFD31KLir1RXVwmI/ziLz 10 | veoiToYJm2+zSL3Bcwvschmrd+BsAqGIN8DeufI6ryTwEt/9fLURgfqBjNEoAmoT 11 | cSb0pyC6CB0yBLd9wTewpbqefOIqKISgKHM6PZ6enGphhYrILhH3CNb9UxglK2D1 12 | T6EdvT5yx7Skf4QcGP2F13XgvCzB54eZmZZkHr5nLLUfnFtTR35SOqv+RWbaqBqZ 13 | 03a+0eOJyfNvFwwMnf8B/BxmpgCaI76ZrJ64JcvfIDOSc9ieTDjImiKqllaOVw4/ 14 | M7bc8y9v8IOj2Ls6GN9+7QC147z5Nsk9h8GHjMpk7c5QYGXAwqZD5IKKJYf0OqoL 15 | sZvOb10Fk3lQwT0hAMEChYWSvj3JL9Exe3/Ud/4WpvhNeXbn05wJYH/BDjKuBZg7 16 | PLgk/sMCjHSrYvh+jCNM7k2uSRRKYZ39OZPm9KRyfq52aAtYhNdq+Ydc1LHg6IdR 17 | /el2LgH97afUwqwILpdYTeQyoHBWkJVlUpiUGRY7MrQp90AEq3LazTjnOq5qv0Yl 18 | /w9FY6d/7iLf+96nW2b9yp/4LgQayQ156NFZLv7UfoOvTLXUzC3MkKGzIUZKfJ7X 19 | 9Z5c1PMYfWMDRPhqHQ9KKiXYetNUuKPnVWAZwsmOviubkPOXbOeqcjV+2ggPa9ps 20 | KXM+q8X97v0Tr7qPm/Ik0ncQz16q3YwQP7mugCR/yuX6gnctitErbbRUiw/hpLc4 21 | 8TJi9m3I/hZpQuKPyIhkVZDzPGAcWAGJo1l9Xqt5ExtR534FY4pWgqZz9cWGyTt0 22 | RpN4rnJPo/vsjj10hbzh8umJ1BulXZM8bTABNcB3KtFnmocMLCz1UfVFNXTqXX6O 23 | hEbnVFIwZN+l/8GptASw33QcAA3monXMBq9r5ZY8vbtl55NisyvltlulDp3paEgR 24 | 7dM1AGFuXMr20u1eFWwByUFjFlBCD/1Srf2mbMbrNKJUXsigt8s3navnxy8WmDuS 25 | 1LBiZn1cAbh22v8zY0dQVvACt2gnGnK7pmV+7b6OATGnqLmlXy0dlWNNTQ2LqowH 26 | liE+fYKeZzSCDMlEdww9QBwmAwzExdGBfZX7jUfRBju241jQvTslbfcX7ha/V/sn 27 | AuTeWpmMczzqpbkgxrwT8En1LDoSIWju2AcI6/92qYfdGmNJRP0UTEVgjBl6PyVZ 28 | Lna4gd/GRlDi8Oh7cq10YGgVKba6mCpP/LcjHTN8S4WhTAEoyhmL5Hk5dGthxx2N 29 | kNRmcWOqiwSA1MI5Unomv0qancgsEUD39HcgF+lgdJGC/AOPeqSZfqPxu9iaEVTF 30 | mzEb9xzX7DbiBBlX+br7Qx3qJFeWR1lGs0mn9ArKK3L/IblMvvrUmgLnSZQpFKJ4 31 | NlJJ0AxXf8I3ksJMRl5u1ghA0y9qmzX/IACtoy+fcQ2DwJMXc2pFIJKCcgzNGXd/ 32 | Q7bccw6+ertegNAdGqDu2KKkGJQt1sDoIbGUFx/IOwS7iaHA8ZO90hW1jmCrkrYE 33 | XtfXtiuPN0lJBTKq4rJghbsLrEIpkRiua7aLtwGyNyEm0A/aNSIpszpERP8tUm8N 34 | awugqWVDp7eifzhhXMfQT8Mf+t2p08ycPvKYFLcV1v1Nx6Zk44KTooRYlE7mkiGL 35 | 6O/13RYtELvdKANC56uG+OfzD8basKs0KEtmieSQAembR3+/WvNX+JUiSiBZsQae 36 | gx4uVwcDOo4mTtfUMjHVJS4yAT/JR8R2hX1ExzMnLAuKZmLr9nKjttbHwVZ1w4U3 37 | h93r6ldnZ4ePG6a/ejXMPnMYCRo5vMwI9gYulwAb/lNRyD0pazKCKvqyjDRMdjB3 38 | SJW4jHynHRrWoa/21MsXPd5XNoMwgi9gqBQ9jOScqAhvaDdvAXn5RgPHHgZ2VZ78 39 | UFbYxFbxDI2kXi/ci/dRH3vs+xYgL2OgQ/LNQO+a8m4hjl1rIMmsgeViAmxJdZ71 40 | 78VeaNu2XwTyBptBIQXCpKk9HniZbu4jIY+THjBV0PcgQjHeftPVNfnKGnve3APc 41 | IWXZFjj2UtUk4ReAogh6GtYWdLAiWcpUMKjuTcsrb8QQ6ImxBToBUhzWYh50/2r6 42 | IFNyj+RVEhVmCtOxt4WPT+alY3/4qa5sF914DZPk1fUklhNqZ9fS760HrIHA1IIf 43 | Hx563CkNGyiGU41klnXtYwq8VymeB2W/mDmXdi7TOwR1lsNVQxfQkHjJ0cwGo6ue 44 | Na/akzW6SduA9rVVl4oFJCTO/CFBxMhMiF/SBwdIUU7bIMKNecZyh1dvXELXoz/A 45 | /laXHP4sDtteyIeRodAt3w5DTqdKwp1wvrR76u7vsmwbugQPiSytKoDCaLkWIQQ3 46 | lw8bGrh8iJUqn6CxD6sET5RB9vL1ntL0m/XlQ81+sFhy6tnpuGP+JwhodH4PvyBZ 47 | upLNiotEvLKVjMozUKiM6zwac1+cedyl3k/fh8yaUqVL8t5NydjsR1FeFydMSkaw 48 | vRNHX/wWkoyGh17kaVD1TknCPAiC1l5vo07i25IhyeenSTpPZ3BdXAkzR7NRss6r 49 | wrEpwVgJ5wBNeScLkF+LFj3wr5vo9ROBj/kPr9RNoSVB+g9/PV6prYv2Pp9Yjidh 50 | 7iYXHMys+wxzG7f7bRT4O3GXM/3gkACVgYwIGHtuVQoW9QD9VVBKXIisIupv7mmF 51 | OIc= 52 | =rvNQ 53 | -----END PGP MESSAGE----- 54 | -------------------------------------------------------------------------------- /examples/tax/README.md: -------------------------------------------------------------------------------- 1 | ### Factom Tax Document Example 2 | 3 | This example shows how Factom can be used to deliver documents to an organization. The organization in this example is the Example Revenue Service (ERS). The sending of the document is timestamped in the Bitcoin blockchain. The document remains encrypted, so only the recipient can read it. The sending of the document can be proven, even though it cannot be read by 3rd parties. Only the ERS can decrypt the tax returns. 4 | 5 | This example assumes that the ERS takes delivery of documents via Factom and is watching their own Factom chain. 6 | 7 | This example was put together with some freely available open source tools, along with the prototype Factom system. This procedure is awkward, only because it is not yet streamlined for this process. In a production environment, the software would handle minutia automatically. To follow the example, you can use a live boot of any popular linux distribution. This example was done with Xubuntu. 8 | 9 | 10 | 11 | ### Send Documents to ERS 12 | 13 | This is how you can send encrypted documents to the ERS. Some examples are already in Factom, but here is how more can be added. 14 | 15 | 1. Start the linux OS and open a terminal. 16 | 2. Download the file `ERS_publickey.txt` from the github repository to the ~/ (home) directory 17 | 3. Import the ERS public key with the command `gpg --import ~/ERS_publickey.txt` The output should be: 18 | 19 | ``` 20 | gpg: /home/xubuntu/.gnupg/trustdb.gpg: trustdb created 21 | gpg: key 579228B9: public key "Example Revenue Service (ERS)" imported 22 | gpg: Total number processed: 1 23 | gpg: imported: 1 (RSA: 1) 24 | ``` 25 | 26 | 4. Encrypt the document to send. In this example, we are using `Unencrypted_Obama_Tax_Return.txt` from the github repository. Use this command to encrypt it: `gpg -e -a -r "Example Revenue Service (ERS)" -o ~/Encrypted_Obama_Tax_Return.txt ~/Unencrypted_Obama_Tax_Return.txt` The output should be: 27 | ``` 28 | gpg: 8A138E1B: There is no assurance this key belongs to the named user 29 | 30 | pub 1024R/8A138E1B 2015-02-11 Example Revenue Service (ERS) 31 | Primary key fingerprint: 323A 8A02 5793 2F31 C0BF 4C1F 280D 8A92 5792 28B9 32 | Subkey fingerprint: A8BE 8143 D3C9 36BC 084A FB74 E8FA 4C32 8A13 8E1B 33 | 34 | It is NOT certain that the key belongs to the person named 35 | in the user ID. If you *really* know what you are doing, 36 | you may answer the next question with yes. 37 | 38 | Use this key anyway? (y/N) y 39 | ``` 40 | It will create the file `Encrypted_Obama_Tax_Return.txt`, the contents of can be copied and pasted into Factom. 41 | 42 | The file will look like this: 43 | ``` 44 | -----BEGIN PGP MESSAGE----- 45 | Version: GnuPG v1 46 | 47 | hIwD6PpMMooTjhsBBACR2g4KMg6k7dzTvg/8xJGa62YW1O3eXKPR05aRuZbJvFyW 48 | 70caMU+GgKgfjgzyafJNkc/ZDCbyl0MqZhCfeFOW66cNJ+GrQFwutVvFaZ9aIU2K 49 | ... removed for space ... 50 | wrEpwVgJ5wBNeScLkF+LFj3wr5vo9ROBj/kPr9RNoSVB+g9/PV6prYv2Pp9Yjidh 51 | 7iYXHMys+wxzG7f7bRT4O3GXM/3gkACVgYwIGHtuVQoW9QD9VVBKXIisIupv7mmF 52 | OIc= 53 | =rvNQ 54 | -----END PGP MESSAGE----- 55 | ``` 56 | 57 | 5. Post the document to Factom. 58 | 1. Browse to http://demo.factom.org:8087/ in a web browser 59 | 2. Click the down arrow next to Entries 60 | 3. Select the Chain `13915515269537837/ERS/2015` 61 | 4. In the Data field, paste the text from the `Encrypted_Obama_Tax_Return.txt` file 62 | 5. Click submit 63 | 6. Wait 1-10 minutes for the Factom Directory Block to be created 64 | 7. Wait several minutes longer for the Directory Block to be timestamped in the Bitcoin blockchain 65 | 66 | 6. Check that the document was included. 67 | 68 | In the Chains page, click on the Chain `13915515269537837/ERS/2015` 69 | In each block, there is a list of Entries. One of the Entries should be the one you created. 70 | 71 | When the ERS want to see if any returns have been sent in, they will open their chain. They will then download each Entry and decrypt each one. 72 | 73 | 74 | 75 | ### How the ERS Reads the Tax Returns 76 | 77 | The ERS would follow a similar procedure for reading the tax returns. Since they are the only ones with the private key, they are the only ones who can read the returns. 78 | 79 | 1. Start the linux OS and open a terminal. 80 | 2. Download the file `ERS_privatekey.txt` from the github repository to the ~/ (home) directory 81 | 3. Import the ERS public key with the command `gpg --allow-secret-key-import --import ~/ERS_privatekey.txt` 82 | 4. Open a web browser and go to http://demo.factom.org:8087/ 83 | 5. Browse to the Chain `13915515269537837/ERS/2015` 84 | 6. Find Entries which contain a message that starts with `-----BEGIN PGP MESSAGE-----` 85 | 7. Copy the text between BEGIN and END, including the BEGIN and END lines. 86 | 8. Paste the text into a text file and save it as `Encrypted_Tax_Return.txt` in the ~/ (home) directory 87 | 9. Run the command `gpg -d -o Unencrypted_Tax_Return.txt Encrypted_Tax_Return.txt`. The output should be: 88 | ``` 89 | gpg: encrypted with 1024-bit RSA key, ID 8A138E1B, created 2015-02-11 90 | "Example Revenue Service (ERS)" 91 | ``` 92 | 10. The file `~/Unencrypted_Tax_Return.txt` will contain the tax return only visible to the ERS 93 | 94 | 95 | ### ERS Receipts 96 | 97 | Since there is still a some question that the ERS got your return, or that something might have gotten jumbled during transit, a receipt would be nice. 98 | 99 | The public key that the ERS has issued can also be used to sign receipts, so that shortly after sending a tax return in, the submitter can be sure that the document was received. 100 | 101 | When the ERS scans and can correctly decrypt the message, they can sign an acknowledgement. The receipts are posted in 13915515269537837/ERS/2015/Receipts. 102 | 103 | ###### The ERS Creates Receipts 104 | 105 | The ERS would find a new tax return in Factom and save the Entry Hash. This is unique to the data that was submitted. In the Obama example, the Entry Hash is `ad8d6e1ef4cc10d6478b2d9eb01a50f7e4b62a207865769702b1a96f4784c21b` 106 | The ERS would run this command to create the receipt. 107 | `echo ad8d6e1ef4cc10d6478b2d9eb01a50f7e4b62a207865769702b1a96f4784c21b | gpg --clearsign` which would output: 108 | ``` 109 | -----BEGIN PGP SIGNED MESSAGE----- 110 | Hash: SHA1 111 | 112 | ad8d6e1ef4cc10d6478b2d9eb01a50f7e4b62a207865769702b1a96f4784c21b 113 | -----BEGIN PGP SIGNATURE----- 114 | Version: GnuPG v1 115 | 116 | iJwEAQECAAYFAlTdLiAACgkQKA2KkleSKLl1bgQAjZQphX45OV74vpssCm085aEn 117 | bSPYYR6EO2mfxsMXIZz1nRx6cPXCESpFkmuSiBsXpY9ipE7jsw0DCAYmBshmaqU/ 118 | 90xV/3f6v8eH/mgrJUZpqQ3dwWliTIfHetV+N1ANeCkkKm0pwswuoS8qenVb1R9P 119 | pEIhDLijjZnuYqeGrGs= 120 | =g/CF 121 | -----END PGP SIGNATURE----- 122 | ``` 123 | 124 | The ERS could then post this in Factom. 125 | 126 | 127 | ###### The Submitter Validates Receipts 128 | 129 | The submitter would know their Entry Hash, since they posted it themselves. They would review the 13915515269537837/ERS/2015/Receipts chain for an Entry that signs their Entry Hash. 130 | 131 | Once they get message above, they would verify that it was actually signed by the ERS, and not a prankster. 132 | 133 | First, they would save the data to a file. In this example we will use `Receipt.txt`. 134 | 135 | They would then run this command: `gpg --verify Receipt.txt` which will give the output: 136 | ``` 137 | gpg: Signature made Thu 12 Feb 2015 04:50:08 PM CST using RSA key ID 579228B9 138 | gpg: Good signature from "Example Revenue Service (ERS)" 139 | gpg: WARNING: This key is not certified with a trusted signature! 140 | gpg: There is no indication that the signature belongs to the owner. 141 | Primary key fingerprint: 323A 8A02 5793 2F31 C0BF 4C1F 280D 8A92 5792 28B9 142 | ``` 143 | 144 | This shows that the ERS has seen your Entry. If the convention is that they only sign it if they can read it, then you can be assured their computer received it and can decrypt it. This would be a high tech equivalent to registered mail. 145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 | -------------------------------------------------------------------------------- /examples/tax/Unencrypted_Biden_Tax_Return.txt: -------------------------------------------------------------------------------- 1 | 1040 2 | U.S. Individual Income Tax Return(99) 3 | 2013 4 | OMB No 1545-0074 5 | IRS Use Only - Do not write or staple in this space. 6 | For the year Jan. 1-Dec. 31, 2013, or other tax year beginning , 2013, ending 20 7 | See separate instructions. 8 | Your first name and initial 9 | JOSEPH R. 10 | Last name 11 | BIDEN JR. 12 | Your social security number 13 | If a joint return, spouse's first name and initial 14 | JILL T. 15 | Last name 16 | BIDEN 17 | Spouse's social security number 18 | Home address (number and street). If you have a P.O. box, see instructions. 19 | Apt no. 20 | A Make sure the SSN(s) above 21 | and on line 6c are correct 22 | City, town or post office, state, and ZIP code. If you have a foreign address, also complete spaces below. 23 | WILMINGTON, DE 24 | Presidential Election Campaign 25 | Check here if you, or your spouse 26 | if filing jointly, want $3 to go to 27 | this fund. Checking a box below 28 | will not change your tax or refund. 29 | X You 30 | X Spouse 31 | Foreign country name 32 | Foreign province/state/county 33 | Foreign postal code 34 | 1 Single 35 | 2 X Married filing jointly (even if only one had income) 36 | 3 Married filing separately. Enter spouse's SSN above and full name here. 37 | 4 Head of household (with qualifying person). If the qualifying person is a child but not your dependent, enter this child's name here. 38 | 5 Qualifying widow(er) with dependent child 39 | 6a X Yourself. If someone can claim you as a dependent, do not check box 6a 40 | b X Spouse 41 | If more than four 42 | dependents, see 43 | instructions and 44 | check here 45 | Dependents: 46 | (1) First name Last name 47 | (2) Dependent's social security number 48 | (3) Dependent's relationship to you 49 | (4) if child under age 17 wualifying for child tax credit 50 | Boxes checked 51 | on 6a and 6b 52 | 2 53 | No. of children 54 | on 6c who: 55 | lived with you 56 | d did not live with 57 | you due to divorce 58 | or separation 59 | (see instructions) 60 | 61 | 62 | Dependents on 6c 63 | not entered above 64 | 65 | 66 | Add numbers 67 | on line above 68 | d Total number of exemptions claimed 69 | 2 70 | Income 71 | 7 Wages, salaries, tips, etc. Attach Form(s) W-2 72 | 7 73 | 306,386 . 74 | 8a Taxable interest Attach Schedule B if required 75 | 8a 76 | 168 77 | b Tax-exempt interest Do not include on line 8a 78 | Attach Form(s) 79 | W-2 here. Also 80 | 9a Ordinary dividends. Attach Schedule B if required 81 | attach Forms 82 | b Qualified dividends 83 | W-2G and 84 | 10 Taxable refunds, credits, or offsets of state and local income taxes 85 | STMT 3 86 | STMT 5 87 | 0 . 88 | 1099-R if tax 89 | was withheld. 90 | 11 91 | Alimony received 92 | 12 Business income or (loss). Attach Schedule C or C-EZ 93 | 24,396. 94 | 13 Capital gain or (loss). Attach Schedule D if required. If not required, check here 95 | 13 96 | 14 Other gains or (losses). Attach Form 4797 97 | 15a IRA distributions 98 | 15a 99 | b Taxable amount 100 | 16a Pensions and annuities 101 | 16a 102 | b Taxable amount 103 | 16B 32,792 104 | 17 Rental real estate, royalties, partnerships, S corporations, trusts, etc. Attach Schedule E 105 | 17 19,022 106 | 18 Farm income or (loss). Attach Schedule F 107 | 19 Unemployment compensation 108 | 20a Social security benefits 109 | 20a 30,522 110 | b Taxable amount 111 | 20b 112 | 25,969 113 | 21 114 | Other income. List type and amount 115 | 22 Combine the amounts in the far right column for lines 7 through 21. This is your total income 116 | 22 117 | 408,733 118 | 23 Educator expenses 119 | 23 120 | 24 Certain business expenses of reservists, performing artists, and fee-basis government 121 | 24 officials. Attach Form 2106 or 2106-EZ 122 | 25 Health savings account deduction. Attach Form 8889 123 | 26 Moving expenses. Attach Form 3903 124 | 27 Deductible part of self-emplayment tax 125 | 1,724 126 | 28 Self-employed SEP, SIMPLE, and qualified plans 127 | 29 Self-employed health insurance deduction 128 | 30 Penalty on early withdrawal of savings 129 | 31a Alimony paid b Recipient's SSN 130 | 32 IRA deduction 131 | 33 Student loan interest deduction 132 | 34 Tuition and fees. Attach Form 8917 133 | 35 Domestic production activities deduction. Attach Form 8903 134 | 36 Add lines 23 through 35 135 | 36 136 | 1,724 137 | 37 Subtract line 36 from line 22. This is your adjusted gross income 138 | 37 139 | 407,009. 140 | 141 | LHA For Disclosure, Privacy Act, and Paperwork Reduction Act Notice, see separate instructions. 142 | Form 1040 (2013) 143 | -------------------------------------------------------------------------------- /examples/tax/Unencrypted_Obama_Tax_Return.txt: -------------------------------------------------------------------------------- 1 | 1040 2 | U.S. Individual Income Tax Return(99) 3 | 2013 4 | OMB No 1545-0074 5 | IRS Use Only - Do not write or staple in this space. 6 | For the year Jan. 1-Dec. 31, 2013, or other tax year beginning , 2013, ending 20 7 | See separate instructions. 8 | Your first name and initial 9 | BARACK H. 10 | Last name 11 | OBAMA 12 | Your social security number 13 | If a joint return, spouse's first name and initial 14 | MICHELLE L. 15 | Last name 16 | OBAMA 17 | Spouse's social security number 18 | Home address (number and street). If you have a P.O. box, see instructions. 19 | 1600 PENNSYLVANIA AVENUE, NW 20 | Apt no. 21 | A Make sure the SSN(s) above 22 | and on line 6c are correct 23 | City, town or post office, state, and ZIP code. If you have a foreign address, also complete spaces below. 24 | WASHINGTON , DC 25 | 20500 26 | Presidential Election Campaign 27 | Check here if you, or your spouse 28 | if filing jointly, want $3 to go to 29 | this fund. Checking a box below 30 | will not change your tax or refund. 31 | X You 32 | X Spouse 33 | Foreign country name 34 | Foreign province/state/county 35 | Foreign postal code 36 | 1 Single 37 | 2 X Married filing jointly (even if only one had income) 38 | 3 Married filing separately. Enter spouse's SSN above and full name here. 39 | 4 Head of household (with qualifying person). If the qualifying person is a child but not your dependent, enter this child's name here. 40 | 5 Qualifying widow(er) with dependent child 41 | 6a X Yourself. If someone can claim you as a dependent, do not check box 6a 42 | b X Spouse 43 | If more than four 44 | dependents, see 45 | instructions and 46 | check here 47 | Dependents: 48 | (1) First name Last name 49 | (2) Dependent's social security number 50 | (3) Dependent's relationship to you 51 | (4) if child under age 17 wualifying for child tax credit 52 | MALIA A OBAMA 53 | DAUGHTER 54 | X 55 | NATASHA M OBAMA. 56 | DAUGHTER 57 | X 58 | Boxes checked 59 | on 6a and 6b 60 | 2 61 | No. of children 62 | on 6c who: 63 | lived with you 64 | d did not live with 65 | you due to divorce 66 | or separation 67 | (see instructions) 68 | 2 69 | 70 | Dependents on 6c 71 | not entered above 72 | 73 | 74 | Add numbers 75 | on line above 76 | d Total number of exemptions claimed 77 | 4 78 | Income 79 | 7 Wages, salaries, tips, etc. Attach Form(s) W-2 80 | 7 81 | 394,796 . 82 | 8a Taxable interest Attach Schedule B if required 83 | 8a 84 | 6,575 85 | b Tax-exempt interest Do not include on line 8a 86 | Attach Form(s) 87 | W-2 here. Also 88 | 9a Ordinary dividends. Attach Schedule B if required 89 | attach Forms 90 | b Qualified dividends 91 | W-2G and 92 | 10 Taxable refunds, credits, or offsets of state and local income taxes 93 | STMT 1 94 | STMT 3 95 | 0 . 96 | 1099-R if tax 97 | was withheld. 98 | 11 99 | Alimony received 100 | 12 Business income or (loss). Attach Schedule C or C-EZ 101 | 104,809. 102 | 13 Capital gain or (loss). Attach Schedule D if required. If not required, check here 103 | 13 104 | -3,000. 105 | 14 Other gains or (losses). Attach Form 4797 106 | 15a IRA distributions 107 | 15a 108 | b Taxable amount 109 | 16a Pensions and annuities 110 | 16a 111 | b Taxable amount 112 | 17 Rental real estate, royalties, partnerships, S corporations, trusts, etc. Attach Schedule E 113 | 18 Farm income or (loss). Attach Schedule F 114 | 19 Unemployment compensation 115 | 20a Social security benefits 116 | b Taxable amount 117 | 21 118 | Other income. List type and amount 119 | 22 Combine the amounts in the far right column for lines 7 through 21. This is your total income 120 | 22 121 | 503,183. 122 | 23 Educator expenses 123 | 23 124 | 24 Certain business expenses of reservists, performing artists, and fee-basis government 125 | 24 officials. Attach Form 2106 or 2106-EZ 126 | 25 Health savings account deduction. Attach Form 8889 127 | 26 Moving expenses. Attach Form 3903 128 | 27 Deductible part of self-emplayment tax 129 | 28 Self-employed SEP, SIMPLE, and qualified plans 130 | 29 Self-employed health insurance deduction 131 | 30 Penalty on early withdrawal of savings 132 | 31a Alimony paid b Recipient's SSN 133 | 32 IRA deduction 134 | 33 Student loan interest deduction 135 | 34 Tuition and fees. Attach Form 8917 136 | 35 Domestic production activities deduction. Attach Form 8903 137 | 36 Add lines 23 through 35 138 | 36 139 | 22,085. 140 | 37 Subtract line 36 from line 22. This is your adjusted gross income 141 | 37 142 | 481,098 143 | 144 | LHA For Disclosure, Privacy Act, and Paperwork Reduction Act Notice, see separate instructions. 145 | Form 1040 (2013) 146 | -------------------------------------------------------------------------------- /factomFullInstall.md: -------------------------------------------------------------------------------- 1 | Factom Central Server Install Guide 2 | ========== 3 | 4 | Before the node network gets setup. Factom clients will simulate talking to a P2P network by using web services calls to a central server. For testing, it will be beneficial to developers to have their own central server. 5 | 6 | 7 | ## Prepare Operating System 8 | 9 | These directions were prepared on ubuntu 14.04. Variations have been reported to work on windows, but no guarantees. 10 | 11 | #### Install the go language 12 | 13 | It is best to follow the directions here to install golang for for your platform. http://golang.org/doc/install 14 | 15 | Examples for ubuntu are included here for expediency. 16 | 17 | ##### Install go and dependencies 18 | ``` 19 | sudo apt-get install git mercurial 20 | ``` 21 | download latest version of go https://golang.org/dl/ This example uses 64 bit linux and 1.4.1 is the latest version. 22 | 23 | ``` 24 | sudo tar -C /usr/local -xzf go1.4.1.linux-amd64.tar.gz 25 | ``` 26 | 27 | Put the go binary directory in you path. 28 | 29 | Open the file `~/.profile` and add these lines to the bottom. If they are not exact, then your ubuntu may not be bootable. 30 | 31 | ``` 32 | export PATH=$PATH:/usr/local/go/bin 33 | ``` 34 | 35 | note: using `sudo apt-get install golang` will install go version 1.2.1. Btcd requires go v1.3 or above. Compiling with v1.2.1 will cause the compiler to use [lots of ram](https://github.com/btcsuite/btcd/issues/277). 36 | 37 | ##### Setup gopath 38 | Open the file `~/.profile` and add these lines to the bottom. If they are not exact, then your ubuntu may not be bootable. 39 | 40 | ``` 41 | export GOPATH=$HOME/go 42 | export PATH=$PATH:$GOPATH/bin 43 | ``` 44 | 45 | **logout and login**. This is the most straightforward way to run/test these changes. 46 | 47 | # Install BTC Suite 48 | 49 | ### Install BTCD 50 | ``` 51 | go get -v github.com/btcsuitereleases/btcd/... 52 | mkdir $HOME/.btcd/ 53 | cp $GOPATH/src/github.com/btcsuitereleases/btcd/sample-btcd.conf $HOME/.btcd/btcd.conf 54 | ``` 55 | 56 | In a text editor open `$HOME/.btcd/btcd.conf` 57 | 58 | Uncomment the line `testnet=1` 59 | 60 | uncomment rpcuser and rpcpass and set them to: 61 | `rpcuser=testuser` 62 | `rpcpass=SecurePassHere` 63 | 64 | 65 | In a console window, run `btcd` and wait for it to download the testnet blockchain. This will take a while, unless you can copy the folder `~/.btcd/data/testnet/` from an already running version of btcd. Note, copying the levelDB files may cause problems with btcd. It may be more prudent to merely run `btcd --connect=` to download the blockchain. 66 | 67 | 68 | ### Install Wallet 69 | 70 | ``` 71 | go get -v github.com/btcsuitereleases/btcwallet/... 72 | mkdir $HOME/.btcwallet/ 73 | cp $GOPATH/src/github.com/btcsuitereleases/btcwallet/sample-btcwallet.conf $HOME/.btcwallet/btcwallet.conf 74 | ``` 75 | 76 | In a text editor open `$HOME/.btcwallet/btcwallet.conf` 77 | 78 | In the RPC section, uncomment and set: 79 | `username=testuser` 80 | `password=SecurePassHere` 81 | 82 | In a second console window, run `btcwallet --create` 83 | 84 | Follow the directions to create a wallet. Give it password which is hard to guess. One example password is `HardToGuessPW` which will be used as an example later. It will be in a config file, so it will not be that secure, though. 85 | 86 | 87 | ### Install GUI 88 | 89 | This is not strictly necessary, but is needed if you want to know where to send testnet BTC and diagnose some issues. Command line alternatives are listed below. 90 | 91 | 92 | ``` 93 | sudo apt-get install libgtk-3-dev libcairo2-dev libglib2.0-dev libsasl2-dev 94 | go get -v -tags gtk_3_10 github.com/btcsuitereleases/btcgui/... 95 | mkdir $HOME/.btcgui/ 96 | cp $GOPATH/src/github.com/btcsuitereleases/btcgui/sample-btcgui.conf $HOME/.btcgui/btcgui.conf 97 | ``` 98 | 99 | open `$HOME/.btcgui/btcgui.conf` in a text editor 100 | In the Authentication section, uncomment and set: 101 | `username=testuser` 102 | `password=SecurePassHere` 103 | 104 | Run `btcd` & `btcwallet` each in separate terminal windows. 105 | 106 | In a 3rd terminal window run `btcgui` 107 | 108 | Send testnet bitcoins to an address in gui 109 | 110 | 111 | ### Command Line Alternatives to GUI 112 | 113 | 114 | You might be able to get by with some command line arguments. This one outputs an address in your wallet `btcctl --rpcuser=testuser --rpcpass=SecurePassHere --testnet --wallet getaccountaddress "default"`. Save the address it gives you and send testnet bitcoins to it. You can use `btcctl --rpcuser=testuser --rpcpass=SecurePassHere --testnet --wallet listreceivedbyaccount` to see if money has been sent to the wallet. Also `btcctl --rpcuser=testuser --rpcpass=SecurePassHere --testnet --wallet listtransactions` to see what has happened in the wallet. 115 | 116 | 117 | 118 | # Install Factom Central Server 119 | 120 | These install directions are rudimentary because factom at this point should be used as a client, unless you are doing local server degugging. 121 | 122 | Run `go get -v github.com/FactomProject/FactomCode/factomd` 123 | Put https://github.com/FactomProject/FactomCode/raw/development/factomd/factomd.conf in `~/.factom/` 124 | Run `factomd` 125 | 126 | 127 | -------------------------------------------------------------------------------- /images/Keymaker1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/images/Keymaker1.png -------------------------------------------------------------------------------- /images/Keymaker10.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/images/Keymaker10.png -------------------------------------------------------------------------------- /images/Keymaker11.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/images/Keymaker11.png -------------------------------------------------------------------------------- /images/Keymaker12.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/images/Keymaker12.png -------------------------------------------------------------------------------- /images/Keymaker13.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/images/Keymaker13.png -------------------------------------------------------------------------------- /images/Keymaker14.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/images/Keymaker14.png -------------------------------------------------------------------------------- /images/Keymaker15.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/images/Keymaker15.png -------------------------------------------------------------------------------- /images/Keymaker16.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/images/Keymaker16.png -------------------------------------------------------------------------------- /images/Keymaker17.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/images/Keymaker17.png -------------------------------------------------------------------------------- /images/Keymaker2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/images/Keymaker2.png -------------------------------------------------------------------------------- /images/Keymaker3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/images/Keymaker3.png -------------------------------------------------------------------------------- /images/Keymaker4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/images/Keymaker4.png -------------------------------------------------------------------------------- /images/Keymaker5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/images/Keymaker5.png -------------------------------------------------------------------------------- /images/Keymaker6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/images/Keymaker6.png -------------------------------------------------------------------------------- /images/Keymaker7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/images/Keymaker7.png -------------------------------------------------------------------------------- /images/Keymaker8.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/images/Keymaker8.png -------------------------------------------------------------------------------- /images/Keymaker9.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/images/Keymaker9.png -------------------------------------------------------------------------------- /images/Whitepaper---Entries-Blocks-written-as-Factom-Blocks.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/images/Whitepaper---Entries-Blocks-written-as-Factom-Blocks.png -------------------------------------------------------------------------------- /images/Whitepaper---Factom---Proof-of-Existance-Layer.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/images/Whitepaper---Factom---Proof-of-Existance-Layer.png -------------------------------------------------------------------------------- /images/Whitepaper---Factom-Complete-System.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/images/Whitepaper---Factom-Complete-System.png -------------------------------------------------------------------------------- /images/Whitepaper---Factom-Layer-Diagram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/images/Whitepaper---Factom-Layer-Diagram.png -------------------------------------------------------------------------------- /images/Whitepaper---Hashes-and-Data-are-Written-to-Entry-Blocks.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/images/Whitepaper---Hashes-and-Data-are-Written-to-Entry-Blocks.png -------------------------------------------------------------------------------- /images/chain-structure.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/images/chain-structure.png -------------------------------------------------------------------------------- /images/controlpanel.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/images/controlpanel.png -------------------------------------------------------------------------------- /images/factom-cli.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/images/factom-cli.png -------------------------------------------------------------------------------- /images/factomd.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/images/factomd.png -------------------------------------------------------------------------------- /images/fctwallet.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/FactomProject/FactomDocs/9854984cd85fc9c6cd81b9a3f1598e7b36ffae95/images/fctwallet.png -------------------------------------------------------------------------------- /installFromSourceDirections.md: -------------------------------------------------------------------------------- 1 | Community Tester Install Guide for Factom Federation (M2) 2 | ========== 3 | 4 | This will walk you through setting up the experimental distributed version of Factom. 5 | 6 | ### Prepare Operating System 7 | 8 | The most testing to date has been done under Linux. To get the best testing experience, it should be done on Linux. That will also help us recreate the bugs you experience better. If you are running Windows, please install a virtual machine to run Factom. Installing on Windows has been known to work, but is not covered here. 9 | 10 | Here are some good directions to get a virtual machine installed with Linux. http://www.instructables.com/id/Introduction-38/?ALLSTEPS 11 | 12 | The following are assuming you are using the 64 bit version of Ubuntu, or one of its descendant projects like xubuntu or mint. 13 | 14 | #### Install the go language and dependencies, then setup GOPATH 15 | 16 | ###### Install Package Managers 17 | 18 | In a terminal window, install Git 19 | 20 | On Linux: 21 | ``` 22 | sudo apt-get install git 23 | ``` 24 | 25 | On Mac: 26 | Steps 1 and 3 should be enough in this tutorial: 27 | https://confluence.atlassian.com/pages/viewpage.action?pageId=269981802 28 | 29 | ###### Install Golang 30 | 31 | Download latest version of go https://golang.org/dl/ This example uses 64 bit Linux and 1.12 is the latest tested version. 32 | ``` 33 | sudo tar -C /usr/local -xzf go1.12.linux-amd64.tar.gz 34 | ``` 35 | 36 | On Mac, installing go this way should work: 37 | http://www.cyberciti.biz/faq/installing-go-programming-language-on-mac-os-x/ 38 | 39 | 40 | ###### Setup Paths 41 | 42 | Put the go binary directory in you path. Also add the GOPATH to your profile. 43 | Open the file `~/.profile` and add these lines to the bottom. If they are not exact, then your Linux may not be bootable. 44 | ``` 45 | export PATH=$PATH:/usr/local/go/bin 46 | 47 | export GOPATH=$HOME/go 48 | export PATH=$PATH:$GOPATH/bin 49 | ``` 50 | **logout and login**. This is the most straightforward way to run/test these changes. Run `go version` from a terminal to verify the install. 51 | 52 | 53 | ### Install Factom 54 | 55 | Currently, the blog post [here](https://factom.com/blog/factom-launches-federated-testnet) has some screenshots of what to expect Factom Federation (M2) to look like. 56 | 57 | These steps will get factom installed onto a linux machine. The steps should be similar for mac. 58 | 59 | ``` 60 | # install glide, the package dependency manager 61 | go get -u github.com/Masterminds/glide 62 | # download the code 63 | git clone https://github.com/FactomProject/factomd $GOPATH/src/github.com/FactomProject/factomd 64 | git clone https://github.com/FactomProject/factom-cli $GOPATH/src/github.com/FactomProject/factom-cli 65 | git clone https://github.com/FactomProject/factom-walletd $GOPATH/src/github.com/FactomProject/factom-walletd 66 | git clone https://github.com/FactomProject/enterprise-wallet $GOPATH/src/github.com/FactomProject/enterprise-wallet 67 | 68 | # To use the unstable development branch, uncomment these lines 69 | # This is primarily for developers who are updating factom itself 70 | # Leave alone to get the tested, released version. 71 | cd $GOPATH/src/github.com/FactomProject/factomd 72 | # git checkout develop 73 | cd $GOPATH/src/github.com/FactomProject/factom-cli 74 | # git checkout develop 75 | cd $GOPATH/src/github.com/FactomProject/factom-walletd 76 | # git checkout develop 77 | cd $GOPATH/src/github.com/FactomProject/enterprise-wallet 78 | # git checkout develop 79 | 80 | # get the dependencies and build each factom program 81 | glide cc 82 | cd $GOPATH/src/github.com/FactomProject/factomd 83 | glide install 84 | go install -ldflags "-X github.com/FactomProject/factomd/engine.Build=`git rev-parse HEAD` -X github.com/FactomProject/factomd/engine.FactomdVersion=`cat VERSION`" -v 85 | cd $GOPATH/src/github.com/FactomProject/factom-cli 86 | glide install 87 | go install -ldflags "-X main.FactomcliVersion=`cat VERSION`" -v 88 | cd $GOPATH/src/github.com/FactomProject/factom-walletd 89 | glide install 90 | go install -ldflags "-X github.com/FactomProject/factom-walletd/vendor/github.com/FactomProject/factom/wallet.WalletVersion=`cat ./vendor/github.com/FactomProject/factom/wallet/VERSION`" -v 91 | cd $GOPATH/src/github.com/FactomProject/enterprise-wallet 92 | glide install 93 | go install -v 94 | cd $GOPATH/src/github.com/FactomProject/factomd 95 | 96 | # done. factomd should be installed 97 | # you can optionally use a config file to run in a non-standard mode 98 | # mkdir -p ~/.factom/m2/ 99 | # cp $GOPATH/src/github.com/FactomProject/factomd/factomd.conf ~/.factom/m2/ 100 | ``` 101 | 102 | 103 | ### Starting Factom 104 | 105 | Note: currently factomd uses a lot of drive accesses when running. It is reccomended to hold the blockchain on a solid state drive. Running factomd on a spinning hard drive will be arduously slow. Factomd currently scans the entire blockchain the first time it is started after if downloads the blockchain, bootup takes a while the first two times, but it is faster after is downloads and is restarted once. You can watch the progress on the [Control Panel](http://localhost:8090/). 106 | 107 | ### Factom Wallets 108 | 109 | Most users will want to run either the API wallet factom-walletd or the GUI wallet enterprise-wallet. Directions for those are located here: https://docs.factom.com/wallet#run-the-factom-foundation-wallet 110 | 111 | Although the factomd API is backwards compatible, the API extended by the old API wallet, fctwallet, is not supported by factom-walletd. The entire wallet from M1 can be imported into factom-walletd using the -i flag and an empty ~/.factom/wallet directory. 112 | 113 | Some users will want to use the old fctwallet with the new factomd. Follow the directions [here](legacyWallets.md) to compile the old programs. 114 | 115 | 116 | ### Testing Factom 117 | 118 | You can run a local version of factomd to get greater flexibility by running it like this: 119 | 120 | `factomd -network=LOCAL` 121 | 122 | This will make a new blockchain without worrying about other's data interfering with your testing. You can use the key `factom-cli importaddress Fs1KWJrpLdfucvmYwN2nWrwepLn8ercpMbzXshd1g8zyhKXLVLWj` to get local Factoids after starting factom-walletd. 123 | 124 | For issues with the software, please post [here](https://github.com/FactomProject/factomd/issues). 125 | 126 | 127 | 128 | 129 | -------------------------------------------------------------------------------- /legacyWallets.md: -------------------------------------------------------------------------------- 1 | Factoid Legacy Wallet Guide 2 | ========== 3 | 4 | ### Install Instructions 5 | 6 | Factom install directions have been created for M2 [here](installFromSourceDirections.md). 7 | 8 | The old wallet (fctwallet and walletapp) will continue to work though. The updated M2 factomd has a new V2 API which provides more feedback, but the older V1 API still is supported. Fctwallet is an API based wallet, but can be interfaced with using factom-cli. The latest version of factom-cli no longer recognizes fctwallet, but the legacy verison was renamed to factom-cli1. This program will control fctwallet. Walletapp can also read the old wallets as well. The legacy wallets are much slower when operating on M2 factomd compared with M1. 9 | 10 | 11 | These instructions will install the legacy wallets. 12 | 13 | 14 | 15 | ``` 16 | # install glide, the package dependency manager 17 | go get -u github.com/Masterminds/glide 18 | # download the code 19 | git clone https://github.com/FactomProject/factom-cli1 $GOPATH/src/github.com/FactomProject/factom-cli1 20 | git clone https://github.com/FactomProject/fctwallet $GOPATH/src/github.com/FactomProject/fctwallet 21 | git clone https://github.com/FactomProject/walletapp $GOPATH/src/github.com/FactomProject/walletapp 22 | 23 | # get the dependencies and build each factom program 24 | glide cc 25 | cd $GOPATH/src/github.com/FactomProject/factom-cli1 26 | glide install 27 | go install 28 | cd $GOPATH/src/github.com/FactomProject/fctwallet 29 | glide install 30 | go install 31 | cd $GOPATH/src/github.com/FactomProject/walletapp 32 | glide install 33 | go install 34 | # almost done. To use walletapp with the GUI webpage, you need to copy the source HTML files to the proper location/ 35 | 36 | # sudo mkdir -p /usr/share/factom/walletapp/ 37 | # sudo cp -r $GOPATH/src/github.com/FactomProject/walletapp/staticfiles/* /usr/share/factom/walletapp/ 38 | ``` 39 | 40 | Earlier commands that used factom-cli will now work using the command factom-cli1. 41 | 42 | 43 | 44 | ### Legacy Wallet Import Instructions 45 | 46 | Most users will just want to port the legacy wallet databases into the new enterprise-wallet or factom-walletd. factom-walletd is much faster and is more robust. The existing `factoid_wallet_bolt.db` contains the private keys for both fctwallet and walletapp. Both Enterprise and factom-walletd share the new `factom_wallet.db` file. Only Enterprise wallet uses the `factom_wallet_gui.db` file to save metadata about the addresses in `factom_wallet.db`. The `factoid_blocks.cache` file enables the wallets to restart quickly. 47 | 48 | ##### factom-walletd 49 | 50 | factom-walletd is the API wallet for new updated M2 version of factom. It is accessed through the factom-cli program, as well as a V2 JSON PRC. 51 | 52 | One disadvantage of porting wallets from fctwallet to factom-walletd is that the address nicknames will be lost. Factom-walletd does not support address names, and addresses must be used by their public keys. 53 | 54 | When a new wallet is made, a new BIP-44 seed is created from randomness. 55 | 56 | To import, start factom-walletd with the -i flag and specify the M1 wallet. This will specify where the M1 wallet is located and to import the addresses from it. Factom-walletd will exit after it imports the addresses. 57 | 58 | ``` 59 | $ factom-walletd -i ~/.factom/factoid_wallet_bolt.db 60 | Reading from '/home/factom/.factom/m2/factomd.conf' 61 | Cannot open custom config file, 62 | Starting with default settings. 63 | open /home/factom/.factom/m2/factomd.conf: no such file or directory 64 | 65 | Warning, factom-walletd API is not password protected. Factoids can be stolen remotely. 66 | Warning, factom-walletd API connection is unencrypted. Password is unprotected over the network. 67 | 2017/01/14 15:51:56 Importing version 1 wallet /home/factom/.factom/factoid_wallet_bolt.db into /home/factom/.factom/wallet/factom_wallet.db 68 | Database started from: /home/factom/.factom/wallet/factom_wallet.db 69 | ``` 70 | 71 | 72 | - `factom-cli backupwallet` will export the BIP-44 seed as well as the private keys for all addresses held by the wallet. 73 | - `factom-cli exportaddresses` will export the public/private keypairs of all addresses in the wallet. 74 | - `factom-cli importaddress` will import a list of private keys into the wallet. 75 | 76 | To save the valuable keys and to review progress, you can import and export keys with the above commands. The most reliable backup method is to copy the `factom_wallet.db` to a safe location and recording the 12 words for newly created addresses. 77 | 78 | 79 | 80 | ##### Enterprise Wallet 81 | 82 | Here are the import instructions for Enterprise Wallet: 83 | https://docs.factom.com/#run-the-factom-foundation-wallet 84 | 85 | Enterprise Wallet automatically imports old wallets if they are in the default location. If they are in a different location, old wallets can be imported with `enterprise-wallet -v1path=~/Desktop/factoid_wallet_bolt.db` 86 | 87 | -------------------------------------------------------------------------------- /wallet_info/bip44_test.py: -------------------------------------------------------------------------------- 1 | 2 | from binascii import hexlify, unhexlify 3 | from mnemonic import Mnemonic 4 | 5 | from bip32utils.BIP32Key import * 6 | 7 | import ed25519 8 | import base58, hashlib 9 | 10 | #Replace secret words from koinify wallet below 11 | words = "yellow yellow yellow yellow yellow yellow yellow yellow yellow yellow yellow yellow" 12 | 13 | #uncomment print statements below to see interim datapoints 14 | 15 | seed = Mnemonic.to_seed(words, '') 16 | #print "seed derived from words: " + hexlify(seed) 17 | 18 | rootkey = BIP32Key.fromEntropy(seed, public=False) 19 | #print "BIP32 root key: " + rootkey.ExtendedKey(private=True, encoded=False).encode('hex') 20 | 21 | BIP44subkey = rootkey.ChildKey(BIP32_HARDEN+44) 22 | 23 | factoidCoinType = BIP44subkey.ChildKey(BIP32_HARDEN+131) 24 | 25 | accountZero = factoidCoinType.ChildKey(BIP32_HARDEN) 26 | 27 | externalFacingKeys = accountZero.ChildKey(0) 28 | 29 | bip32ExtendedKey = externalFacingKeys.ExtendedKey(private=True, encoded=True) 30 | 31 | print "factom bip44 seed: " + words 32 | 33 | print "factoid bip32 extended key " + bip32ExtendedKey 34 | 35 | privkey0 = externalFacingKeys.ChildKey(0).PrivateKey() 36 | privkey1 = externalFacingKeys.ChildKey(1).PrivateKey() 37 | 38 | print "private key hex 0: " + privkey0.encode('hex') 39 | print "private key hex 1: " + privkey1.encode('hex') 40 | 41 | privkey0prefixed = "6478" + privkey0.encode('hex') 42 | digest = hashlib.sha256(hashlib.sha256(privkey0prefixed.decode("hex")).digest()).digest() 43 | print "human readable private key 0: " + base58.b58encode(privkey0prefixed.decode("hex") + digest[:4]) 44 | 45 | privkey1prefixed = "6478" + privkey1.encode('hex') 46 | digest = hashlib.sha256(hashlib.sha256(privkey1prefixed.decode("hex")).digest()).digest() 47 | print "human readable private key 1: " + base58.b58encode(privkey1prefixed.decode("hex") + digest[:4]) 48 | 49 | 50 | privint0 = ed25519.SigningKey(privkey0) 51 | privint1 = ed25519.SigningKey(privkey1) 52 | pubint0 = privint0.get_verifying_key() 53 | pubint1 = privint1.get_verifying_key() 54 | 55 | rawpubkey0 = pubint0.to_ascii(encoding="hex") 56 | rawpubkey1 = pubint1.to_ascii(encoding="hex") 57 | 58 | rcd0 = "01" + rawpubkey0 59 | rcd1 = "01" + rawpubkey1 60 | 61 | rcdhash0 = hashlib.sha256(hashlib.sha256(rcd0.decode("hex")).digest()).digest().encode("hex") 62 | rcdhash1 = hashlib.sha256(hashlib.sha256(rcd1.decode("hex")).digest()).digest().encode("hex") 63 | 64 | pub0prefixed = "5fb1" + rcdhash0 65 | digest = hashlib.sha256(hashlib.sha256(pub0prefixed.decode("hex")).digest()).digest() 66 | print "human readable address 0: " + base58.b58encode(pub0prefixed.decode("hex") + digest[:4]) 67 | 68 | pub1prefixed = "5fb1" + rcdhash1 69 | digest = hashlib.sha256(hashlib.sha256(pub1prefixed.decode("hex")).digest()).digest() 70 | print "human readable address 1: " + base58.b58encode(pub1prefixed.decode("hex") + digest[:4]) 71 | # ^ note this is base58 encode, not base58check encode. base58check adds extra checksum data which we have added manually already. 72 | 73 | 74 | 75 | ''' 76 | Results of execution 77 | 78 | factom bip44 seed: yellow yellow yellow yellow yellow yellow yellow yellow yellow yellow yellow yellow 79 | factoid bip32 extended key xprvA22bpQKA9av7gEKdskwxbBNaMso6XpmW7sXi5LGgKnGCMe82BYW68tcNXtn4ZiLHDYJ2HpRvknV7zdDSgBXtPo4dRwG8XCcU55akAcarx3G 80 | private key hex 0: 36422e9560f56e0ead53a83b33aec9571d379291b5e292b88dec641a98ef05d8 81 | private key hex 1: d595251fcf8c5893476e35284f90b809fb6c2ff6f3e19dcf04f7a76af7644720 82 | human readable private key 0: Fs1jQGc9GJjyWNroLPq7x6LbYQHveyjWNPXSqAvCEKpETNoTU5dP 83 | human readable private key 1: Fs2wZzM2iBn4HEbhwEUZjLfcbTo5Rf6ChRNjNJWDiyWmy9zkPQNP 84 | human readable address 0: FA22de5NSG2FA2HmMaD4h8qSAZAJyztmmnwgLPghCQKoSekwYYct 85 | human readable address 1: FA3heCmxKCk1tCCfiAMDmX8Ctg6XTQjRRaJrF5Jagc9rbo7wqQLV 86 | 87 | 88 | ''' 89 | 90 | -------------------------------------------------------------------------------- /wallet_info/token_sale/README.md: -------------------------------------------------------------------------------- 1 | Factom Token Sale Address Derivation 2 | ========== 3 | 4 | The token sale will cause Bitcoins to be sent from the purchaser to the Factom multisignature address. The Koinify wallet will attach the desired Factoid public key to the payment with an OP_RETURN statement. The Factoid genesis block will credit these public keys. 5 | 6 | Perform this procedure only with small value Koinify wallets, because mistakes can compromise all the assets held in Koinify. Do not use the wallet for high values in the future either. 7 | 8 | This is intended only for software licence token experts to audit the Factoid purchase mechanism. Do not use this procedure if you are not a software licence token expert. 9 | 10 | ## Setup Environment 11 | 12 | To protect all Koinify asset's private keys, the secret words should not be entered until the computer is offline. 13 | 14 | - Remove Hard drive, and other permanent storage devices 15 | - Boot to a CD version of linux. This example uses xubuntu 14.04. 16 | - Connect to the internet 17 | - in terminal run `sudo apt-get install python-setuptools` 18 | - Download [python-mnemonic](https://github.com/trezor/python-mnemonic/archive/master.zip) 19 | - unzip and run `sudo python setup.py install` in terminal for python-mnemonic 20 | - Download [bip32utils](https://github.com/jmcorgan/bip32utils/archive/master.zip) 21 | - unzip and run `sudo python setup.py install` in terminal for bip32utils 22 | - Download [ecdsa](https://pypi.python.org/packages/source/e/ecdsa/ecdsa-0.13.tar.gz#md5=1f60eda9cb5c46722856db41a3ae6670) 23 | - unzip and run `sudo python setup.py install` in terminal for ecdsa 24 | - Download [ed25519](https://pypi.python.org/packages/d5/d6/cd19a64022dc7557d245aad6a943eed7693189b48c58a9adf3bc00ceedc5/ed25519-1.4.tar.gz#md5=7c9401afca45dcb3fdefdc8a5990bab3) 25 | - in terminal run `sudo apt-get install python-dev` 26 | - unzip and run `sudo python setup.py install` in terminal for ed25519 27 | 28 | - Download [words_to_factoid_purchase.py](https://raw.githubusercontent.com/FactomProject/FactomDocs/master/wallet_info/token_sale/words_to_factoid_purchase.py) 29 | - in terminal run `python words_to_factoid_purchase.py`. If working it should output `data encoded in OP_RETURN is: 464143544f4d303023f0e67ac88d0e39d6f3a894570efee943cd1c326f1d866647151194a8e01e21` 30 | 31 | ## Run the test 32 | 33 | - **Disable internet** 34 | - open `words_to_factoid_purchase.py` in a text editor 35 | - replace the example words with the ones written down during the Koinify wallet creation 36 | - run with `python words_to_factoid_purchase.py` 37 | - The data displayed should be the data which appears after the OP_RETURN in the Bitcoin Blockchain 38 | - Power down computer to erase memory 39 | 40 | -------------------------------------------------------------------------------- /wallet_info/token_sale/words_to_factoid_purchase.py: -------------------------------------------------------------------------------- 1 | 2 | from binascii import hexlify, unhexlify 3 | from mnemonic import Mnemonic 4 | 5 | from bip32utils.BIP32Key import * 6 | 7 | import ed25519 8 | 9 | #Replace secret words from koinify wallet below 10 | words = "legal winner thank year wave sausage worth useful legal winner thank yellow" 11 | 12 | #uncomment print statements below to see interim datapoints 13 | 14 | seed = Mnemonic.to_seed(words, '') 15 | #print "seed derived from words: " + hexlify(seed) 16 | 17 | rootkey = BIP32Key.fromEntropy(seed, public=False) 18 | #print "BIP32 root key: " + rootkey.ExtendedKey(private=True, encoded=False).encode('hex') 19 | 20 | factoidChildKey = rootkey.ChildKey(BIP32_HARDEN+7) 21 | #print "BIP32 root of Factoid chain key: " + factoidChildKey.ExtendedKey(private=True, encoded=False).encode('hex') 22 | 23 | last32 = factoidChildKey.ExtendedKey(private=True, encoded=False)[-32:] 24 | #print "Last 32 bytes: " + last32.encode('hex') 25 | 26 | signing_key = ed25519.SigningKey(last32) 27 | #print "The private key (ed25519 seed k) is: " + signing_key.to_ascii(encoding="hex") 28 | 29 | verifying_key = signing_key.get_verifying_key() 30 | pubkeyHex = verifying_key.to_ascii(encoding="hex") 31 | #print "The public key is: " + pubkeyHex 32 | 33 | opheader = "464143544f4d3030" 34 | opdata = opheader + pubkeyHex 35 | 36 | print "data encoded in OP_RETURN is: " + opdata 37 | 38 | 39 | 40 | -------------------------------------------------------------------------------- /wallet_info/wallet_test_vectors.md: -------------------------------------------------------------------------------- 1 | Factom BIP44 derivations 2 | ========== 3 | 4 | Note: the 12 words from the koinify token sale used a different, incompatible address derivation. The koinify derivation is located [here](https://github.com/FactomProject/FactomDocs/tree/master/wallet_info/token_sale). **Don't use your Koinify words as a BIP44 wallet.** 5 | 6 | 7 | There are two coin types in the Factom system: Factoids and Entry Credits (ECs). There is a coin type for each: 8 | 9 | See the slip-44 [source](https://github.com/satoshilabs/slips/blob/master/slip-0044.md). 10 | 11 | index | hexa | coin 12 | ------|------------|----------------------------------- 13 | 131 | 0x80000083 | [Factom Factoids](https://github.com/FactomProject) 14 | 132 | 0x80000084 | [Factom Entry Credits](https://github.com/FactomProject) 15 | 16 | 17 | A Factoid test vector generator is located [here](https://github.com/FactomProject/FactomDocs/tree/master/wallet_info/bip44_test.py). 18 | To run this program the same libraries as [this](https://github.com/FactomProject/FactomDocs/tree/master/wallet_info/token_sale/README.md) are needed, plus the base58 python library. 19 | 20 | The test vectors for the Factoid BIP44 wallets are: 21 | ``` 22 | factom bip44 seed: yellow yellow yellow yellow yellow yellow yellow yellow yellow yellow yellow yellow 23 | factoid bip32 extended key xprvA22bpQKA9av7gEKdskwxbBNaMso6XpmW7sXi5LGgKnGCMe82BYW68tcNXtn4ZiLHDYJ2HpRvknV7zdDSgBXtPo4dRwG8XCcU55akAcarx3G 24 | private key hex 0: 36422e9560f56e0ead53a83b33aec9571d379291b5e292b88dec641a98ef05d8 25 | private key hex 1: d595251fcf8c5893476e35284f90b809fb6c2ff6f3e19dcf04f7a76af7644720 26 | human readable private key 0: Fs1jQGc9GJjyWNroLPq7x6LbYQHveyjWNPXSqAvCEKpETNoTU5dP 27 | human readable private key 1: Fs2wZzM2iBn4HEbhwEUZjLfcbTo5Rf6ChRNjNJWDiyWmy9zkPQNP 28 | human readable address 0: FA22de5NSG2FA2HmMaD4h8qSAZAJyztmmnwgLPghCQKoSekwYYct 29 | human readable address 1: FA3heCmxKCk1tCCfiAMDmX8Ctg6XTQjRRaJrF5Jagc9rbo7wqQLV 30 | ``` 31 | 32 | 33 | Factoids' public keys are hashed like P2SH addresses in Bitcoin. See description [here](https://github.com/FactomProject/FactomDocs/blob/master/factomDataStructureDetails.md#factoid-transaction). 34 | 35 | Entry Credits use raw ed25519 keys as a public key, so the public address derivation is [different](https://github.com/FactomProject/FactomDocs/blob/master/factomDataStructureDetails.md#entry-credit-address). 36 | 37 | 38 | -------------------------------------------------------------------------------- /whitepaper.md: -------------------------------------------------------------------------------- 1 | Download the Factom Whitepaper: 2 | 3 | https://github.com/FactomProject/FactomDocs/raw/master/Factom_Whitepaper.pdf 4 | --------------------------------------------------------------------------------