fix(generate): use Duff, not Dash... uhg 🤦‍♂️
[crowdnode.js/.git] / README.md
1 # CrowdNode Node.js SDK
2
3 CrowdNode allows you to become a partial MNO - staking Dash to earn interest,
4 participate in voting, etc.
5
6 The CrowdNode Node.js SDK enables you to build Web-based flows and
7 cross-platform CLI tools to privately manage staking using CrowdNode's KYC-free
8 Blockchain API.
9
10 # Install
11
12 ## Node.js
13
14 You must have [node.js](https://webinstall.dev/node) installed:
15
16 ### Mac & Linux
17
18 ```bash
19 curl https://webinstall.dev/node | bash
20 export PATH="${HOME}/.local/opt/node:$PATH"
21 ```
22
23 ### Windows
24
25 ```pwsh
26 curl.exe -A MS https://webinstall.dev/node | powershell
27 PATH %USERPROFILE%\.local\opt\node;%PATH%
28 ```
29
30 ## CrowdNode SDK
31
32 ```bash
33 npm install --save crowdnode@v1
34 ```
35
36 # API
37
38 The SDK also provides Type Hinting via JSDoc (compatible with TypeScript / tsc
39 without any transpiling).
40
41 ## IMPORTANT
42
43 The CLI is denominated in **Dash** and **Percent** because those are the units
44 most customers are familiar with and can easily calculate in their heads without
45 making "careless" mistakes.
46
47 HOWEVER, the SDK and CrowdNode API are denominated in **Duffs** (Satoshis) and
48 **Permil** (Permille) because those are the whole units that are easiest to
49 compute.
50
51 ## QuickStart
52
53 The CrowdNode SDK uses Dashcore to create raw transactions and broadcasts them
54 as Instant Send via the Dash Insight API. It uses Dash Insight WebSockets to
55 listen for responses from the CrowdNode hotwallet.
56
57 A simple CrowdNode application may look like this:
58
59 ```js
60 "use strict";
61
62 let Fs = require("fs").promises;
63 let CrowdNode = require("crowdnode");
64
65 async function main() {
66   let keyfile = process.argv[2];
67
68   // a wallet pre-loaded with about Đ0.01
69   let wif = await Fs.readFile(keyfile, "utf8");
70   wif = wif.trim();
71
72   // Initializes API info, such as hotwallets
73   await CrowdNode.init({ insightBaseUrl: "https://insight.dash.org/" });
74
75   let hotwallet = CrowdNode.main.hotwallet;
76   await CrowdNode.signup(wif, hotwallet);
77   await CrowdNode.accept(wif, hotwallet);
78   await CrowdNode.deposit(wif, hotwallet);
79
80   console.info("Congrats! You're staking!");
81 }
82
83 main().catch(function (err) {
84   console.error("Fail:");
85   console.error(err.stack || err);
86   process.exit(1);
87 });
88 ```
89
90 There are also a number of utility functions which are not exposed as public
91 APIs, but which you could learn from in [crowdnode-cli](/bin/crowdnode.js).
92
93 ## Constants
94
95 ```js
96 CrowdNode.offset = 20000;
97 CrowdNode.duffs = 100000000;
98 CrowdNode.depositMinimum = 10000;
99
100 CrowdNode.requests = {
101   acceptTerms: 65536,
102   offset: 20000,
103   signupForApi: 131072,
104   toggleInstantPayout: 4096,
105   withdrawMin: 1,
106   withdrawMax: 1000,
107 };
108
109 CrowdNode.responses = {
110   PleaseAcceptTerms: 2,
111   WelcomeToCrowdNodeBlockChainAPI: 4,
112   DepositReceived: 8,
113   WithdrawalQueued: 16,
114   WithdrawalFailed: 32,
115   AutoWithdrawalEnabled: 64,
116   AutoWithdrawalDisabled: 128,
117 };
118 ```
119
120 ## Usage
121
122 ### Manage Stake
123
124 ```js
125 await CrowdNode.init({ insightBaseUrl: "https://insight.dash.org" });
126
127 CrowdNode.main.baseUrl; // "https://app.crowdnode.io"
128 CrowdNode.main.hotwallet; // "XjbaGWaGnvEtuQAUoBgDxJWe8ZNv45upG2"
129
130 await CrowdNode.status(pubAddress, hotwallet);
131 /*
132  * {
133  *   signup: 0, // seconds since unix epoch
134  *   accept: 0,
135  *   deposit: 0,
136  * }
137  */
138
139 await CrowdNode.signup(wif, hotwallet);
140 /** @type SocketPayment
141  * {
142  *   "address": "Xj00000000000000000000000000000000",
143  *   "satoshis": 20002, // PleaseAcceptTerms
144  *   "timestamp": 1655634136000,
145  *   "txid": "xxxx...",
146  *   "txlock": true
147  * }
148  */
149
150 await CrowdNode.accept(wif, hotwallet);
151 /** @type SocketPayment
152  * {
153  *   "address": "Xj00000000000000000000000000000000",
154  *   "satoshis": 20004, // WelcomeToCrowdNodeBlockChainAPI
155  *   "timestamp": 1655634138000,
156  *   "txid": "xxxx...",
157  *   "txlock": true
158  * }
159  */
160
161 // amount given in DUFFs
162 await CrowdNode.deposit(wif, hotwallet, (amount = 0));
163 /** @type SocketPayment
164  * {
165  *   "address": "Xj00000000000000000000000000000000",
166  *   "satoshis": 20008, // DepositReceived
167  *   "timestamp": 1655634142000,
168  *   "txid": "xxxx...",
169  *   "txlock": true
170  * }
171  */
172
173 // permil is 1/10 percent, 500 permil = 50.0 percent
174 await CrowdNode.withdrawal(wif, hotwallet, permil);
175 /** @type SocketPayment
176  * {
177  *   "address": "Xj00000000000000000000000000000000",
178  *   "satoshis": 20016, // WithdrawalQueued
179  *   "timestamp": 1657634142000,
180  *   "txid": "xxxx...",
181  *   "txlock": true
182  * }
183  */
184 ```
185
186 ### HTTP RPC
187
188 ```js
189 await CrowdNode.http.GetBalance(pubAddr);
190 /** @type CrowdNodeBalance
191  * {
192  *   "DashAddress": "Xj00000000000000000000000000000000",
193  *   "TotalBalance": 0.01292824,
194  *   "TotalActiveBalance": 0,
195  *   "TotalDividend": 0,
196  *   "UpdatedOn": "2022-06-19T08:06:19.11",
197  *   "UpdateOnUnixTime": 1655625979
198  * }
199  */
200
201 await CrowdNode.http.GetFunds(pubAddr);
202 await CrowdNode.http.GetFundsFrom(pubAddr, secondsSinceEpoch);
203 /*
204  *  [
205  *    {
206  *      "FundingType": 1,
207  *      "Amount": 0.00810218,
208  *      "Time": 1655553336,
209  *      "TimeReceived": 1655553336,
210  *      "TxId": "e5a...",
211  *      "Status": 32,
212  *      "Comment": null,
213  *      "TimeUTC": "2022-06-18T11:55:36",
214  *      "Id": 3641556,
215  *      "UpdatedOn": "2022-06-18T12:04:15.1233333"
216  *    }
217  *  ]
218  */
219
220 await CrowdNode.http.IsAddressInUse(pubAddr);
221 /**
222  * {
223  *   "inUse": true,
224  *   "DashAddress": "Xj00000000000000000000000000000000"
225  * }
226  */
227 ```
228
229 ### Messages (Voting, etc)
230
231 ```js
232 await CrowdNode.http.GetMessages(pubAddr);
233 /**
234  * []
235  */
236
237 await CrowdNode.http.SetEmail(wif, email, sig);
238 await CrowdNode.http.Vote(wif, gobjectHash, vote, sig);
239 await CrowdNode.http.SetReferral(wif, referralId, sig);
240 ```
241
242 ```js
243 await CrowdNode.http.FundsOpen(pub);
244 /* ${baseUrl}/FundsOpen/${pub} */
245
246 await CrowdNode.http.VotingOpen(pub);
247 /* ${baseUrl}/VotingOpen/${pub} */
248 ```
249
250 ## Glossary
251
252 | Term          | Description                                                   |
253 | ------------- | ------------------------------------------------------------- |
254 | addr          | your Dash address (Base58Check-encoded Pay-to-PubKey Address) |
255 | amount        | the integer value of "Duffs" (Đ/100000000)                    |
256 | permil        | 1/1000, 1‰, or 0.1% - between 1 and 1000 (0.1% to 100.0%)     |
257 | ./privkey.wif | the file path to your staking key in WIF (Base58Check) format |
258
259 # CLI Documentation
260
261 See <https://github.com/dashhive/crowdnode.js/tree/main/cli>.
262
263 # Official CrowdNode Docs
264
265 <https://knowledge.crowdnode.io/en/articles/5963880-blockchain-api-guide>