@inscrib3/react

A React library for integrating Inscrib3 functionality into your web applications, providing a custom hook for managing Bitcoin wallet connections and Ordinals drops.

Installation

npm install @inscrib3/react

Quick Start

importReact,{useState,useEffect}from'react';importuseSdkfrom'@inscrib3/react';functionApp(){const{ wallet, drops, error }=useSdk();// Network and Chain (Bitcoin or Fractal) are supportedconst[myDrops,setMyDrops]=useState([]);// Connect wallet when button is clickedconsthandleConnect=()=>{wallet.connect();};// Fetch drops when wallet is connecteduseEffect(()=>{constfetchDrops=async()=>{if(wallet.recipientAddress){constdropsData=awaitdrops.all();if(dropsData){setMyDrops(dropsData);}}};fetchDrops();},[wallet.recipientAddress]);return(<div>{error&&<divclassName="error">{error}</div>}{!wallet.recipientAddress ? (<buttononClick={handleConnect}>Connect Wallet</button>) : (<div><p>Connected: {wallet.recipientAddress}</p><h2>My Drops</h2>{myDrops.map(drop=>(<divkey={drop.id}><h3>{drop.name}</h3><p>{drop.description}</p></div>))}</div>)}</div>);}

API Reference

useSdk Hook

The main export of this package is the useSdk hook, which provides access to wallet functionality and Inscrib3 operations.

importuseSdkfrom'@inscrib3/react';constMyComponent=()=>{const{ wallet, drops, error }=useSdk();// Use the SDK functionality};

Returns

Property	Type	Description
error	string | null	Error message if an operation fails
wallet	object	Wallet connection and signing functions
drops	object	Operations for managing drops

Wallet Operations

The wallet object provides functions for connecting to a Bitcoin wallet and signing messages.

const{ wallet }=useSdk();// Connect walletawaitwallet.connect();// Access wallet addressesconstpaymentAddress=wallet.paymentAddress;constrecipientAddress=wallet.recipientAddress;// Sign a messageconstsignature=awaitwallet.signMessage(address,message);

Wallet Properties and Methods

Property/Method	Type	Description
paymentAddress	string	User's payment address
paymentPublicKey	string	User's payment public key
recipientAddress	string	User's ordinals recipient address
recipientPublicKey	string	User's ordinals recipient public key
connect()	function	Connects to the wallet and requests necessary permissions
signMessage(address, message)	function	Signs a message with the specified address

Drops Management

The drops object provides simplified methods for managing Ordinals drops, abstracting away the authentication details.

const{ drops }=useSdk();// Create a new dropconstnewDrop=awaitdrops.create("My Drop","DROP","Description of my drop",fileList,// FileList object containing the icon"10000"// price in sats);// Get all dropsconstallDrops=awaitdrops.all();// Get a specific dropconstdrop=awaitdrops.read("drop-id");// Remove a dropawaitdrops.remove("drop-id");// Mint from a dropconstmintResult=awaitdrops.mint("drop-id");

Drops Methods

Method	Parameters	Description
create(name, symbol, description, fileList, price)	(string, string, string, FileList, string)	Creates a new drop
all()	()	Gets all drops for the connected user
read(id)	(string)	Gets details of a specific drop
remove(id)	(string)	Removes a drop
mint(id)	(string)	Mints from a drop (handles signing and broadcasting)

Uploads Management

The drops.uploads object provides methods for managing files in a drop.

const{ drops }=useSdk();// Get all uploads for a dropconstuploads=awaitdrops.uploads.all("drop-id");// Update uploads for a dropconstupdateResult=awaitdrops.uploads.update("drop-id",fileList);// Remove uploads from a dropconstremoveResult=awaitdrops.uploads.remove("drop-id",["file1.png","file2.png"]);

Uploads Methods

Method	Parameters	Description
all(id)	(string)	Gets all uploads for a drop
update(id, fileList)	(string, FileList)	Adds new files to a drop
remove(id, files)	(string, string[])	Removes files from a drop

Error Handling

The useSdk hook provides an error state that will be set when operations fail. You should display this to the user when it's not null.

const{ error }=useSdk();if(error){return<divclassName="error">{error}</div>;}

All methods automatically handle errors and update the error state, so you don't need to wrap them in try-catch blocks.

Wallet Connection Flow

The React SDK handles the complete wallet connection flow:

1. When wallet.connect() is called, it requests connection to the wallet
2. It requests both Payment and Ordinals addresses
3. It automatically requests a signature for authentication
4. It stores offline the addresses, message, and signature for use in API calls

This means you don't need to handle the authentication flow manually - just call wallet.connect() and the hook will take care of the rest.

Complete Example: Creating and Minting a Drop

importReact,{useState}from'react';importuseSdkfrom'@inscrib3/react';constCreateDropPage=()=>{const{ wallet, drops, error }=useSdk();const[name,setName]=useState('');const[symbol,setSymbol]=useState('');const[description,setDescription]=useState('');const[price,setPrice]=useState('');const[files,setFiles]=useState(null);const[createdDrop,setCreatedDrop]=useState(null);const[mintResult,setMintResult]=useState(null);consthandleConnect=async()=>{awaitwallet.connect();};consthandleCreateDrop=async(e)=>{e.preventDefault();constdrop=awaitdrops.create(name,symbol,description,files,price);if(drop){setCreatedDrop(drop);// Upload additional filesif(files&&files.length>1){awaitdrops.uploads.update(drop.id,files);}}};consthandleMint=async()=>{constresult=awaitdrops.mint(createdDrop.id);if(result){setMintResult(result);}};if(!wallet.paymentAddress){return(<div><h1>Please connect your wallet</h1><buttononClick={handleConnect}>Connect Wallet</button>{error&&<divclassName="error">{error}</div>}</div>);}return(<div>{error&&<divclassName="error">{error}</div>}<h1>Create New Ordinals Drop</h1>{!createdDrop ? (<formonSubmit={handleCreateDrop}><div><label>Name:</label><inputtype="text"value={name}onChange={(e)=>setName(e.target.value)}required/></div><div><label>Symbol:</label><inputtype="text"value={symbol}onChange={(e)=>setSymbol(e.target.value)}required/></div><div><label>Description:</label><textareavalue={description}onChange={(e)=>setDescription(e.target.value)}required/></div><div><label>Price (sats):</label><inputtype="text"value={price}onChange={(e)=>setPrice(e.target.value)}required/></div><div><label>Files:</label><inputtype="file"onChange={(e)=>setFiles(e.target.files)}multiplerequired/></div><buttontype="submit">Create Drop</button></form>) : (<div><h2>Drop Created Successfully!</h2><p>Drop ID: {createdDrop.id}</p>{!mintResult ? (<buttononClick={handleMint}>Mint from Drop</button>) : (<div><h3>Mint Successful!</h3><p>Transaction ID: {mintResult.txid}</p></div>)}</div>)}</div>);};

Implementation Details

Automatic PSBT Signing

The React SDK automatically handles the PSBT signing process when minting from a drop:

1. It calls the SDK's mint method to get the PSBTs
2. It uses sats-connect to request signatures for both PSBTs
3. It automatically broadcasts the signed PSBTs

This means you don't need to handle the signing process manually - just call drops.mint(id) and the hook will take care of the rest.

Network Configuration

The SDK is configured to use the Bitcoin Signet network by default. This is suitable for testing and development.

TypeScript Support

The library is written in TypeScript and includes full type definitions. You'll get autocomplete and type checking out of the box when using TypeScript.

License

MIT