factom-identity-lib

### Table of Contents - [server][1] - [FactomServerIdentityManager][2] - [Parameters][3] - [Examples][4] - [addCoinbaseCancel][5] - [Parameters][6] - [getServerIdentity][7] - [Parameters][8] - [getServerIdentityHistory][9] - [Parameters][10] - [updateCoinbaseAddress][11] - [Parameters][12] - [updateEfficiency][13] - [Parameters][14] - [generateCoinbaseAddressUpdateEntry][15] - [Parameters][16] - [generateCoinbaseCancelEntry][17] - [Parameters][18] - [generateEfficiencyUpdateEntry][19] - [Parameters][20] - [app][21] - [FactomIdentityManager][22] - [Parameters][23] - [Examples][24] - [createIdentity][25] - [Parameters][26] - [getActivePublicIdentityKeys][27] - [Parameters][28] - [getIdentityName][29] - [Parameters][30] - [isIdentityKeyActive][31] - [Parameters][32] - [replaceIdentityKey][33] - [Parameters][34] - [extractCryptoMaterial][35] - [Parameters][36] - [FactomWalletdKeyStore][37] - [Parameters][38] - [Examples][39] - [generateIdentityKey][40] - [Parameters][41] - [getAllIdentityKeys][42] - [getSecretIdentityKey][43] - [Parameters][44] - [importIdentityKeys][45] - [Parameters][46] - [removeIdentityKeys][47] - [Parameters][48] - [generateRandomIdentityKeyPair][49] - [getPublicIdentityKey][50] - [Parameters][51] - [isValidIdentityKey][52] - [Parameters][53] - [isValidPublicIdentityKey][54] - [Parameters][55] - [isValidSecretIdentityKey][56] - [Parameters][57] - [keyToPublicIdentityKey][58] - [Parameters][59] - [seedToSecretIdentityKey][60] - [Parameters][61] ## server [src/server/index.js:6-6][62] Module containing functions about Factom server identities. ### FactomServerIdentityManager [src/server/factom-server-identity-manager.js:27-95][63] Main class to read and write Factom identities. #### Parameters - `opts` **[Object][64]?** Options of connection to factomd and factom-walletd. - `opts.factomd` **[Object][64]?** Options of connection to factomd. See [https://factomjs.luciap.ca/#connectionoptions][65]. - `opts.walletd` **[Object][64]?** Options of connection to factom-walletd. See [https://factomjs.luciap.ca/#connectionoptions][65]. #### Examples ```javascript const manager = new FactomServerIdentityManager({ factomd: { host: 'api.factomd.net', port: 443, protocol: 'https' }, walletd: { host: 'localhost', user: 'paul', password: 'pass' } }); ``` #### addCoinbaseCancel [src/server/factom-server-identity-manager.js:85-94][66] Add a coinbase cancel message to a server identity. ##### Parameters - `rootChainId` **[string][67]** Identity Root Chain Id. - `descriptorHeight` **[number][68]** Coinbase descriptor block height. - `descriptorIndex` **[number][68]** Coinbase descriptor index. - `sk1` **[string][67]** Server identity Secret Key 1. - `ecAddress` **[string][67]** Entry Credit address paying for the entry. Returns **{txId: [string][67], repeatedCommit: [boolean][69], chainId: [string][67], entryHash: [string][67]}** Info about the Entry insertion. #### getServerIdentity [src/server/factom-server-identity-manager.js:38-40][70] Get a server identity information. ##### Parameters - `rootChainId` **[string][67]** Identity Root Chain Id. Returns **{rootChainId: [string][67], serverManagementSubchainId: [string][67], coinbaseAddress: [string][67], efficiency: [number][68], identityKeys: [Array][71]<[string][67]>}** #### getServerIdentityHistory [src/server/factom-server-identity-manager.js:48-50][72] Get a server identity information history. ##### Parameters - `rootChainId` **[string][67]** Identity Root Chain Id. Returns **{rootChainId: [string][67], serverManagementSubchainId: [string][67], coinbaseAddressHistory: [Array][71]<[Object][64]>, efficiencyHistory: [Array][71]<[Object][64]>, identityKeys: [Array][71]<[string][67]>}** #### updateCoinbaseAddress [src/server/factom-server-identity-manager.js:60-62][73] Update the coinbase address of a server identity. ##### Parameters - `rootChainId` **[string][67]** Identity Root Chain Id. - `fctAddress` **[string][67]** Public Factoid address to set as coinbase address. - `sk1` **[string][67]** Server identity Secret Key 1. - `ecAddress` **[string][67]** Entry Credit address paying for the entry. Returns **{txId: [string][67], repeatedCommit: [boolean][69], chainId: [string][67], entryHash: [string][67]}** Info about the Entry insertion. #### updateEfficiency [src/server/factom-server-identity-manager.js:72-74][74] Update the efficiency of a server identity. ##### Parameters - `rootChainId` **[string][67]** Identity Root Chain Id. - `efficiency` **[number][68]** Efficiency between 0 and 100. - `sk1` **[string][67]** Server identity Secret Key 1. - `ecAddress` **[string][67]** Entry Credit address paying for the entry. Returns **{txId: [string][67], repeatedCommit: [boolean][69], chainId: [string][67], entryHash: [string][67]}** Info about the Entry insertion. ### generateCoinbaseAddressUpdateEntry [src/server/coinbase-address.js:115-127][75] Generate Entry object to update a server identity coinbase address. #### Parameters - `rootChainId` **[string][67]** Identity Root Chain Id. - `fctAddress` **[string][67]** Public Factoid address to set as the new coinbase address. - `sk1` **[string][67]** Server identity Secret Key 1. ### generateCoinbaseCancelEntry [src/server/coinbase-cancel.js:54-100][76] #### Parameters - `rootChainId` **[string][67]** Identity Root Chain Id. - `serverManagementSubchainId` **[string][67]** Server Management Subchain Id. - `height` **[number][68]** Block height of the coinbase descriptor to cancel. - `index` **[number][68]** Index of the coinbase descriptor to cancel. - `sk1` **[string][67]** Server identity Secret Key 1. ### generateEfficiencyUpdateEntry [src/server/efficiency.js:105-125][77] Generate Entry object to update a server identity efficiency. #### Parameters - `rootChainId` **[string][67]** Identity Root Chain Id. - `serverManagementSubchainId` **[string][67]** Server Management Subchain Id. - `efficiency` **[number][68]** Efficiency between 0 and 100. - `sk1` **[string][67]** Server identity Secret Key 1. Returns **{chainId: [Buffer][78], extIds: [Array][71]<[Buffer][78]>, content: [Buffer][78]}** ## app [src/app/index.js:5-5][79] Module containing functions about Factom identities for applications. ### FactomIdentityManager [src/app/factom-identity-manager.js:29-112][80] Main class to read and write Factom identities. #### Parameters - `daemonsConfig` **[Object][64]?** Configs of connection to factomd and factom-walletd. - `daemonsConfig.factomd` **[Object][64]?** Configs of connection to factomd. See [https://factomjs.luciap.ca/#connectionoptions][65]. - `daemonsConfig.walletd` **[Object][64]?** Configs of connection to factom-walletd. See [https://factomjs.luciap.ca/#connectionoptions][65]. - `opts` **[Object][64]?** Options. - `opts.initialCacheData` **[Object][64]?** Populate cache with some initial data. - `opts.save` **[Function][81]?** Synchronous or asynchronous function called to save the state of the cache. #### Examples ```javascript const manager = new FactomIdentityManager({ factomd: { host: 'api.factomd.net', port: 443, protocol: 'https' }, walletd: { host: 'localhost', user: 'paul', password: 'pass' } }); ``` #### createIdentity [src/app/factom-identity-manager.js:87-89][82] Create a new identity on-chain. ##### Parameters - `name` **[Array][71]<[string][67]>** Array of strings used as the "name" of the identity. - `keys` **([Array][71]<[string][67]> | [number][68])** Either an array of public identity keys or a number. If a number is provided the library generate new random keys (the secret keys are part of the returned object). - `ecAddress` **[string][67]** Entry Credit address paying for the entry. If a public EC address is provided the library attempts to retrieve the secret part from the configured walletd instance. Returns **[Array][71]<{identityKeys: {public: [string][67], secret: [string][67]}, txId: [string][67], repeatedCommit: [boolean][69], chainId: [string][67], entryHash: [string][67]}>** Info about the Chain creation together with the list of identity keys associated with the new identity. #### getActivePublicIdentityKeys [src/app/factom-identity-manager.js:43-45][83] Get all the active public identity keys of an identity at a given blockchain height. If no block height is specified, check for the latest block height. ##### Parameters - `identityChainId` **[string][67]** Identity chain id. - `blockHeight` **[number][68]?** Specific blockchain height. If not provided check for the latest block. Returns **[Array][71]<[string][67]>** Array of public identity keys active for the identity. #### getIdentityName [src/app/factom-identity-manager.js:52-54][84] Retrieve the identity "name" that was set at the creation of the identity chain. ##### Parameters - `identityChainId` **[string][67]** Identity chain id. Returns **[Array][71]<[Buffer][78]>** Array of Buffer representing the name of the identity. #### isIdentityKeyActive [src/app/factom-identity-manager.js:65-74][85] Check if an identity key is (was) active for an identity at a given blockchain height. If no block height is specified, check for the latest block height. ##### Parameters - `identityChainId` **[string][67]** Identity chain id. - `idKey` **[string][67]** Public or private identity key. - `blockHeight` **[number][68]?** Specific blockchain height. If not provided check for the latest block. Returns **[boolean][69]** True if the identity key is active for the identity. #### replaceIdentityKey [src/app/factom-identity-manager.js:103-111][86] Replace an identity key by another on-chain. ##### Parameters - `identityChainId` **[string][67]** Identity chain id. - `keys` **[Object][64]** - `keys.oldIdKey` **[string][67]** Old public identity key to replace. - `keys.newIdKey` **[string][67]** New public identity key to take the place of oldIdKey. - `keys.signingSecretIdKey` **[string][67]** Secret identity key signing for the replacement. Must be of same or higher priority than oldIdKey. - `ecAddress` **[string][67]** Entry Credit address paying for the entry. If a public EC address is provided the library attempts to retrieve the secret part from the configured walletd instance. Returns **{txId: [string][67], repeatedCommit: [boolean][69], chainId: [string][67], entryHash: [string][67]}** Info about the Entry insertion. ### extractCryptoMaterial [src/app/key-helpers.js:68-73][87] Extract the ed25519 cryptographic material encapsulated in the identity key. #### Parameters - `idKey` **[string][67]** Public or secret identity key. Returns **[Buffer][78]** Either the ed25519 32-byte public key or the 32-byte secret seed. ### FactomWalletdKeyStore [src/app/walletd-key-store.js:19-123][88] Helper class to user factom-walletd as a key store. #### Parameters - `opts` **[Object][64]?** Options of connection to factom-walletd. See [https://factomjs.luciap.ca/#connectionoptions][65]. #### Examples ```javascript const store = new FactomWalletdKeyStore({ host: 'localhost', user: 'paul', password: 'pass' }); ``` #### generateIdentityKey [src/app/walletd-key-store.js:110-122][89] Generates a new identity key from the wallet seed and stores it into walletd. New keys are generated from the same mnemonic seed used for FCT and EC addresses. ##### Parameters - `number` **[number][68]** Number of identity keys to generate. (optional, default `1`) Returns **{public: [string][67], secret: [string][67]}** #### getAllIdentityKeys [src/app/walletd-key-store.js:98-101][90] Get all identity keys stored in walletd. Returns **[Array][71]<{public: [string][67], secret: [string][67]}>** #### getSecretIdentityKey [src/app/walletd-key-store.js:30-40][91] Fetch corresponding identity key from the wallet if necessary. ##### Parameters - `idKey` **[string][67]** Identity key. Returns **[string][67]** Corresponsing secret identity key. #### importIdentityKeys [src/app/walletd-key-store.js:48-64][92] Import keys in walletd. ##### Parameters - `secretIdKeys` **([string][67] \| [Array][71]<[string][67]>)** A single secret key or an array of secret keys to import. Returns **[Array][71]<{public: [string][67], secret: [string][67]}>** #### removeIdentityKeys [src/app/walletd-key-store.js:70-91][93] Remove from walletd some identity keys. ##### Parameters - `idKeys` **([string][67] \| [Array][71]<[string][67]>)** ### generateRandomIdentityKeyPair [src/app/key-helpers.js:129-136][94] Generate a random identity key pair. Returns **{public: [string][67], secret: [string][67]}** Random identity key pair. ### getPublicIdentityKey [src/app/key-helpers.js:81-91][95] Get the public identity key corresponding to the input identity key. #### Parameters - `idKey` **[string][67]** Secret (or public) identity key. Returns **[string][67]** Corresponding public identity key. ### isValidIdentityKey [src/app/key-helpers.js:16-40][96] Check if an identity key is well formed. #### Parameters - `idKey` **[string][67]** Public or secret identity key. Returns **[boolean][69]** True if the identity key is valid. ### isValidPublicIdentityKey [src/app/key-helpers.js:48-50][97] Check if a public identity key is well formed. #### Parameters - `pubIdKey` **[string][67]** Public identity key. Returns **[boolean][69]** True if the public identity key is valid. ### isValidSecretIdentityKey [src/app/key-helpers.js:58-60][98] Check if a secret identity key is well formed. #### Parameters - `secIdKey` **[string][67]** Public identity key. Returns **[boolean][69]** True if the secret identity key is valid. ### keyToPublicIdentityKey [src/app/key-helpers.js:99-101][99] Convert a 32-byte key to a public identity key. #### Parameters - `key` **([string][67] \| [Buffer][78])** 32-byte key. Returns **[string][67]** Public identity key. ### seedToSecretIdentityKey [src/app/key-helpers.js:109-111][100] Convert a 32-byte seed to a secret identity key. #### Parameters - `seed` **([string][67] \| [Buffer][78])** 32-byte seed. Returns **[string][67]** Secret identity key. [1]: #server [2]: #factomserveridentitymanager [3]: #parameters [4]: #examples [5]: #addcoinbasecancel [6]: #parameters-1 [7]: #getserveridentity [8]: #parameters-2 [9]: #getserveridentityhistory [10]: #parameters-3 [11]: #updatecoinbaseaddress [12]: #parameters-4 [13]: #updateefficiency [14]: #parameters-5 [15]: #generatecoinbaseaddressupdateentry [16]: #parameters-6 [17]: #generatecoinbasecancelentry [18]: #parameters-7 [19]: #generateefficiencyupdateentry [20]: #parameters-8 [21]: #app [22]: #factomidentitymanager [23]: #parameters-9 [24]: #examples-1 [25]: #createidentity [26]: #parameters-10 [27]: #getactivepublicidentitykeys [28]: #parameters-11 [29]: #getidentityname [30]: #parameters-12 [31]: #isidentitykeyactive [32]: #parameters-13 [33]: #replaceidentitykey [34]: #parameters-14 [35]: #extractcryptomaterial [36]: #parameters-15 [37]: #factomwalletdkeystore [38]: #parameters-16 [39]: #examples-2 [40]: #generateidentitykey [41]: #parameters-17 [42]: #getallidentitykeys [43]: #getsecretidentitykey [44]: #parameters-18 [45]: #importidentitykeys [46]: #parameters-19 [47]: #removeidentitykeys [48]: #parameters-20 [49]: #generaterandomidentitykeypair [50]: #getpublicidentitykey [51]: #parameters-21 [52]: #isvalididentitykey [53]: #parameters-22 [54]: #isvalidpublicidentitykey [55]: #parameters-23 [56]: #isvalidsecretidentitykey [57]: #parameters-24 [58]: #keytopublicidentitykey [59]: #parameters-25 [60]: #seedtosecretidentitykey [61]: #parameters-26 [62]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/server/index.js#L6-L6 "Source code on GitHub" [63]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/server/factom-server-identity-manager.js#L27-L95 "Source code on GitHub" [64]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object [65]: https://factomjs.luciap.ca/#connectionoptions [66]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/server/factom-server-identity-manager.js#L85-L94 "Source code on GitHub" [67]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String [68]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number [69]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean [70]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/server/factom-server-identity-manager.js#L38-L40 "Source code on GitHub" [71]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array [72]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/server/factom-server-identity-manager.js#L48-L50 "Source code on GitHub" [73]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/server/factom-server-identity-manager.js#L60-L62 "Source code on GitHub" [74]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/server/factom-server-identity-manager.js#L72-L74 "Source code on GitHub" [75]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/server/coinbase-address.js#L115-L127 "Source code on GitHub" [76]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/server/coinbase-cancel.js#L54-L100 "Source code on GitHub" [77]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/server/efficiency.js#L105-L125 "Source code on GitHub" [78]: https://nodejs.org/api/buffer.html [79]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/app/index.js#L5-L5 "Source code on GitHub" [80]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/app/factom-identity-manager.js#L29-L112 "Source code on GitHub" [81]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function [82]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/app/factom-identity-manager.js#L87-L89 "Source code on GitHub" [83]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/app/factom-identity-manager.js#L43-L45 "Source code on GitHub" [84]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/app/factom-identity-manager.js#L52-L54 "Source code on GitHub" [85]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/app/factom-identity-manager.js#L65-L74 "Source code on GitHub" [86]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/app/factom-identity-manager.js#L103-L111 "Source code on GitHub" [87]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/app/key-helpers.js#L68-L73 "Source code on GitHub" [88]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/app/walletd-key-store.js#L19-L123 "Source code on GitHub" [89]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/app/walletd-key-store.js#L110-L122 "Source code on GitHub" [90]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/app/walletd-key-store.js#L98-L101 "Source code on GitHub" [91]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/app/walletd-key-store.js#L30-L40 "Source code on GitHub" [92]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/app/walletd-key-store.js#L48-L64 "Source code on GitHub" [93]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/app/walletd-key-store.js#L70-L91 "Source code on GitHub" [94]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/app/key-helpers.js#L129-L136 "Source code on GitHub" [95]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/app/key-helpers.js#L81-L91 "Source code on GitHub" [96]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/app/key-helpers.js#L16-L40 "Source code on GitHub" [97]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/app/key-helpers.js#L48-L50 "Source code on GitHub" [98]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/app/key-helpers.js#L58-L60 "Source code on GitHub" [99]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/app/key-helpers.js#L99-L101 "Source code on GitHub" [100]: https://github.com/PaulBernier/factom-identity/blob/2813d84d8a08a8762668c4f213c735a7f5e2ffef/src/app/key-helpers.js#L109-L111 "Source code on GitHub"