A TypeScript library for parsing Counterparty protocol transactions from Bitcoin blockchain data. Supports both legacy OP_RETURN and modern Taproot reveal formats.
- OP_RETURN Parser: Decode RC4-encrypted Counterparty messages from Bitcoin OP_RETURN outputs
- Taproot Parser: Extract Counterparty data from Taproot reveal transactions (witness scripts)
- Complete Protocol Support: Handles all major Counterparty message types
- Type Safety: Full TypeScript support with detailed type definitions
npm install @counterpartyxcp/txparserThis library requires bitcoinjs-lib as a peer dependency:
npm install bitcoinjs-lib@^7.0.0-rc.0import { parse_op_return } from '@counterpartyxcp/txparser';
import * as btc from 'bitcoinjs-lib';
const scriptBuffer = Buffer.from('...'); // OP_RETURN script
const firstInputTxid = '...'; // Transaction ID of first input (used as RC4 key)
const network = btc.networks.bitcoin;
const result = parse_op_return(scriptBuffer, firstInputTxid, network);
if (result) {
console.log('Message Type:', result.message_name);
console.log('Message ID:', result.message_id);
console.log('Parameters:', result.params);
}import { parse_reveal_tx } from '@counterpartyxcp/txparser';
import * as btc from 'bitcoinjs-lib';
const revealTxHex = '...'; // Raw transaction hex
const network = btc.networks.bitcoin;
const result = parse_reveal_tx(revealTxHex, network);
if (result) {
console.log('Message Type:', result.message_name);
console.log('Message ID:', result.message_id);
console.log('Parameters:', result.params);
}The parser supports the following Counterparty message types:
- Enhanced Send (ID: 2) - Send assets with memo support
- Sweep (ID: 4) - Sweep all assets to an address
- Order (ID: 10) - Create decentralized exchange orders
- BTC Pay (ID: 11) - Bitcoin payment for orders
- Dispenser (ID: 12) - Create asset dispensers
- Dispense (ID: 13) - Trigger dispenser payment
- Issuance (ID: 20, 22) - Issue new assets
- Issuance Subasset (ID: 21, 23) - Issue subassets
- Broadcast (ID: 30) - Broadcast messages/data
- Dividend (ID: 50) - Pay dividends to asset holders
- Cancel (ID: 70) - Cancel open orders
- Fairminter (ID: 90) - Create fair minter
- Fairmint (ID: 91) - Mint from fair minter
- Attach (ID: 101) - Attach assets to UTXOs
- Detach (ID: 102) - Detach assets from UTXOs
- Destroy (ID: 110) - Destroy assets
interface ParsedTransaction {
message_name: string;
message_id: number;
params: TransactionPayload;
}
type TransactionPayload =
| EnhancedSendPayload
| SweepPayload
| IssuancePayload
| OrderPayload
| BroadcastPayload
| FairminterPayload
| FairmintPayload
| AttachPayload
| DetachPayload
| DispenserPayload
| DispensePayload
| DividendPayload
| CancelPayload
| DestroyPayload
| UnknownPayload;See types.ts for complete type definitions.
npm install
npm run buildnpm run devThe project includes a comprehensive test suite with 99.52% code coverage and 100% line coverage.
# Run all tests
npm test
# Run tests in watch mode
npm run test:watch
# Run tests with coverage report
npm run test:coverageSee tests/README.md for detailed test documentation.
Counterparty OP_RETURN messages are:
- Encrypted with RC4 using the first input's transaction ID as the key
- Prefixed with "CNTRPRTY" (8 bytes)
- Followed by message type ID (1 or 4 bytes)
- Followed by CBOR or binary-encoded payload
Taproot reveal transactions use witness scripts with envelope patterns:
- Generic envelope:
OP_FALSE OP_IF <data chunks> OP_ENDIF - Ord/XCP envelope:
OP_FALSE OP_IF "ord" "xcp" <metadata> <content> OP_ENDIF
Contributions are welcome! Please feel free to submit a Pull Request.
MIT