This repository has been archived by the owner on May 8, 2023. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 41
/
docs_md
312 lines (181 loc) · 12 KB
/
docs_md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
### Table of Contents
* [Welcome][1]
* [Minting using our token contracts][2]
* [mintLIT][3]
* [Parameters][4]
* [LIT Node Client][5]
* [LitNodeClient][6]
* [Parameters][7]
* [getEncryptionKey][8]
* [Parameters][9]
* [saveEncryptionKey][10]
* [Parameters][11]
* [Creating the LIT HTML][12]
* [createHtmlLIT][13]
* [Parameters][14]
* [toggleLock][15]
* [Encryption and decryption utilities][16]
* [zipAndEncryptString][17]
* [Parameters][18]
* [zipAndEncryptFiles][19]
* [Parameters][20]
* [encryptZip][21]
* [Parameters][22]
* [decryptZip][23]
* [Parameters][24]
* [Utilities][25]
* [fileToDataUrl][26]
* [Parameters][27]
* [checkAndSignAuthMessage][28]
* [Types][29]
* [AuthSig][30]
* [Properties][31]
* [LITChain][32]
* [Properties][33]
* [LIT_CHAINS][34]
## Welcome
Welcome to the LIT JS SDK API documentation. To understand how these functions fit together, please view the README in the github repo for this SDK.
## Minting using our token contracts
You may use our pre-deployed token contracts to mint your LIT, or you may supply your own. Our contracts are ERC1155 tokens on Polygon and Ethereum. Using these contracts is the easiest way to get started.
## mintLIT
Mint a LIT using our ERC1155 contract.
### Parameters
* `params` **[Object][35]**
* `params.chain` **[string][36]** The chain to mint on. "ethereum" and "polygon" are currently supported.
* `params.quantity` **[number][37]** The number of tokens to mint. Note that these will be fungible, so they will not have serial numbers.
Returns **[Object][35]** The txHash, tokenId, tokenAddress, mintingAddress, and authSig.
## LIT Node Client
A client that connects directly to the LIT nodes to store and retrieve encryption keys for LITs. Only holders of an NFT that corresponds with a LIT may store and retrieve the keys.
## LitNodeClient
A LIT node client. Connects directly to the LIT nodes to store and retrieve encryption keys.
### Parameters
* `config` **[Object][35]** (optional, default `{alertWhenUnauthorized:true,minNodeCount:8}`)
* `config.alertWhenUnauthorized` **[boolean][38]** Whether or not to show a JS alert() when a user tries to unlock a LIT but is unauthorized. If you turn this off, you should create an event listener for the "lit-authFailure" event on the document, and show your own error to the user. (optional, default `true`)
* `config.minNodeCount` **[number][37]** The minimum number of nodes that must be connected for the LitNodeClient to be ready to use. (optional, default `8`)
### getEncryptionKey
Retrieve the symmetric encryption key from the LIT nodes. Note that this will only work if the current user is a holder of the NFT that corresponds to this LIT. This NFT token address and ID was specified when this LIT was created.
#### Parameters
* `params` **[Object][35]**
* `params.tokenAddress` **[string][36]** The token address of the NFT that corresponds to this LIT. This should be an ERC721 or ERC1155 token.
* `params.tokenId` **[string][36]** The token ID of the NFT that corresponds to this LIT
* `params.chain` **[string][36]** The chain that the corresponding NFT lives on. Currently "polygon" and "ethereum" are supported.
* `params.authSig` **[AuthSig][39]** The authentication signature that proves that the user owns the crypto wallet address that should be an owner of the NFT that corresponds to this LIT.
Returns **[Object][35]** The symmetric encryption key that can be used to decrypt the locked content inside the LIT. You should pass this key to the decryptZip function.
### saveEncryptionKey
Securely save the symmetric encryption key to the LIT nodes.
#### Parameters
* `params` **[Object][35]**
* `params.tokenAddress` **[string][36]** The token address of the NFT that corresponds to this LIT. This should be an ERC721 or ERC1155 token.
* `params.tokenId` **[string][36]** The token ID of the NFT that corresponds to this LIT
* `params.chain` **[string][36]** The chain that the corresponding NFT lives on. Currently "polygon" and "ethereum" are supported.
* `params.authSig` **[AuthSig][39]** The authentication signature that proves that the user owns the crypto wallet address that should be an owner of the NFT that corresponds to this LIT.
* `params.symmetricKey` **[string][36]** The symmetric encryption key that was used to encrypt the locked content inside the LIT. You should use zipAndEncryptString or zipAndEncryptFiles to get this encryption key. This key will be split up using threshold encryption so that the LIT nodes cannot decrypt a given LIT.
Returns **[Object][35]** An object that gives the status of the operation, denoted via a boolean with the key "success"
## Creating the LIT HTML
Creates a barebones HTML LIT with built in unlock functionality. You need to design your LIT with HTML and CSS, and provide an unlock button with the id "unlockButton" inside your HTML.
## createHtmlLIT
Create a ready-to-go LIT using provided HTML/CSS body and an encrypted zip data url
### Parameters
* `params` **[Object][35]**
* `params.title` **[string][36]** The title that will be used for the title tag in the outputted HTML
* `params.htmlBody` **[number][37]** The HTML body for the locked state of the LIT. All users will be able to see this HTML. This HTML must have a button with an id of "unlockButton" which will be automatically set up to decrypt and load the encryptedZipDataUrl
* `params.css` **[string][36]** Any CSS you would like to include in the outputted HTML
* `params.encryptedZipDataUrl` **[number][37]** a data URL of the encrypted zip that contains the locked content that only token holders will be able to view.
* `params.tokenAddress` **[string][36]** The token address of the corresponding NFT for this LIT. ERC721 and ERC 1155 tokens are currently supported.
* `params.tokenId` **[number][37]** The ID of the token of the corresponding NFT for this LIT. Only holders of this token ID will be able to unlock and decrypt this LIT.
* `params.chain` **[string][36]** The chain that the corresponding NFT was minted on. "ethereum" and "polygon" are currently supported.
* `params.npmPackages` **[Array][40]** An array of strings of NPM package names that should be embedded into this LIT. These packages will be pulled down via unpkg, converted to data URLs, and embedded in the LIT HTML. You can include any packages from npmjs.com. (optional, default `[]`)
Returns **[string][36]** The HTML string that is now a LIT. You can send this HTML around and only token holders will be able to unlock and decrypt the content inside it. Included in the HTML is this LIT JS SDK itself, the encrypted locked content, an automatic connection to the LIT nodes network, and a handler for a button with id "unlockButton" which will perform the unlock operation when clicked.
## toggleLock
Lock and unlock the encrypted content inside a LIT. This content is only viewable by holders of the NFT that corresponds to this LIT. Locked content will be decrypted and placed into the HTML element with id "mediaGridHolder". The HTML element with the id "lockedHeader" will have it's text automatically changed to LOCKED or UNLOCKED to denote the state of the LIT. Note that if you're creating a LIT using the createHtmlLIT function, you do not need to use this function, because this function is automatically bound to any button in your HTML with the id "unlockButton".
## Encryption and decryption utilities
## zipAndEncryptString
Zip and encrypt a string. This is used to encrypt any string that is to be locked and included in a LIT. For example, on MintLIT, we render the HTML/CSS containing the locked files and a grid to view them to a string using ReactDOMServer.renderToString().
### Parameters
* `string` **[string][36]** The string to zip and encrypt
Returns **[Object][35]** The encryptedZip as a Blob and the symmetricKey used to encrypt it, as a JSON string. The encrypted zip will contain a single file called "string.txt"
## zipAndEncryptFiles
Zip and encrypt multiple files.
### Parameters
* `files` **[array][40]** An array of the files you wish to zip and encrypt
Returns **[Object][35]** The encryptedZip as a Blob and the symmetricKey used to encrypt it, as a JSON string. The encrypted zip will contain a folder "encryptedAssets" and all of the files will be inside it.
## encryptZip
Encrypt a zip file created with JSZip using a new random symmetric key via WebCrypto.
### Parameters
* `zip` **JSZip** The JSZip instance to encrypt
Returns **[Object][35]** The encryptedZip as a Blob and the symmetricKey used to encrypt it, as a JSON string.
## decryptZip
Decrypt and unzip a zip that was created using encryptZip, zipAndEncryptString, or zipAndEncryptFiles.
### Parameters
* `encryptedZipBlob` **[Blob][41]** The encrypted zip as a Blob
* `symmKey` **[Object][35]** An object containing the symmetric key used that will be used to decrypt this zip.
Returns **[Array][40]** An array of the decrypted files inside the zip.
## Utilities
## fileToDataUrl
Convert a file to a data URL, which could then be embedded in a LIT. A data URL is a string representation of a file.
### Parameters
* `file` **File** The file to turn into a data url
Returns **[string][36]** The data URL. This is a string representation that can be used anywhere the original file would be used.
## checkAndSignAuthMessage
Check for an existing cryptographic authentication signature and create one of it does not exist. This is used to prove ownership of a given crypto wallet address to the LIT nodes. The result is stored in LocalStorage so the user doesn't have to sign every time they perform an operation.
Returns **[AuthSig][39]** The AuthSig created or retrieved
## Types
## AuthSig
Type: [Object][35]
### Properties
* `sig` **[string][36]** The actual hex-encoded signature
* `derivedVia` **[string][36]** The method used to derive the signature
* `signedMessage` **[string][36]** The message that was signed
* `address` **[string][36]** The crypto wallet address that signed the message
## LITChain
Type: [Object][35]
### Properties
* `contractAddress` **[string][36]** The address of the token contract
* `chainId` **[string][36]** The chain ID of the chain that this token contract is deployed on. Used for EVM chains.
* `name` **[string][36]** The human readable name of the chain
## LIT_CHAINS
Pre-deployed token contracts that you may use for minting LITs. These are ERC1155 contracts that let you mint any quantity of a given token. Use the chain name as a key in this object. Currently "polygon" and "ethereum" are supported.
Type: [LITChain][42]
[1]: #welcome
[2]: #minting-using-our-token-contracts
[3]: #mintlit
[4]: #parameters
[5]: #lit-node-client
[6]: #litnodeclient
[7]: #parameters-1
[8]: #getencryptionkey
[9]: #parameters-2
[10]: #saveencryptionkey
[11]: #parameters-3
[12]: #creating-the-lit-html
[13]: #createhtmllit
[14]: #parameters-4
[15]: #togglelock
[16]: #encryption-and-decryption-utilities
[17]: #zipandencryptstring
[18]: #parameters-5
[19]: #zipandencryptfiles
[20]: #parameters-6
[21]: #encryptzip
[22]: #parameters-7
[23]: #decryptzip
[24]: #parameters-8
[25]: #utilities
[26]: #filetodataurl
[27]: #parameters-9
[28]: #checkandsignauthmessage
[29]: #types
[30]: #authsig
[31]: #properties
[32]: #litchain
[33]: #properties-1
[34]: #lit_chains
[35]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
[36]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
[37]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
[38]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
[39]: #authsig
[40]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
[41]: https://developer.mozilla.org/docs/Web/API/Blob
[42]: #litchain