Developer Guide

This guide explains how to properly create and submit transactions through Shield.

Creating Shield-Compatible Transactions

1. Get Payment Information

First, query the /info endpoint to retrieve the current Shield payment address and fee rates:

curl -XGET 'https://shield.rebarlabs.io/v1/info'

This returns the payment address and several fee options with corresponding hashrate estimates.

2. Add Shield Output

Add an output to your transaction that pays the Shield payment address provided in the /info response. The amount can be 1 sat for now.

2. Calculate Required Fee

Choose a fee tier based on your confirmation urgency:

• Higher fee tiers connect to more hashrate, increasing the chance of quick confirmation

• The estimated_hashrate value (0-1) represents the approximate percentage of Bitcoin hashrate that will accept your transaction

Calculate your total fee by multiplying your transaction size in vbytes by your chosen fee rate:

Total Fee = Transaction Size (vbytes) × Fee Rate (sats/vbyte)

3. Include the Shield Fee Output Value

Modify the output you created in your transaction to pay the calculated fee to the Shield payment address provided in the /info response.

Example using Bitcoin Core:

// Assuming you've calculated a required fee of 25000 satoshis
const shieldAddress = "bc1q..."; // From /info endpoint

const dummyOutputs = {
  [shieldAddress]: 1 / 100000000, // Convert to BTC
  "recipientAddress": 0.01 // Your actual transaction amount
};

// Create the transaction with mock outputs
const dummyTx = bitcoin.createrawtransaction(inputs, dummyOutputs);

// Decode the transaction to compute vSize
const decoded = bitcoin.decoderawtransaction(dummyTx);
const vSize = decoded.vsize;

// Calculate fees and adjust output values
const fee = vSize * feeRate;
const outputs = {
  [shieldAddress]: fee / 100000000, // Convert to BTC
  "recipientAddress": 0.01
};

// Create and sign the transaction
const rawTx = bitcoin.createRawTransaction(inputs, outputs);
const signedTx = bitcoin.signrawtransactionwithwallet(..);
const hexString = signedTx.hex;

4. Submit the Transaction

Submit your transaction using the /rpc endpoint:

curl -XPOST 'https://shield.rebarlabs.io/v1/rpc' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "1.0",
    "id": "shield",
    "method": "sendrawtransaction",
    "params": ["$HEX_STRING"]
  }'

Best Practices

1. Always query current fees: Fee requirements may change based on network conditions

2. Use P2WPKH outputs: Native SegWit outputs (bech32) are more efficient and cheaper

3. Consider transaction size: Larger transactions require higher total fees

4. Choose appropriate fee rates: Balance confirmation speed with cost based on your needs

5. Test transactions: For high-value transactions, consider testing with small amounts first