description |
---|
js-1sat-ord |
A Javascript library for creating and managing 1Sat Ordinal inscriptions and transactions. Uses @bsv/sdk
under the hood.
Install the library, and it's peer dependency. We recommend using Bun for the best performance, but you can also use Yarn or npm:
# Using Bun (recommended)
bun add js-1sat-ord @bsv/sdk
# Using Yarn
yarn add js-1sat-ord @bsv/sdk
# Using npm
npm i js-1sat-ord @bsv/sdk
import { createOrdinals, sendOrdinals, sendUtxos, deployBsv21Token, transferOrdToken } from 'js-1sat-ord'
Prepare some utxos to use in the following format. Be sure to use base64 encoded scripts. We use this encoding because it makes large scripts smaller in size.
import type { Utxo } from "js-1sat-ord";
const utxo: Utxo = {
satoshis: 269114,
txid: "61fd6e240610a9e9e071c34fc87569ef871760ea1492fe1225d668de4d76407e",
script: "<base64 encoded script>",
vout: 1,
};
You can use the helper fetchPayUtxos(address)
to fetch unspent transaction outputs from the public 1Sat API and create the scripts with the correct encoding. This should be a BSV address, not your ordinals address.
import { fetchPayUtxos } from "js-1sat-ord";
const utxos = await fetchPayUtxos(payAddress)
For a markdown inscription, you can create a string and convert it to base64:
import type { Inscription } from "js-1sat-ord";
// Create a markdown string
const markdownContent = "# Hello World!\n\nThis is a 1Sat Ordinal inscription.";
// Convert to base64
const encodedFileData = Buffer.from(markdownContent).toString('base64');
// Prepare the inscription object
const inscription: Inscription = {
dataB64: encodedFileData,
contentType: "text/markdown"
};
Be sure to use different keys for ordinals and normal payments:
import { PrivateKey } from "js-1sat-ord";
const paymentPk = PrivateKey.fromWif(paymentWif);
const ordPk = PrivateKey.fromWif(ordWif);
The createOrdinals
function creates a transaction with inscription outputs:
import type { CreateOrdinalsConfig } from "js-1sat-ord";
const config: CreateOrdinalsConfig = {
utxos: [utxo],
destinations: [{
address: ordinalDestinationAddress,
inscription: { dataB64: encodedFileData, contentType: "text/markdown" }
}],
paymentPk: paymentPk
};
const result = await createOrdinals(config);
Sends ordinals to the given destinations:
import type { SendOrdinalsConfig } from "js-1sat-ord";
const config: SendOrdinalsConfig = {
paymentUtxos: [paymentUtxo],
ordinals: [ordinalUtxo],
paymentPk: paymentPk,
ordPk: ordPk,
destinations: [{
address: destinationAddress,
inscription: { dataB64: encodedFileData, contentType: "text/markdown" }
}]
};
const result = await sendOrdinals(config);
import type { DeployBsv21TokenConfig } from "js-1sat-ord";
const config: DeployBsv21TokenConfig = {
symbol: "MYTICKER",
icon: "<icon_outpoint>",
utxos: [utxo],
initialDistribution: { address: destinationAddress, amt: "1000000000" },
paymentPk: paymentPk,
destinationAddress: destinationAddress
};
const result = await deployBsv21Token(config);
import type { TransferBsv21TokenConfig } from "js-1sat-ord";
const config: TransferBsv21TokenConfig = {
protocol: TokenType.BSV21,
tokenID: tokenID,
utxos: [utxo],
inputTokens: [tokenUtxo],
distributions: [{ address: destinationAddress, amt: "1000" }],
paymentPk: paymentPk,
ordPk: ordPk
};
const result = await transferOrdToken(config);
Sends utxos to the given destination:
import type { SendUtxosConfig } from "js-1sat-ord";
const config: SendUtxosConfig = {
utxos: [utxo],
paymentPk: paymentPk,
payments: [{ to: destinationAddress, amount: 1000 }]
};
const { tx } = await sendUtxos(config);
Each function accepts additional configuration options not shown in the examples above. These include:
changeAddress
: Address to send change to (if not provided, defaults to the payment key's address)satsPerKb
: Satoshis per kilobyte for fee calculationmetaData
: MAP (Magic Attribute Protocol) metadata to include in inscriptionssigner
: Custom signer object for transaction signingadditionalPayments
: Additional payments to include in the transaction
Refer to the function documentation for a complete list of configuration options for each function.
Since this package depends on @bsv/sdk
there should be no issue with bundlers.
There is a public 1Sat API which is documented here:
https://ordinals.gorillapool.io/api/docs