{ "name": "luxfi", "versions": { "3.15.5": { "name": "luxfi", "version": "3.15.5", "description": "Lux Network JS Library", "main": "dist/index.js", "scripts": { "build": "rm -rf dist/ && npx tsc -b && cp -r typings/src ./dist", "prebundle": "yarn build", "bundle": "webpack --mode production", "lint": "eslint ./ --ext js,ts --fix", "prepublish": "yarn build", "release:prepare": "rm -rf ./dist ./node_modules && yarn install && yarn build && yarn bundle && yarn test && git status", "test": "jest", "test-watch": "jest --watch", "docshtml": "npx typedoc --plugin typedoc-plugin-external-module-name --mode file src", "docsmd": "rm -rf docsMD && yarn build && npx typedoc --readme none --plugin typedoc-plugin-markdown,typedoc-plugin-external-module-name --theme markdown --out docsMD src", "docs": "yarn docshtml && yarn docsmd", "prettier-src": "prettier --write ./src", "prettier-examples": "prettier --write ./examples", "prettier-tests": "prettier --write ./tests", "prettier-web": "prettier --write ./web", "prettier-mocks": "prettier --write ./__mocks__", "prettier": "yarn prettier-src && yarn prettier-examples && yarn prettier-tests && yarn prettier-web && yarn prettier-mocks" }, "repository": { "type": "git", "url": "git+https://github.com/luxfi/luxjs.git" }, "keywords": [ "lux", "blockchain", "defi" ], "author": { "name": "Lux Partners Limited", "email": "devs@lux.network" }, "license": "BSD-3-Clause", "bugs": { "url": "https://github.com/luxfi/luxjs/issues" }, "homepage": "https://github.com/luxfi/luxjs#readme", "devDependencies": { "@types/bech32": "1.1.4", "@types/bn.js": "5.1.1", "@types/create-hash": "1.2.2", "@types/hdkey": "2.0.1", "@types/jest": "27.5.0", "@types/node": "16.11.12", "@typescript-eslint/eslint-plugin": "6.17.0", "@typescript-eslint/parser": "6.17.0", "clean-webpack-plugin": "4.0.0", "eslint": "8.56.0", "eslint-config-prettier": "9.1.0", "eslint-plugin-prettier": "5.1.2", "eslint-plugin-security": "1.5.0", "git-revision-webpack-plugin": "5.0.0", "html-webpack-plugin": "5.5.0", "jest": "29.7.0", "jest-mock-axios": "4.7.3", "prettier": "3.1.1", "terser-webpack-plugin": "5.3.6", "ts-jest": "29.1.1", "ts-loader": "9.5.1", "typedoc": "^0.18.0", "typedoc-plugin-external-module-name": "^4.0.3", "typedoc-plugin-markdown": "^2.4.0", "typescript": "5.3.3", "webpack": "5.74.0", "webpack-cli": "4.10.0" }, "engines": { "node": ">=14.0.0" }, "dependencies": { "assert": "2.0.0", "axios": "0.27.2", "bech32": "2.0.0", "bip39": "3.0.4", "bn.js": "5.2.1", "buffer": "6.0.3", "create-hash": "1.2.0", "crypto-browserify": "3.12.0", "elliptic": "6.5.4", "ethers": "5.7.2", "hdkey": "2.0.1", "isomorphic-ws": "5.0.0", "randombytes": "^2.1.0", "store2": "2.14.2", "stream-browserify": "3.0.0", "ws": "8.8.1", "xss": "1.0.14" }, "prettier": { "tabWidth": 2, "useTabs": false, "semi": false, "singleQuote": false, "jsxBracketSameLine": false, "trailingComma": "none" }, "_id": "luxfi@3.15.5", "gitHead": "4272af1ce02bb5a19c82d32c2584132c01b8eaaf", "types": "./dist/index.d.ts", "_nodeVersion": "18.19.0", "_npmVersion": "10.2.3", "dist": { "integrity": "sha512-mnvdcTPvHcPXucLZNZ8zj27jWaEzOIbw/GEx5K3OPb4JhTYxR0kFLZ0OJklTVkNx6ghMHTUpjrw+aLrJD/9RAw==", "shasum": "501d59d799b41f453e20d546daad4cb677cb731a", "tarball": "https://pkg.hanzo.ai/luxfi/-/luxfi-3.15.5.tgz", "fileCount": 1285, "unpackedSize": 11623392, "signatures": [ { "keyid": "SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA", "sig": "MEUCIHDQpC9YMjyQL4Z+wODpE40oc2bl5HxghQfFo1Y8Gw4CAiEAwT26yzr9vEBAcwoEZQoPgcDAGHj0AcX7xtfHS3Zj0HI=" } ] }, "_npmUser": { "name": "zeekay", "email": "z@zeekay.ai" }, "directories": {}, "maintainers": [ { "name": "zeekay", "email": "z@zeekay.ai" } ], "_npmOperationalInternal": { "host": "s3://npm-registry-packages", "tmp": "tmp/luxfi_3.15.5_1716316498028_0.5951345126104202" }, "_hasShrinkwrap": false, "contributors": [] } }, "time": { "created": "2024-05-21T18:34:58.027Z", "3.15.5": "2024-05-21T18:34:58.364Z", "modified": "2024-05-21T18:34:58.659Z" }, "users": {}, "dist-tags": { "latest": "3.15.5" }, "_rev": "16-7016643ec3267c18", "_id": "luxfi", "readme": "# LuxJS - The Lux Network JavaScript Library\n\n## Overview\n\nLuxJS is a JavaScript Library for interfacing with the Lux Platform. It is built using TypeScript and intended to support both browser and Node.js. The LuxJS library allows you to issue commands to the Lux node APIs.\n\nThe APIs currently supported by default are:\n\n* Admin API\n* Auth API\n* XVM API (X-Chain)\n* EVM API (C-Chain)\n* Health API\n* Index API\n* Info API\n* Keystore API\n* Metrics API\n* PlatformVM API (P-Chain)\n* Socket\n\nWe built LuxJS with ease of use in mind. With this library, any Javascript developer is able to interact with a node on the Lux Platform who has enabled their API endpoints for the developer's consumption. We keep the library up-to-date with the latest changes in the [Lux Platform Specification](https://docs.lux.network).\n\n Using LuxJS, developers can:\n\n* Locally manage private keys\n* Retrieve balances on addresses\n* Get UTXOs for addresses\n* Build and sign transactions\n* Issue signed transactions to the X-Chain, P-Chain, and C-Chain\n* Perform cross-chain swaps between the X-Chain<->P-Chain and between the X-Chain<->C-Chain\n* Add Validators and Delegators to the Primary Subnetwork by staking LUX\n* Create a Subnetwork\n* Administer a local node\n* Retrieve Lux network information from a node\n\n### Requirements\n\nLuxJS requires Node.js LTS version 14.16.0 or higher to compile.\n\n### Installation\n\nLux is available for install via `yarn`:\n\n`yarn add lux`\n\nYou can also pull the repo down directly and build it from scratch:\n\n`yarn build`\n\nThis will generate a pure Javascript library and place it in a folder named \"web\" in the project root. The \"lux.js\" file can then be dropped into any project as a pure javascript implementation of Lux.\n\nThe LuxJS library can be imported into your existing Node.js project as follows:\n\n```js\nconst lux = require(\"luxnet\")\n```\n\nOr into your TypeScript project like this:\n\n```js\nimport { Lux } from \"luxnet\"\n```\n\n### Importing essentials\n\n```js\nimport { Lux, BinTools, BN, Buffer } from \"luxnet\"\n\nconst bintools = BinTools.getInstance()\n```\n\nThe above lines import the libraries used in the tutorials. The libraries include:\n\n* Lux: Our javascript module.\n* BinTools: A singleton built into LuxJS that is used for dealing with binary data.\n* [BN](https://www.npmjs.com/package/bn.js): A bignumber module use by LuxJS.\n* [Buffer](https://www.npmjs.com/package/buffer): A Buffer library.\n\n## Example 1 — Managing X-Chain Keys\n\nLuxJS comes with its own XVM Keychain. This KeyChain is used in the functions of the API, enabling them to sign using keys it's registered. The first step in this process is to create an instance of LuxJS connected to our Lux Platform endpoint of choice.\n\n```js\nimport { Lux, BinTools, Buffer, BN } from \"luxnet\"\n\nconst bintools = BinTools.getInstance()\n\nconst myNetworkID = 12345 //default is 1, we want to override that for our local network\nconst lux = new Lux(\"localhost\", 9650, \"http\", myNetworkID)\nconst xchain = lux.XChain() //returns a reference to the X-Chain used by LuxJS\n```\n\n### Accessing the KeyChain\n\nThe KeyChain is accessed through the X-Chain and can be referenced directly or through a reference variable.\n\n```js\nconst myKeychain = xchain.keyChain()\n```\n\nThis exposes the instance of the class XVMKeyChain which is created when the X-Chain API is created. At present, this supports secp256k1 curve for ECDSA key pairs.\n\n### Creating X-Chain key pairs\n\nThe KeyChain has the ability to create new KeyPairs for you and return the address associated with the key pair.\n\n```js\nconst newAddress1 = myKeychain.makeKey() // returns an instance of the KeyPair class\n```\n\nYou may also import your existing private key into the KeyChain using either a Buffer...\n\n```js\nconst mypk = bintools.cb58Decode(\n \"JaCCSxdoWfo3ao5KwenXrJjJR7cBTQ287G1C5qpv2hr2tCCdb\"\n) // returns a Buffer\nconst newAddress2 = myKeychain.importKey(mypk) // returns an instance of the KeyPair class\n```\n\n... or an CB58 string works, too:\n\n```js\nconst mypk = \"PrivateKey-JaCCSxdoWfo3ao5KwenXrJjJR7cBTQ287G1C5qpv2hr2tCCdb\"\nconst newAddress2 = myKeychain.importKey(mypk) // returns an instance of the KeyPair class\n```\n\n### Working with KeyChains\n\nThe X-Chains's KeyChain has standardized key management capabilities. The following functions are available on any KeyChain that implements this interface.\n\n```js\nconst addresses = myKeychain.getAddresses() // returns an array of Buffers for the addresses\nconst addressStrings = myKeychain.getAddressStrings() // returns an array of strings for the addresses\nconst exists = myKeychain.hasKey(addresses[0]) // returns true if the address is managed\nconst keypair = myKeychain.getKey(addresses[0]) // returns the KeyPair class\n```\n\n### Working with KeyPairs\n\nThe X-Chain's KeyPair has standardized KeyPair functionality. The following operations are available on any KeyPair that implements this interface.\n\n```js\nconst address = keypair.getAddress() // returns Buffer\nconst addressString = keypair.getAddressString() // returns string\n\nconst pubk = keypair.getPublicKey() // returns Buffer\nconst pubkstr = keypair.getPublicKeyString() // returns a CB58 encoded string\n\nconst privk = keypair.getPrivateKey() //returns Buffer\nconst privkstr = keypair.getPrivateKeyString() //returns a CB58 encoded string\n\nkeypair.generateKey() // creates a new random KeyPair\n\nconst mypk = bintools.cb58Decode(\n \"24jUJ9vZexUM6expyMcT48LBx27k1m7xpraoV62oSQAHdziao5\"\n)\nconst successful = keypair.importKey(mypk) // returns boolean if private key imported successfully\n\nconst message = Buffer.from(\"Through consensus to the stars\")\nconst signature = keypair.sign(message) // returns a Buffer with the signature\n\nconst signerPubk = keypair.recover(message, signature) // returns a Buffer\nconst isValid = keypair.verify(message, signature) // returns a boolean\n```\n\n## Example 2 — Creating An Asset\n\nThis example creates an asset in the X-Chain and publishes it to the Lux Platform. The first step in this process is to create an instance of LuxJS connected to our Lux Platform endpoint of choice.\n\n```js\nimport { Lux, BinTools, Buffer, BN } from \"luxnet\"\nimport { InitialStates, SECPTransferOutput } from \"luxnet/dist/apis/xvm\"\n\nconst myNetworkID = 12345 // default is 1, we want to override that for our local network\nconst lux = new Lux(\"localhost\", 9650, \"http\", myNetworkID)\nconst xchain = lux.XChain() // returns a reference to the X-Chain used by LuxJS\n```\n\n### Describe the new asset\n\nThe first steps in creating a new asset using LuxJS is to determine the qualities of the asset. We will give the asset a name, a ticker symbol, as well as a denomination.\n\n```js\n// Name our new coin and give it a symbol\nconst name = \"TeamRocket\"\nconst symbol = \"ROKT\"\n\n// Where is the decimal point indicate what 1 asset is and where fractional assets begin\n// Ex: 1 LUX is denomination 9, so the smallest unit of LUX is nanoLUX (nLUX) at 10^-9 LUX\nconst denomination = 9\n```\n\n### Creating the initial state\n\nWe want to mint an asset with 400 coins to all of our managed keys, 500 to the second address we know of, and 600 to the second and third address. This sets up the state that will result from the Create Asset transaction.\n\n_Note: This example assumes we have the keys already managed in our X-Chain's Keychain._\n\n```js\nconst addresses = xchain.keyChain().getAddresses()\n\n// Create outputs for the asset's initial state\nconst secpOutput1 = new SECPTransferOutput(\n new BN(400),\n new BN(400),\n 1,\n addresses\n)\nconst secpOutput2 = new SECPTransferOutput(new BN(500), new BN(400), 1, [\n addresses[1],\n])\nconst secpOutput3 = new SECPTransferOutput(new BN(600), new BN(400), 1, [\n addresses[1],\n addresses[2],\n])\n\n// Populate the initialStates with the outputs\nconst initialState = new InitialStates()\ninitialState.addOutput(secpOutput1)\ninitialState.addOutput(secpOutput2)\ninitialState.addOutput(secpOutput3)\n```\n\n### Creating the signed transaction\n\nNow that we know what we want an asset to look like, we create an output to send to the network. There is an XVM helper function `buildCreateAssetTx()` which does just that.\n\n```js\n// Fetch the UTXOSet for our addresses\nconst utxos = await xchain.getUTXOs(addresses)\n\n// Make an unsigned Create Asset transaction from the data compiled earlier\nconst unsigned = await xchain.buildCreateAssetTx(\n utxos, // the UTXOSet containing the UTXOs we're going to spend\n addresses, // the addresses which will pay the fees\n addresses, // the addresses which recieve the change from the spent UTXOs\n initialState, // the initial state to be created for this new asset\n name, // the full name of the asset\n symbol, // a short ticker symbol for the asset\n denomination // the asse's denomination\n)\n\nconst signed = unsigned.sign(xchain) // returns a Tx class\n```\n\n### Issue the signed transaction\n\nNow that we have a signed transaction ready to send to the network, let's issue it!\n\nUsing the LuxJS X-Chain API, we going to call the `issueTx` function. This function can take either the Tx class returned in the previous step, a CB58 representation of the transaction, or a raw Buffer class with the data for the transaction. Examples of each are below:\n\n```js\n// using the Tx class\nconst txid = await xchain.issueTx(signed) // returns a CB58 serialized string for the TxID\n```\n\n```js\n// using the base-58 representation\nconst txid = await xchain.issueTx(signed.toString()) // returns a CB58 serialized string for the TxID\n```\n\n```js\n// using the transaction Buffer\nconst txid = await xchain.issueTx(signed.toBuffer()) // returns a CB58 serialized string for the TxID\n```\n\nWe assume ONE of those methods are used to issue the transaction.\n\n### Get the status of the transaction\n\nNow that we sent the transaction to the network, it takes a few seconds to determine if the transaction has gone through. We can get an updated status on the transaction using the TxID through the XVM API.\n\n```js\n// returns one of: \"Accepted\", \"Processing\", \"Unknown\", and \"Rejected\"\nconst status = await xchain.getTxStatus(txid)\n```\n\nThe statuses can be one of \"Accepted\", \"Processing\", \"Unknown\", and \"Rejected\":\n\n* \"Accepted\" indicates that the transaction has been accepted as valid by the network and executed\n* \"Processing\" indicates that the transaction is being voted on.\n* \"Unknown\" indicates that node knows nothing about the transaction, indicating the node doesn't have it\n* \"Rejected\" indicates the node knows about the transaction, but it conflicted with an accepted transaction\n\n### Identifying the newly created asset\n\nThe X-Chain uses the TxID of the transaction which created the asset as the unique identifier for the asset. This unique identifier is henceforth known as the \"AssetID\" of the asset. When assets are traded around the X-Chain, they always reference the AssetID that they represent.\n\n## Example 3 — Sending An Asset\n\nThis example sends an asset in the X-Chain to a single recipient. The first step in this process is to create an instance of Lux connected to our Lux Platform endpoint of choice.\n\n```js\nimport { Lux, BinTools, Buffer, BN } from \"luxnet\"\n\nconst myNetworkID = 12345 // default is 1, we want to override that for our local network\nconst lux = new lux.Lux(\n \"localhost\",\n 9650,\n \"http\",\n myNetworkID\n)\nconst xchain = lux.XChain() // returns a reference to the X-Chain used by LuxJS\n```\n\nWe're also assuming that the keystore contains a list of addresses used in this transaction.\n\n### Getting the UTXO Set\n\nThe X-Chain stores all available balances in a datastore called Unspent Transaction Outputs (UTXOs). A UTXO Set is the unique list of outputs produced by transactions, addresses that can spend those outputs, and other variables such as lockout times (a timestamp after which the output can be spent) and thresholds (how many signers are required to spend the output).\n\nFor the case of this example, we're going to create a simple transaction that spends an amount of available coins and sends it to a single address without any restrictions. The management of the UTXOs will mostly be abstracted away.\n\nHowever, we do need to get the UTXO Set for the addresses we're managing.\n\n```js\nconst myAddresses = xchain.keyChain().getAddresses() // returns an array of addresses the KeyChain manages as buffers\nconst addressStrings = xchain.keyChain().getAddressStrings() // returns an array of addresses the KeyChain manages as strings\nconst u = await xchain.getUTXOs(myAddresses)\nconst utxos = u.utxos\n```\n\n### Spending the UTXOs\n\nThe `buildBaseTx()` helper function sends a single asset type. We have a particular assetID whose coins we want to send to a recipient address. This is an imaginary asset for this example which we believe to have 400 coins. Let's verify that we have the funds available for the transaction.\n\n```js\nconst assetID = \"8pfG5CTyL5KBVaKrEnCvNJR95dUWAKc1hrffcVxfgi8qGhqjm\" // cb58 string\nconst mybalance = utxos.getBalance(myAddresses, assetID) // returns 400 as a BN\n```\n\nWe have 400 coins! We're going to now send 100 of those coins to our friend's address.\n\n```js\nconst sendAmount = new BN(100) // amounts are in BN format\nconst friendsAddress = \"X-lux1k26jvfdzyukms95puxcceyzsa3lzwf5ftt0fjk\" // address format is Bech32\n\n// The below returns a UnsignedTx\n// Parameters sent are (in order of appearance):\n// * The UTXO Set\n// * The amount being sent as a BN\n// * An array of addresses to send the funds\n// * An array of addresses sending the funds\n// * An array of addresses any leftover funds are sent\n// * The AssetID of the funds being sent\nconst unsignedTx = await xchain.buildBaseTx(\n utxos,\n sendAmount,\n [friendsAddress],\n addressStrings,\n addressStrings,\n assetID\n)\nconst signedTx = xchain.signTx(unsignedTx)\nconst txid = await xchain.issueTx(signedTx)\n```\n\nAnd the transaction is sent!\n\n### Get the status of the transaction\n\nNow that we sent the transaction to the network, it takes a few seconds to determine if the transaction has gone through. We can get an updated status on the transaction using the TxID through the X-Chain.\n\n```js\n// returns one of: \"Accepted\", \"Processing\", \"Unknown\", and \"Rejected\"\nconst status = await xchain.getTxStatus(txid)\n```\n\nThe statuses can be one of \"Accepted\", \"Processing\", \"Unknown\", and \"Rejected\":\n\n* \"Accepted\" indicates that the transaction has been accepted as valid by the network and executed\n* \"Processing\" indicates that the transaction is being voted on.\n* \"Unknown\" indicates that node knows nothing about the transaction, indicating the node doesn't have it\n* \"Rejected\" indicates the node knows about the transaction, but it conflicted with an accepted transaction\n\n### Check the results\n\nThe transaction finally came back as \"Accepted\", now let's update the UTXOSet and verify that the transaction balance is as we expected.\n\n*Note: In a real network the balance isn't guaranteed to match this scenario. Transaction fees or additional spends may vary the balance. For the purpose of this example, we assume neither of those cases.*\n\n```js\nconst updatedU = await xchain.getUTXOs()\nconst updatedUTXOs = updatedU.utxos\nconst newBalance = updatedUTXOs.getBalance(myAddresses, assetID)\nif (newBalance.toNumber() != mybalance.sub(sendAmount).toNumber()) {\n throw Error(\"heyyy these should equal!\")\n}\n```\n\n### Repo Dependency Updates\n\nDependabot will make pull requests against the development branch. If all tests pass, it is safe to merge into development, but for redundancy you want to try to build it locally.\n\n```zsh\ngit fetch origin\ngit checkout -b \ngit merge development\nyarn build && yarn test\n```\n\nIf the E2E check does not pass, go into the 'checks' section of the PR.\n`https://github.com/ava-labs/luxjs/pull//checks`\n\n* Click on the `> E2E` tab on the left\n* Click 'Re-run jobs' on the right", "_attachments": {} }