dedoo-inscriber

v0.2.11

Published

7 months ago

Blockchain Agnostic Inscription library for Bitcoin-like cryptocurrencies

0High
0Medium
0Low

Dedoo Inscriber (dedoo-inscriber)

A blockchain-agnostic inscription library for Bitcoin-like cryptocurrencies. Create and manage ordinal inscriptions across multiple blockchain networks with support for text, images, and arbitrary data.

🚀 Key Features:

Blockchain Agnostic: Works with any Bitcoin-like cryptocurrency that supports ordinals
Configurable Parameters: No hardcoded values - all blockchain-specific settings configurable
Multiple Data Types: Support for text, images, JSON, and arbitrary binary data
Generic Testnet Detection: Automatically detects testnet environments
TypeScript Support: Full type definitions included
Efficient Inscriptions: Optimized transaction creation for minimal fees
MIME Type Support: Proper content type handling for different file formats
Backward Compatible: Existing code continues to work without changes

📦 Installation

npm install dedoo-inscriber dedoo-coinjs-lib

🔧 Quick Start

Basic Text Inscription (Using Default Configuration)

import { inscribe } from 'dedoo-inscriber';
import { networks } from 'dedoo-coinjs-lib';

// Register your blockchain network
networks.register('mycoin', {
  messagePrefix: '\\x19MyCoin Signed Message:\\n',
  bech32: 'mc',
  bip32: { public: 0x0488b21e, private: 0x0488ade4 },
  pubKeyHash: 0,
  scriptHash: 5,
  wif: 128
});

const network = networks.get('mycoin');

// Create a text inscription using default configuration
const txs = await inscribe({
  toAddress: 'recipient_address',
  fromAddress: 'sender_address',
  contentType: 'text/plain',
  data: Buffer.from('Hello, Ordinals!'),
  feeRate: 10, // satoshis per vbyte
  network,
  publicKey: Buffer.from('your_public_key_hex', 'hex'),
  getUtxos: async (amount) => {
    // Your UTXO fetching logic
    return await fetchUtxos(amount);
  },
  signPsbt: async (psbtBase64, disableTweakSigner = false) => {
    // Your PSBT signing logic
    return await signPsbtWithWallet(psbtBase64, disableTweakSigner);
  }
  // config not provided - uses default Bellcoin configuration
});

console.log('Fund Transaction:', txs[0]);
console.log('Reveal Transaction:', txs[1]);

Custom Blockchain Configuration

import { inscribe } from 'dedoo-inscriber';
import { networks } from 'dedoo-coinjs-lib';

const network = networks.get('mycoin');

// Create inscription with custom blockchain configuration
const txs = await inscribe({
  toAddress: 'recipient_address',
  fromAddress: 'sender_address',
  contentType: 'image/png',
  data: imageBuffer, // Your image data
  feeRate: 15,
  network,
  publicKey: publicKeyBuffer,
  getUtxos: fetchUtxosFunction,
  signPsbt: signPsbtFunction,
  config: {
    maxChunkLen: 200,                    // Custom chunk size for this blockchain
    utxoMinValue: 500,                   // Lower minimum UTXO value
    serviceFee: 500_000,                 // Custom service fee (0.005 coins)
    serviceFeeMainnetAddress: "YourMainnetServiceAddress",
    serviceFeeTestnetAddress: "YourTestnetServiceAddress",
  }
});

console.log('Custom configured inscription created!');

Image Inscription

import { inscribe } from 'dedoo-inscriber';
import fs from 'fs';

// Read image file
const imageData = fs.readFileSync('path/to/image.png');

const txs = await inscribe({
  toAddress: 'recipient_address',
  fromAddress: 'sender_address',
  contentType: 'image/png',
  data: imageData,
  feeRate: 10,
  network,
  publicKey: publicKeyBuffer,
  getUtxos: fetchUtxosFunction,
  signPsbt: signPsbtFunction,
  config: {
    maxChunkLen: 300, // Larger chunks for image data
    utxoMinValue: 1000,
  }
});

🏗️ API Reference

inscribe(params: InscribeParams): Promise<string[]>

Creates an ordinal inscription transaction.

Parameters:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | toAddress | string | ✅ | Recipient address for the inscription | | fromAddress | string | ✅ | Sender address | | contentType | string | ✅ | MIME type of the content (e.g., 'text/plain', 'image/png') | | data | Buffer | ✅ | Content data to inscribe | | feeRate | number | ✅ | Fee rate in satoshis per vbyte | | network | Network | ✅ | Network configuration from dedoo-coinjs-lib | | publicKey | Buffer | ✅ | Public key for signing | | getUtxos | function | ✅ | Function to fetch UTXOs: (amount: number) => Promise<ApiUTXO[]> | | signPsbt | function | ✅ | Function to sign PSBT: (psbtBase64: string, disableTweakSigner?: boolean) => Promise<string> | | config | InscriptionConfig | ❌ | Optional blockchain-specific configuration |

Returns: Promise<string[]> - Array containing [fundTransaction, revealTransaction] hex strings

InscriptionConfig Interface

Optional configuration for blockchain-specific parameters:

interface InscriptionConfig {
  maxChunkLen?: number;              // Maximum chunk length for inscription data (default: 240)
  maxPayloadLen?: number;            // Maximum payload length (default: 1500)
  utxoMinValue?: number;             // Minimum UTXO value in satoshis (default: 1000)
  serviceFee?: number;               // Service fee in satoshis (default: 1,000,000)
  serviceFeeMainnetAddress?: string; // Mainnet service fee address
  serviceFeeTestnetAddress?: string; // Testnet service fee address
}

ApiUTXO Interface

UTXO format expected by the getUtxos function:

interface ApiUTXO {
  txid: string;                // Transaction ID
  vout: number;                // Output index
  value: number;               // Value in satoshis
  scriptPubKeyHex?: string;    // Script public key hex
  redeemScriptHex?: string;    // Redeem script hex (if applicable)
  hex: string;                 // Full transaction hex
}

📋 Configuration Examples

Bellcoin (Default Configuration)

// No config needed - uses defaults
const txs = await inscribe({
  // ... other parameters
  // config not provided - uses Bellcoin defaults
});

Bitcoin Configuration

const bitcoinConfig = {
  maxChunkLen: 520,                    // Bitcoin script limit
  utxoMinValue: 546,                   // Bitcoin dust limit
  serviceFee: 1000,                    // Lower service fee
  serviceFeeMainnetAddress: "1YourBitcoinMainnetAddress",
  serviceFeeTestnetAddress: "2YourBitcoinTestnetAddress",
};

Dogecoin Configuration

const dogecoinConfig = {
  maxChunkLen: 240,
  utxoMinValue: 100000,                // 0.001 DOGE
  serviceFee: 100000000,               // 1 DOGE
  serviceFeeMainnetAddress: "DYourDogeMainnetAddress",
  serviceFeeTestnetAddress: "nYourDogeTestnetAddress",
};

Litecoin Configuration

const litecoinConfig = {
  maxChunkLen: 240,
  utxoMinValue: 5460,                  // Litecoin dust limit
  serviceFee: 100000,                  // 0.001 LTC
  serviceFeeMainnetAddress: "LYourLitecoinMainnetAddress",
  serviceFeeTestnetAddress: "tYourLitecoinTestnetAddress",
};

🔗 Ecosystem

dedoo-inscriber is part of the Dedoo blockchain-agnostic ecosystem:

dedoo-coinjs-lib - Core blockchain library
dedoopair - ECPair key management
dedoohdw - HD wallet functionality
dedoo-wallet-sdk - Provider SDK
dedoo-ordutils - Ordinals utilities

📋 Changelog

Version 0.2.11 (Latest)

✅ Blockchain Agnostic Configuration - All parameters now configurable via InscriptionConfig
✅ No More Hardcoded Values - Service fees, chunk sizes, and addresses configurable
✅ Enhanced TypeScript Support - New interfaces for better type safety
✅ Backward Compatibility - Existing code continues to work without changes
✅ Updated Dependencies - Now uses dedoo-coinjs-lib consistently
✅ Improved Documentation - Comprehensive examples for different blockchains

Version 0.2.10

Multi-blockchain support
Generic testnet detection
Improved error handling

🔄 Migration Guide

From Version 0.2.10 to 0.2.11

No breaking changes! Your existing code will continue to work exactly as before.

Optional: Migrate to Configurable Parameters

Before (still works):

const txs = await inscribe({
  toAddress: 'recipient',
  fromAddress: 'sender',
  contentType: 'text/plain',
  data: Buffer.from('Hello'),
  feeRate: 10,
  network,
  publicKey,
  getUtxos,
  signPsbt
  // Uses hardcoded Bellcoin defaults
});

After (recommended for new blockchains):

const txs = await inscribe({
  toAddress: 'recipient',
  fromAddress: 'sender',
  contentType: 'text/plain',
  data: Buffer.from('Hello'),
  feeRate: 10,
  network,
  publicKey,
  getUtxos,
  signPsbt,
  config: {
    serviceFee: 500_000,              // Custom service fee
    serviceFeeMainnetAddress: "YourAddress",
    serviceFeeTestnetAddress: "YourTestAddress",
    maxChunkLen: 300,                 // Custom chunk size
    utxoMinValue: 500                 // Custom minimum UTXO
  }
});

🎯 Best Practices

1. Choose Appropriate Chunk Sizes

// For text content
config: { maxChunkLen: 240 }

// For images/binary data
config: { maxChunkLen: 300 }

// For Bitcoin (script size limits)
config: { maxChunkLen: 520 }

2. Set Reasonable Service Fees

// High-value blockchain
config: { serviceFee: 1_000_000 }  // 0.01 coins

// Low-value blockchain
config: { serviceFee: 100_000 }    // 0.001 coins

// No service fee
config: { serviceFee: 0 }

3. Configure Dust Limits Properly

// Bitcoin
config: { utxoMinValue: 546 }

// Bellcoin
config: { utxoMinValue: 1000 }

// Dogecoin
config: { utxoMinValue: 100000 }

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

NPM Package: https://www.npmjs.com/package/dedoo-inscriber
GitHub Repository: https://github.com/dedooxyz/dedoo-inscriber
Documentation: https://docs.dedoo.xyz
Website: https://dedoo.xyz

🆘 Support

GitHub Issues: https://github.com/dedooxyz/dedoo-inscriber/issues
Community: https://discord.gg/dedoo
Email: [email protected]

Built with ❤️ by the Dedoo Development Team