\n\n# @stricahq/typhonjs\n\n[](https://www.npmjs.com/package/@stricahq/typhonjs)\n[](https://www.npmjs.com/package/@stricahq/typhonjs)\n[](https://nodejs.org)\n[](./LICENSE)\n\nPure JavaScript Cardano wallet library.\n\n- Parse and create every type of Cardano address\n- Build transactions with automatic UTxO selection, fee calculation and change\n- Mint and burn tokens\n- Lock funds at Plutus V1, V2 and V3 scripts and spend them\n- Stake, withdraw rewards, delegate to a DRep, vote and submit governance proposals\n- Attach metadata\n\nIt doesn't use any Node.js builtins, so it runs in Node.js and in the browser without polyfills.\n\n## v4 is a breaking change\n\nv4 is ESM-only, needs Node 22.12 or later, and uses `bigint` and `Uint8Array` where 3.x used `BigNumber` and `Buffer`.\n\n### Migrating from 3.x\n\n| 3.x | 4.x |\n|---|---|\n| `BigNumber` amounts, fees, deposits and protocol parameters | `bigint` |\n| `priceMem`, `priceSteps` and `minFeeRefScriptCostPerByte` as `BigNumber` | `Rational`, such as `0.0577`, `\"577/10000\"` or `[577, 10000]` |\n| `collateralPercent` and `ProtocolParamUpdate.maxValueSize` as `BigNumber` | `number` |\n| `BigNumber` in `PlutusData` | `bigint` |\n| `Buffer` in and out | `Uint8Array` out, `Buffer` still accepted as input |\n| `bytes.toString(\"hex\")` | `utils.toHex(bytes)` |\n| `Buffer.from(hex, \"hex\")` | `utils.fromHex(hex)` |\n| Plutus data maps with an indefinite length | definite length, so the hash of a datum that holds a map changes |\n| `prepareTransaction` adds no collateral return | it adds a collateral return and total collateral to Plutus transactions |\n| `prepareTransaction` always spends the first UTxO in `inputs` | it spends none when the inputs you added cover the transaction |\n| Node.js polyfills for browser bundles | no Node.js builtins |\n| CommonJS package | ESM only, `require(esm)` on Node >= 22.12 |\n\n## Installation\n\n```sh\nyarn add @stricahq/typhonjs\n```\n\n### Browser\n\n```html\n\n\n```\n\n## Addresses\n\n`utils.getAddressFromString` reads any bech32 or Byron address and gives you back an address object:\n\n```js\nimport { address, types, utils } from \"@stricahq/typhonjs\";\n\nconst receiver = utils.getAddressFromString(\n \"addr1q9dmtr22dz54qn8pgx4yhle64nhwpqjyxsueaetdcxxa7k5jhh20yrgtl00c5mqnpjm5p8aud9cqldgwf3rq8dxvgy4snhadga\"\n);\n\nreceiver instanceof address.BaseAddress; // true\nreceiver.getHex(); // \"015bb58d4a68...\"\nreceiver.paymentCredential.hash; // Uint8Array(28)\nreceiver.stakeCredential.hash; // Uint8Array(28)\n```\n\nTo create your wallet's own addresses, derive its keys with [@stricahq/bip32ed25519](https://github.com/StricaHQ/bip32ed25519) v2 and put their hashes in credentials:\n\n```js\nimport { Bip32PrivateKey } from \"@stricahq/bip32ed25519\";\n\nconst rootKey = await Bip32PrivateKey.fromEntropy(entropy);\nconst accountKey = rootKey.derivePath(\"m/1852'/1815'/0'\");\nconst accountXpub = accountKey.toBip32PublicKey();\n\nconst HARDENED = 0x80000000;\nconst bipPath = (chain, index) => ({\n purpose: HARDENED + 1852,\n coin: HARDENED + 1815,\n account: HARDENED,\n chain,\n index,\n});\n\nconst paymentCredential = {\n type: types.HashType.ADDRESS,\n hash: accountXpub.derivePath(\"0/0\").toPublicKey().hash(),\n bipPath: bipPath(0, 0),\n};\nconst stakeCredential = {\n type: types.HashType.ADDRESS,\n hash: accountXpub.derivePath(\"2/0\").toPublicKey().hash(),\n bipPath: bipPath(2, 0),\n};\n\nconst myAddress = new address.BaseAddress(\n types.NetworkId.MAINNET,\n paymentCredential,\n stakeCredential\n);\nmyAddress.getBech32(); // \"addr1q...\"\n\nconst rewardAddress = new address.RewardAddress(types.NetworkId.MAINNET, stakeCredential);\nrewardAddress.getBech32(); // \"stake1u...\"\n```\n\n## Transactions\n\nA transaction needs the current protocol parameters:\n\n```js\nconst protocolParams = {\n minFeeA: 44n,\n minFeeB: 155381n,\n stakeKeyDeposit: 2000000n,\n utxoCostPerByte: 4310n,\n maxValueSize: 5000,\n\n // the rest are optional\n maxTxSize: 16384,\n // for reference scripts\n minFeeRefScriptCostPerByte: 15,\n // for Plutus scripts\n collateralPercent: 150,\n priceMem: 0.0577,\n priceSteps: 0.0000721,\n languageView: { PlutusScriptV3: [/* cost model */] },\n};\n```\n\n`paymentTransaction` sends ADA and tokens from a list of UTxOs:\n\n```js\nimport { Transaction } from \"@stricahq/typhonjs\";\n\nconst utxos = [\n {\n txId: \"d771da555feac5b6376652b284c20b39f7b5aef8ea8e03c927f7f731fed13314\",\n index: 0,\n amount: 50000000n,\n tokens: [],\n address: myAddress,\n },\n];\n\nconst tx = new Transaction({ protocolParams }).paymentTransaction({\n inputs: utxos,\n outputs: [{ address: receiver, amount: 5000000n, tokens: [] }],\n changeAddress: myAddress,\n ttl: currentSlot + 7200,\n});\n\ntx.getFee(); // bigint\n```\n\nAmounts are `bigint` lovelace. A token is `{ policyId, assetName, amount }`, with the policy id and asset name in hex.\n\nFor anything else, start from an empty `Transaction`, add what it should do, and call `prepareTransaction`:\n\n```js\nconst tx = new Transaction({ protocolParams });\n\ntx.addOutput({ address: receiver, amount: 5000000n, tokens: [] });\ntx.setAuxiliaryData({ metadata: [{ label: 674, data: { msg: [\"Thanks for dinner\"] } }] });\ntx.setTTL(currentSlot + 7200);\n\ntx.prepareTransaction({ inputs: utxos, changeAddress: myAddress });\n```\n\n`prepareTransaction` spends UTxOs from `inputs`, in the order you give them, until they cover the outputs, deposits and fee. It sends the rest to `changeAddress` and sets the fee.\n\n## Signing\n\n`getRequiredWitnesses()` lists every key that has to sign, with the `bipPath` of its credential. Sign the transaction hash with each one:\n\n```js\nconst txHash = tx.getTransactionHash();\n\nfor (const [, path] of tx.getRequiredWitnesses()) {\n const privateKey = accountKey.derive(path.chain).derive(path.index).toPrivateKey();\n tx.addWitness({\n publicKey: privateKey.toPublicKey().toBytes(),\n signature: privateKey.sign(txHash),\n });\n}\n\nconst { hash, payload } = tx.buildTransaction();\n```\n\n`payload` is the signed transaction as CBOR hex, ready to submit, and `hash` is its id.\n\nKeys that a native script or a required signer asks for are listed by `getRequiredNativeScriptWitnesses()` and `getRequiredSigners()`.\n\n## Tokens\n\nMint with a native script policy:\n\n```js\nimport { NativeScriptFactory } from \"@stricahq/typhonjs\";\n\nconst policy = new NativeScriptFactory({ pubKeyHash: utils.toHex(policyKeyHash) });\nconst policyId = utils.toHex(policy.policyId());\nconst assetName = utils.toHex(new TextEncoder().encode(\"TYPHON\"));\n\ntx.addMint({ policyId, assets: [{ assetName, amount: 1000n }], nativeScript: policy.json() });\ntx.addOutput({\n address: receiver,\n amount: 2000000n,\n tokens: [{ policyId, assetName, amount: 1000n }],\n});\n```\n\nA negative amount burns. For a Plutus policy, set `plutusScript` and a `redeemer` on the mint in place of `nativeScript`.\n\n## Staking\n\n```js\nconst { CertificateType, DRepType } = types;\n\n// register the stake key and delegate to a pool\ntx.addCertificate({\n type: CertificateType.STAKE_REG_DELEG,\n cert: {\n stakeCredential,\n poolKeyHash: utils.decodeBech32(\"pool1...\").value,\n deposit: protocolParams.stakeKeyDeposit,\n },\n});\n\n// delegate voting power to a DRep\ntx.addCertificate({\n type: CertificateType.VOTE_DELEGATION,\n cert: { stakeCredential, dRep: { type: DRepType.ADDRESS, key: dRepKeyHash } },\n});\n\n// withdraw rewards\ntx.addWithdrawal({ rewardAccount: rewardAddress, amount: rewardBalance });\n```\n\n`types.CertificateType` has the other stake, DRep and committee certificates.\n\n## Governance\n\nA DRep key comes from the same account as the wallet's other keys:\n\n```js\nconst dRepCredential = {\n type: types.HashType.ADDRESS,\n hash: accountXpub.derivePath(\"3/0\").toPublicKey().hash(),\n bipPath: bipPath(3, 0),\n};\n```\n\nRegister it:\n\n```js\ntx.addCertificate({\n type: types.CertificateType.DREP_REG,\n cert: { dRepCredential, deposit: 500000000n, anchor: null },\n});\n```\n\nVote on a governance action:\n\n```js\ntx.addVotingProcedure({\n voter: { type: types.VoterType.DREP_KEY, key: dRepCredential },\n votes: [\n {\n govActionId: { txId: utils.fromHex(actionTxId), index: 0 },\n vote: types.VoteType.YES,\n anchor: null,\n },\n ],\n});\n```\n\n`addProposalProcedure` submits a proposal, and `setDonationAmount` donates to the treasury.\n\n## Plutus scripts\n\nTo lock funds at a script, send them to its address with a datum:\n\n```js\nconst scriptAddress = utils.getAddressFromString(\"addr1w...\");\n\ntx.addOutput({\n address: scriptAddress,\n amount: 5000000n,\n tokens: [],\n plutusData: { constructor: 0, fields: [42n, utils.fromHex(\"cafe\")] },\n});\n```\n\nThat's an inline datum. Set `plutusDataHash` instead for a datum hash. An output with `plutusScript` or `nativeScript` holds that script as a reference script.\n\nTo spend from the script, add the UTxO with a redeemer, and put the script on its address credential:\n\n```js\nconst plutusScript = {\n cborHex: \"59...\",\n type: types.PlutusScriptType.PlutusScriptV3,\n};\n\ntx.addInput({\n txId: lockedTxId,\n index: 0,\n amount: 5000000n,\n tokens: [],\n address: new address.EnterpriseAddress(types.NetworkId.MAINNET, {\n type: types.HashType.SCRIPT,\n hash: scriptAddress.paymentCredential.hash,\n plutusScript,\n }),\n plutusData: datum, // leave out if the UTxO holds its datum inline\n redeemer: {\n plutusData: { constructor: 0, fields: [] },\n exUnits: { mem: 1000000, steps: 500000000 },\n },\n});\n\ntx.prepareTransaction({ inputs: utxos, changeAddress: myAddress, collateralInputs });\n```\n\n`collateralInputs` are UTxOs you keep for collateral.\n\nA redeemer works the same way on a mint, certificate, withdrawal, vote or proposal that runs a Plutus script. When a reference input holds the script, leave it off the credential and add the reference input:\n\n```js\ntx.addReferenceInput({ txId: refTxId, index: 0, plutusScript });\n```\n\nExecution units come from evaluating the transaction. `getRedeemers()` lists every redeemer with the tag and index an evaluator reports its units by. Set the units on each `redeemer`, then call `prepareTransaction` again so the fee covers them:\n\n```js\nfor (const { tag, index, redeemer } of tx.getRedeemers()) {\n redeemer.exUnits = evaluation[`${tag}:${index}`];\n}\n\ntx.prepareTransaction({ inputs: utxos, changeAddress: myAddress, collateralInputs });\n```\n\n## Utilities\n\n| Helper | What it does |\n|---|---|\n| `utils.toHex`, `utils.fromHex` | bytes to hex and back |\n| `utils.getAddressFromString`, `utils.getAddressFromHex` | an address object from bech32, base58, bytes or hex |\n| `utils.decodeBech32` | the prefix and bytes of any bech32 string |\n| `utils.calculateMinUtxoAmountBabbage` | the least ADA an output can hold |\n| `PlutusDataFactory` | the CBOR and hash of a datum |\n| `NativeScriptFactory` | the CBOR and policy id of a native script |\n| `crypto.hash32`, `crypto.hash28` | Blake2b-256 and Blake2b-224 |\n\n## API docs\n\nThe full API reference is at [docs.strica.io/lib/typhonjs](https://docs.strica.io/lib/typhonjs), and the [tests](./tests) have more examples.\n\n## Used by\n\n[Typhon Wallet](https://typhonwallet.io)\n\n# License\n\nCopyright 2022 Strica\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","readmeFilename":"README.md"}
![](\"https://docs.strica.io/images/logo.png\"){kind=logo}
\n \n