|
| 1 | + |
| 2 | +# cardano-wasm |
| 3 | + |
| 4 | +JavaScript bindings to the WASM build of [cardano-api](https://github.com/intersectmbo/cardano-api). You can find more information about the WASM build in the [cardano-wasm](https://github.com/IntersectMBO/cardano-api/tree/master/cardano-wasm) subfolder. |
| 5 | + |
| 6 | +This package provides functionalities to inspect, create, and manipulate transactions and other information related to Cardano blockchains, as well as interacting directly with them through the `cardano-node`. |
| 7 | + |
| 8 | +----- |
| 9 | + |
| 10 | +## 📦 Installation |
| 11 | + |
| 12 | +To install the package, run the following command in your project's directory: |
| 13 | + |
| 14 | +```bash |
| 15 | +npm install cardano-wasm |
| 16 | +``` |
| 17 | + |
| 18 | +----- |
| 19 | + |
| 20 | +## 🚀 Usage |
| 21 | + |
| 22 | +Because this library is a wrapper around a WebAssembly (WASM) module, you must first initialize it asynchronously. The dynamic `import()` function returns a promise that resolves to the module, and its `default` export is an `async` function that loads and prepares the API. |
| 23 | + |
| 24 | +Here is a clean, modern example using an `async` IIFE (Immediately Invoked Function Expression) to get you started. |
| 25 | + |
| 26 | +Create an `index.js` file: |
| 27 | + |
| 28 | +```javascript |
| 29 | +// A self-executing async function to initialize and use the Cardano API |
| 30 | +(async () => { |
| 31 | + try { |
| 32 | + // 1. Dynamically import the package. |
| 33 | + const cardanoModule = await import('cardano-wasm'); |
| 34 | + |
| 35 | + // 2. The module's default export is an async function that initializes the WASM instance. |
| 36 | + // Await this to get the usable API object. |
| 37 | + const api = await cardanoModule.default(); |
| 38 | + console.log("Cardano API loaded successfully!"); |
| 39 | + |
| 40 | + // 3. Now you can use the API to perform Cardano operations. |
| 41 | + // For example, let's create a new transaction body. |
| 42 | + const tx = await api.newTx(); |
| 43 | + console.log("New Transaction Body Created:", tx); |
| 44 | + |
| 45 | + // You can now build upon the 'tx' object to add inputs, outputs, etc. |
| 46 | + |
| 47 | + } catch (error) { |
| 48 | + console.error("Failed to load or use the Cardano API:", error); |
| 49 | + } |
| 50 | +})(); |
| 51 | +``` |
| 52 | + |
| 53 | +### Node.js |
| 54 | + |
| 55 | +To run this file, you can simply use Node.js: |
| 56 | + |
| 57 | +```bash |
| 58 | +node index.js |
| 59 | +``` |
| 60 | + |
| 61 | +### Webpack |
| 62 | + |
| 63 | +Alternatively you can use `cardano-wasm` as part of a `webpack` project, but you'll need to install `html-webpack-plugin` and `copy-webpack-plugin`: |
| 64 | + |
| 65 | +```bash |
| 66 | +npm install html-webpack-plugin copy-webpack-plugin |
| 67 | +``` |
| 68 | + |
| 69 | +And do a couple of adjustments to the `webpack.config.js`: |
| 70 | + |
| 71 | +```js |
| 72 | +const HtmlWebpackPlugin = require('html-webpack-plugin'); |
| 73 | +const CopyWebpackPlugin = require('copy-webpack-plugin'); |
| 74 | +const path = require('path'); |
| 75 | + |
| 76 | +module.exports = { |
| 77 | + entry: './src/index.js', |
| 78 | + |
| 79 | + target: ['web', 'es2020'], |
| 80 | + |
| 81 | + output: { |
| 82 | + filename: 'main.js', |
| 83 | + path: path.resolve(__dirname, 'dist'), |
| 84 | + publicPath: '', |
| 85 | + }, |
| 86 | + |
| 87 | + experiments: { |
| 88 | + asyncWebAssembly: true, |
| 89 | + }, |
| 90 | + |
| 91 | + devtool: 'source-map', |
| 92 | + |
| 93 | + plugins: [ |
| 94 | + new HtmlWebpackPlugin({ template: './index.html' }), |
| 95 | + new CopyWebpackPlugin({ |
| 96 | + patterns: [ |
| 97 | + { |
| 98 | + from: 'node_modules/cardano-wasm/dist/cardano-wasm.js', |
| 99 | + to: 'cardano-wasm.js', |
| 100 | + }, |
| 101 | + ], |
| 102 | + }), |
| 103 | + ], |
| 104 | + |
| 105 | + module: { |
| 106 | + rules: [ |
| 107 | + { |
| 108 | + test: /\.wasm$/, |
| 109 | + type: 'asset/resource', |
| 110 | + }, |
| 111 | + ], |
| 112 | + }, |
| 113 | + |
| 114 | + mode: 'development', |
| 115 | +}; |
| 116 | +``` |
| 117 | + |
| 118 | +Your `webpack.config.js` configuration may vary, but it could be necessary to adjust the `target`, `experiments`, `devtool`, `plugins`, and `module` keys as shown in the example above. |
| 119 | + |
| 120 | +----- |
| 121 | + |
| 122 | +## 📖 API Reference |
| 123 | + |
| 124 | +For a detailed understanding of all available functionalities, please refer to the official [**cardano-wasm documentation**](https://cardano-api.cardano.intersectmbo.org/cardano-wasm/typedoc/). |
| 125 | + |
| 126 | +----- |
| 127 | + |
| 128 | +## 🚗 Road map |
| 129 | + |
| 130 | +So far, `cardano-wasm` supports: |
| 131 | +- Basic wallet management. |
| 132 | +- Basic transaction building. |
| 133 | +- Transaction signing and submission through web-grpc. |
| 134 | +- Basic node communication through web-grpc. |
| 135 | + |
| 136 | +In the future, we aim to add support for: |
| 137 | +- Core wallet and staking features: |
| 138 | + - Extended wallet management (with mnemonics and stake addresses) |
| 139 | + - Staking and Delegation (certificates) |
| 140 | + - Multi-asset and metadata support |
| 141 | +- Native scripts and Plutus support |
| 142 | +- Governance: |
| 143 | + - DRep management |
| 144 | + - Voting |
| 145 | + - Constitution and committee management |
| 146 | +- Advanced transaction features |
| 147 | + - Validity interval |
| 148 | + - Reward withdrawals |
| 149 | + |
| 150 | +In parallel, we will be working on expanding the support for querying the node through gRPC and web-grpc. |
| 151 | + |
| 152 | +----- |
| 153 | + |
| 154 | +## 📄 License |
| 155 | + |
| 156 | +This project is licensed under **Apache-2.0 license**. |
0 commit comments