← Back to Docs

Adding Parent Chains

How to add support for new L1 blockchains to Coinshift.

Currently Supported

RPC Compatibility Requirements

A blockchain must implement these Bitcoin Core JSON-RPC methods:

Required Methods

• getblockchaininfo — current block height and chain info
• getrawtransaction — fetch transaction details by txid
• listunspent — list UTXOs for an address

Optional Methods

• getreceivedbyaddress — alternative transaction discovery

Responses must follow Bitcoin Core's JSON-RPC format. The getrawtransaction response (verbose) must include: txid, confirmations, blockheight (optional), vout with value and scriptPubKey.address, and vin with txid and vout.

Step-by-Step Guide

Step 1: Update ParentChainType Enum

Edit lib/types/swap.rs:

pub enum ParentChainType {
    BTC,
    BCH,
    LTC,
    Signet,
    Regtest,
    NewChain,  // Add your new chain
}

Step 2: Implement Helper Methods

Update all impl ParentChainType methods with your chain's values:

impl ParentChainType {
    pub fn default_confirmations(&self) -> u32 {
        match self {
            // ...
            Self::NewChain => 6,
        }
    }
    pub fn default_rpc_port(&self) -> u16 {
        match self {
            // ...
            Self::NewChain => 8555,
        }
    }
    pub fn coin_name(&self) -> &'static str {
        match self {
            // ...
            Self::NewChain => "New Chain",
        }
    }
    pub fn ticker(&self) -> &'static str {
        match self {
            // ...
            Self::NewChain => "NEW",
        }
    }
    // Also update: to_bitcoin_network(), sats_per_coin(),
    // default_rpc_url_hint(), all()
}

Step 3: Update L1 Config UI

Edit app/gui/l1_config.rs to add setup hints:

match self.selected_parent_chain {
    // ...
    ParentChainType::NewChain => {
        ui.label("Use NewChain Core with -txindex=1.");
    }
}

Step 4: Test RPC Compatibility

# getblockchaininfo
curl -u user:password --data-binary \
  '{"jsonrpc":"2.0","id":1,"method":"getblockchaininfo","params":[]}' \
  -H 'content-type: application/json' http://localhost:PORT/

# getrawtransaction (replace TXID)
curl -u user:password --data-binary \
  '{"jsonrpc":"2.0","id":1,"method":"getrawtransaction","params":["TXID",true]}' \
  -H 'content-type: application/json' http://localhost:PORT/

# listunspent (replace ADDRESS)
curl -u user:password --data-binary \
  '{"jsonrpc":"2.0","id":1,"method":"listunspent","params":[0,999999,["ADDRESS"]]}' \
  -H 'content-type: application/json' http://localhost:PORT/

Step 5: Handle Chain-Specific Quirks

If your chain has RPC differences, extend ParentChainRpcClient:

impl ParentChainRpcClient {
    pub fn get_transaction_for_chain(
        &self, txid: &str, chain: ParentChainType,
    ) -> Result<TransactionInfo, Error> {
        match chain {
            ParentChainType::NewChain => { /* custom handling */ }
            _ => self.get_transaction(txid),
        }
    }
}

Node Configuration

Each parent chain node needs:

1. Transaction index: -txindex=1
2. RPC enabled: Configure rpcuser, rpcpassword, rpcport
3. Address indexing (optional): improves some features

Example config file:

server=1
txindex=1
rpcuser=myuser
rpcpassword=mypassword
rpcport=8332
rpcallowip=127.0.0.1

Coinshift RPC Configuration

Configure the connection in Coinshift via the GUI (L1 Config tab) or edit the config file directly:

• Linux: ~/.local/share/coinshift/l1_rpc_configs.json
• macOS: ~/Library/Application Support/coinshift/l1_rpc_configs.json
• Windows: %APPDATA%\coinshift\l1_rpc_configs.json

Testing

Unit Tests

#[test]
fn test_new_chain_config() {
    let chain = ParentChainType::NewChain;
    assert_eq!(chain.default_rpc_port(), 8555);
    assert_eq!(chain.coin_name(), "New Chain");
    assert_eq!(chain.ticker(), "NEW");
}

Integration Tests

1. Start your chain node in regtest/testnet mode
2. Configure RPC in Coinshift
3. Create a test swap targeting your chain
4. Verify transaction detection and confirmation tracking

Troubleshooting

• "RPC error: Method not found" — Node may not support a required method; check if it needs enabling
• "Transaction not found" — Ensure txindex=1 is set; restart with -reindex if needed
• "Connection refused" — Check node is running and port matches config
• "Invalid response format" — RPC response differs from Bitcoin Core; may need custom handling

Enable debug logging:

RUST_LOG=coinshift::parent_chain_rpc=debug ./coinshift-gui

Contributing

When submitting a PR for a new parent chain, include:

1. Changes to lib/types/swap.rs (enum + helper methods)
2. Changes to app/gui/l1_config.rs (UI hints)
3. Test cases for the new chain
4. Documentation updates