|
1 | | -## ElvenJS |
| 1 | +## Elven monorepo |
2 | 2 |
|
3 | | -### One static file to rule it all on the MultiversX blockchain! |
| 3 | +TODO link other readmes |
4 | 4 |
|
5 | | -## Docs |
6 | | -- [www.elvenjs.com](https://www.elvenjs.com) |
| 5 | +## Development |
7 | 6 |
|
8 | | -## Videos |
9 | | -- [JavaScript browser SDK for MultiversX Blockchain](https://youtu.be/tcTukpkjcQw) |
| 7 | +### HTTPS Local Development |
10 | 8 |
|
11 | | -## Demos |
12 | | -- [elvenjs.netlify.app](https://elvenjs.netlify.app/) - EGLD, ESDT transactions, smart contract queries and transactions |
13 | | -- [elrond-donate-widget-demo.netlify.app](https://multiversx-donate-widget-demo.netlify.app/) - donation-like widget demo |
14 | | -- [StackBlitz vanilla html demo](https://stackblitz.com/edit/web-platform-d4rx5v?file=index.html) |
15 | | -- [StackBlitz Solid.js demo](https://stackblitz.com/edit/vitejs-vite-rbo6du?file=src/App.tsx) |
16 | | -- [StackBlitz React demo](https://stackblitz.com/edit/vitejs-vite-qr2u7l?file=src/App.tsx) |
17 | | -- [StackBlitz Vue demo](https://stackblitz.com/edit/vue-zrb8y5?file=src/App.vue) |
| 9 | +The development server runs on HTTPS for secure local development. When you run `npm run dev:server`, the setup script will automatically: |
18 | 10 |
|
19 | | -Authenticate, sign and send transactions on the MultiversX blockchain in the browser. No need for bundlers, frameworks, etc. Just attach the script source, and you are ready to go. You can incorporate it into your preferred CMS framework like WordPress or an e-commerce system. Plus, it will also work on a standard static HTML website. |
| 11 | +1. Check if development SSL certificates exist |
| 12 | +2. Generate new self-signed certificates if needed |
| 13 | +3. Start the HTTPS development server |
20 | 14 |
|
21 | | -The primary purpose of this tool is to have a lite script for browser usage where you can authenticate and sign/send transactions on the MultiversX blockchain and do this without any additional build steps. |
| 15 | +The first time you access the development server in your browser, you'll see a security warning because we're using self-signed certificates. This is normal for local development, and you can safely proceed by accepting the certificate warning. |
22 | 16 |
|
23 | | -The purpose is to simplify the usage for primary use cases and open the doors for many frontend tools and approaches. |
24 | | - |
25 | | -It is a script for browsers incorporates ES6 modules. If you need fully functional JavaScript/Typescript SDK (also in Nodejs), please use [sdk-js](https://docs.multiversx.com/sdk-and-tools/sdk-js/), an official Typescript MultiversX SDK. And if you are React developer, please check the [Nextjs dapp](https://github.com/xdevguild/nextjs-dapp-template). |
26 | | - |
27 | | -**You can use it already, but it is under active development, and the API might change, there could be breaking changes without changing major versions.** |
28 | | - |
29 | | -### How to use it |
30 | | - |
31 | | -Copy and include the `elven.js` script from the `build` directory or the best would be to use CDN (https://unpkg.com/elven.js/build/elven.js). Please don't link the script using the [demo](https://elvenjs.netlify.app/) domain. |
32 | | - |
33 | | -Use module type, like: |
34 | | - |
35 | | -```html |
36 | | -<script type="module"> |
37 | | - import { |
38 | | - ElvenJS, |
39 | | - Transaction, |
40 | | - Address, |
41 | | - TransactionPayload, |
42 | | - TokenTransfer, |
43 | | - ContractFunction, |
44 | | - U32Value, |
45 | | - } from './elven.js'; |
46 | | -
|
47 | | - // Your code here |
48 | | -</script> |
49 | | -``` |
50 | | -or from CDN: |
51 | | - |
52 | | -```html |
53 | | -<script type="module"> |
54 | | - import { |
55 | | - ElvenJS, |
56 | | - Transaction, |
57 | | - Address, |
58 | | - TransactionPayload, |
59 | | - TokenTransfer, |
60 | | - ContractFunction, |
61 | | - U32Value, |
62 | | - } from 'https://unpkg.com/elven.js@<actual_version_here>/build/elven.js'; |
63 | | -
|
64 | | - // Your code here |
65 | | -</script> |
66 | | -``` |
67 | | - |
68 | | -### SDK reference |
69 | | - |
70 | | -Please check the docs here: [www.elvenjs.com/docs/sdk-reference.html](https://www.elvenjs.com/docs/sdk-reference.html) |
71 | | - |
72 | | -### Recipes |
73 | | - |
74 | | -Please check how to use it with a couple of recipes here: [www.elvenjs.com/docs/recipes.html](https://www.elvenjs.com/docs/recipes.html) |
75 | | - |
76 | | -Check for more complete examples in the [example/index.html](/example/index.html) |
77 | | - |
78 | | -### Usage example with static website (base demo): |
79 | | - |
80 | | -Check out the example file: [example/index.html](/example/index.html) |
81 | | - |
82 | | -You will find the whole demo there. The same is deployed here: [elvenjs.netlify.app](https://elvenjs.netlify.app) |
83 | | - |
84 | | -### Usage in frontend frameworks |
85 | | - |
86 | | -Elven.js can also be used in many different frameworks by importing it from node_modules (of course, it is a client-side library). When it comes to React/Nextjs, it is advised to use one of the ready templates, for example, the one mentioned above. But Elven.js can be helpful in other frameworks where there are no templates yet. Example: |
87 | | - |
88 | | -```bash |
89 | | -npm install elven.js |
90 | | -``` |
91 | | -and then in your client side framework: |
92 | | -```typescript |
93 | | -import { ElvenJS } from 'elven.js'; |
94 | | -``` |
95 | | - |
96 | | -The types should also be exported. |
97 | | - |
98 | | -### What can it do? |
99 | | - |
100 | | -The API is limited for now, this will change, but even now, it can do most of the core operations: |
101 | | - |
102 | | -- authenticate using the xPortal mobile, MultiversX browser extension, MultiversX Web Wallet and xAlias |
103 | | -- integrate with xPortal Hub |
104 | | -- handle expiration of the auth state |
105 | | -- handle login with tokens to be able to get the signature |
106 | | -- sign transactions |
107 | | -- send transactions (also custom smart contracts) |
108 | | -- sign custom messages |
109 | | -- basic global states handling (local storage) |
110 | | -- basic structures for transaction payload |
111 | | -- sync the network on page load |
112 | | -- querying the smart contracts (without tools for result parsing yet) |
113 | | -- support for guarded transactions using MultiversX 2FA solutions |
114 | | - |
115 | | -### What will it do soon? (TODO): |
116 | | - |
117 | | -- authenticate with Ledger Nano |
118 | | -- result parsing (separate library) |
119 | | -- more advanced global state handling and (real-time updates (if needed)?) |
120 | | -- more structures and simplification for payload builders |
121 | | -- split it into more files/libraries |
122 | | -- make it as small as possible |
123 | | - |
124 | | -### What it won't probably do: |
125 | | - |
126 | | -- crypto tasks |
127 | | -- results parsing (but it will land in a separate package) |
128 | | - |
129 | | -Why? Because it is supposed to be a browser script, it should be as small as possible. All that functionality can be replaced if needed by a custom implementation or other libraries. There will be docs with examples for that. And in the future, there may be more similar libraries, but optional and separated. |
130 | | - |
131 | | -### Development |
132 | | - |
133 | | -1. clone the repo |
134 | | -2. `npm install` dependencies |
135 | | -3. `npm run build` |
136 | | -4. test on example -> `npm run dev:server` |
137 | | -5. rebuild with every change in the script |
138 | | - |
139 | | -To test the MultiversX browser extension you would need to run localhost with SSL. |
140 | | -For quick dev testing tools like [localhost.run](https://localhost.run/) should be enough. |
141 | | -After you run `npm run dev:server`, in separate teriminal window run `ssh -R 80:localhost:3000 localhost.run`. You can also relay on your own SSL setup. |
142 | | - |
143 | | -### Articles |
144 | | - |
145 | | -- [How to Interact With the MultiversX Blockchain in a Simple Static Website](https://hackernoon.com/how-to-interact-with-the-elrond-blockchain-in-a-simple-static-website) |
146 | | -- [How to enable donations on any website using the MultiversX blockchain and EGLD tokens](https://dev.to/juliancwirko/how-to-enable-donations-on-any-website-using-the-elrond-blockchain-and-egld-tokens-3fkf) |
147 | | - |
148 | | -### TODO |
149 | | -- [Kanban board](https://github.com/elven-js/projects/1) |
150 | | - |
151 | | -### Other tools |
152 | | - |
153 | | -If you need to use MultiversX SDK with React-based projects, you can try these tools: |
154 | | - |
155 | | -- [sdk-dapp](https://github.com/multiversx/mx-sdk-dapp) - for standard React-based SPA |
156 | | -- [nextjs-dapp-template](https://github.com/xdevguild/nextjs-dapp-template) - or Nextjs apps |
157 | | -- [useElven](https://www.useelven.com) - React Hooks for interacting with MultiversX blockchain |
158 | | - |
159 | | -If you are interested in creating and managing your own PFP NFT collection, you might be interested in: |
160 | | - |
161 | | -- [Elven Tools](https://www.elven.tools) - What is included: NFT minter smart contract (decentralized way of minting), minter Nextjs dapp (interaction on the frontend side), CLI tool (deploy, configuration, interaction) |
162 | | -- [nft-art-maker](https://github.com/juliancwirko/nft-art-maker) - tool for creating png assets from provided layers. It can also pack files and upload them to IPFS using nft.storage. All CIDs will be auto-updated |
163 | | - |
164 | | -Other tools: |
165 | | - |
166 | | -- [Buildo Begins](https://github.com/xdevguild/buildo-begins) - all MultiversX blockchain CLI interactions with sdk-js, still in progress, but usable |
167 | | -- [Buildo.dev](https://www.buildo.dev) - Buildo.dev is a MultiversX app that helps with blockchain interactions, like issuing tokens and querying smart contracts. |
| 17 | +The development server will be available at `https://localhost:3000` (or your specified PORT). |
0 commit comments