Skip to content

Commit 0235521

Browse files
Copilotbhavidhingra
Copilot
and
bhavidhingra
committed
Add BIP322 broadcastable message processor script and documentation
Co-authored-by: bhavidhingra <17147510+bhavidhingra@users.noreply.github.com>
1 parent 2d4b90e commit 0235521

File tree

3 files changed

+391
-0
lines changed

3 files changed

+391
-0
lines changed

‎examples/ts/BIP322_CLAIMS_README.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# BIP322 Broadcastable Message Processor
2+
3+
This TypeScript script processes JSON files containing claims with BIP322 broadcastable messages. It demonstrates how to:
4+
5+
1. Parse JSON structure containing claims data
6+
2. Extract `broadcastableMessage` fields from claims
7+
3. Use `deserializeBIP322BroadcastableMessage()` to deserialize each message
8+
4. Use `generateBIP322MessageListAndVerifyFromMessageBroadcastable()` to verify and process messages
9+
10+
## Usage
11+
12+
```bash
13+
npx tsx process-bip322-claims.ts <json-file> <coin-name>
14+
```
15+
16+
### Arguments
17+
18+
- `json-file`: Path to JSON file containing claims data
19+
- `coin-name`: Coin name (supported: "btc", "tbtc4")
20+
21+
### Example
22+
23+
```bash
24+
npx tsx process-bip322-claims.ts sample-claims.json btc
25+
```
26+
27+
## Input JSON Format
28+
29+
The script expects JSON files with the following structure:
30+
31+
```json
32+
{
33+
"status": "success",
34+
"claims": [
35+
{
36+
"id": "claim-001",
37+
"broadcastableMessage": "7b227478486578223a22303130323033222c226d657373616765496e666f223a5b7b2261646472657373223a22736f6d6541646472657373222c226d657373616765223a22736f6d654d657373616765222c227075626b657973223a5b227075626b657931222c227075626b657932225d2c2273637269707454797065223a2270327368227d5d7d",
38+
...
39+
}
40+
],
41+
"count": 1,
42+
"pagination": {
43+
"limit": 100,
44+
"hasNext": false
45+
}
46+
}
47+
```
48+
49+
### Required Fields
50+
51+
- `claims`: Array of claim objects
52+
- `claims[].id`: Unique identifier for the claim
53+
- `claims[].broadcastableMessage`: Hex-encoded BIP322 broadcastable message (optional)
54+
55+
## Sample Data
56+
57+
The repository includes `sample-claims.json` with test data that demonstrates the script functionality. Note that the test data contains mock transaction hex values that will fail verification, but this is expected and demonstrates how the script handles both success and failure cases.
58+
59+
## Functions Used
60+
61+
### `deserializeBIP322BroadcastableMessage(hex: string)`
62+
63+
- **Purpose**: Deserializes a hex-encoded BIP322 broadcastable message
64+
- **Input**: Hex string containing serialized BIP322 message
65+
- **Output**: `BIP322MessageBroadcastable` object containing transaction hex and message info
66+
67+
### `generateBIP322MessageListAndVerifyFromMessageBroadcastable(messages: BIP322MessageBroadcastable[], coinName: string)`
68+
69+
- **Purpose**: Verifies BIP322 messages and extracts address/message pairs
70+
- **Input**: Array of deserialized BIP322 messages and coin name
71+
- **Output**: Array of `{address: string, message: string}` objects
72+
- **Supported Coins**: "btc", "tbtc4"
73+
74+
## Output
75+
76+
The script provides detailed output showing:
77+
78+
1. JSON file parsing results
79+
2. Claims processing summary
80+
3. Message extraction details
81+
4. Deserialization results for each message
82+
5. Verification results or detailed error information
83+
6. Final summary with counts and extracted message information
84+
85+
## Error Handling
86+
87+
The script handles various error conditions:
88+
89+
- **File not found**: Clear error message with file path
90+
- **Invalid JSON**: Parse error indication
91+
- **Deserialization failures**: Per-message error reporting
92+
- **Verification failures**: Detailed error messages with fallback to show extracted data
93+
- **Unsupported coin names**: Clear error about supported values
94+
95+
## Development Notes
96+
97+
This script is designed as a usage example for BitGo's BIP322 utilities. In production environments:
98+
99+
1. Use actual BIP322 transaction data with valid Bitcoin transaction hex
100+
2. Ensure broadcastable messages are properly formatted
101+
3. Handle network-specific addresses and script types appropriately
102+
4. Implement proper error recovery and logging
103+
104+
## Example Output
105+
106+
```
107+
Processing BIP322 claims from: sample-claims.json
108+
Coin: btc
109+
110+
Status: success
111+
Total claims: 3
112+
113+
Extracting broadcastable messages...
114+
Claim 1 (ID: claim-001): Found broadcastable message
115+
Claim 2 (ID: claim-002): Found broadcastable message
116+
Claim 3 (ID: claim-003): No broadcastable message found
117+
118+
Found 2 broadcastable message(s)
119+
120+
Deserializing BIP322 broadcastable messages...
121+
Deserializing message 1...
122+
✓ Successfully deserialized message 1
123+
Transaction hex length: 6
124+
Message info count: 1
125+
Message 1: Address: someAddress, Script type: p2sh
126+
127+
=== SUMMARY ===
128+
Total claims processed: 3
129+
Broadcastable messages found: 2
130+
Successfully deserialized: 2
131+
Message info extracted: 2
132+
```

‎examples/ts/process-bip322-claims.ts‎

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
/**
2+
* Process BIP322 broadcastable messages from JSON claims data
3+
*
4+
* This script reads a JSON file containing an array of claims, each with a
5+
* broadcastableMessage string. It extracts and deserializes the messages,
6+
* then verifies them using BitGo's BIP322 utilities.
7+
*
8+
* Usage:
9+
* npx tsx process-bip322-claims.ts [path-to-json-file] [coin-name]
10+
*
11+
* Example:
12+
* npx tsx process-bip322-claims.ts sample-claims.json btc
13+
*
14+
* Copyright 2025, BitGo, Inc. All Rights Reserved.
15+
*/
16+
17+
import * as fs from 'fs';
18+
import * as path from 'path';
19+
import { transaction } from '@bitgo/abstract-utxo';
20+
21+
interface ClaimData {
22+
id: string;
23+
broadcastableMessage: string;
24+
[key: string]: any;
25+
}
26+
27+
interface ClaimsResponse {
28+
status: string;
29+
claims: ClaimData[];
30+
count: number;
31+
pagination?: {
32+
limit: number;
33+
hasNext: boolean;
34+
};
35+
}
36+
37+
/**
38+
* Process BIP322 broadcastable messages from a JSON file
39+
* @param filePath - Path to the JSON file containing claims data
40+
* @param coinName - The coin name (e.g., 'btc', 'tbtc4')
41+
*/
42+
async function processBIP322Claims(filePath: string, coinName: string): Promise<void> {
43+
try {
44+
console.log(`Processing BIP322 claims from: ${filePath}`);
45+
console.log(`Coin: ${coinName}`);
46+
console.log('');
47+
48+
// Read and parse the JSON file
49+
const jsonData = fs.readFileSync(filePath, 'utf8');
50+
const claimsData: ClaimsResponse = JSON.parse(jsonData);
51+
52+
console.log(`Status: ${claimsData.status}`);
53+
console.log(`Total claims: ${claimsData.count}`);
54+
console.log('');
55+
56+
if (!claimsData.claims || claimsData.claims.length === 0) {
57+
console.log('No claims found in the data.');
58+
return;
59+
}
60+
61+
// Extract broadcastable messages from claims
62+
const broadcastableMessages: string[] = [];
63+
64+
console.log('Extracting broadcastable messages...');
65+
claimsData.claims.forEach((claim, index) => {
66+
if (claim.broadcastableMessage) {
67+
broadcastableMessages.push(claim.broadcastableMessage);
68+
console.log(` Claim ${index + 1} (ID: ${claim.id}): Found broadcastable message`);
69+
} else {
70+
console.log(` Claim ${index + 1} (ID: ${claim.id}): No broadcastable message found`);
71+
}
72+
});
73+
74+
if (broadcastableMessages.length === 0) {
75+
console.log('No broadcastable messages found in any claims.');
76+
return;
77+
}
78+
79+
console.log(`\nFound ${broadcastableMessages.length} broadcastable message(s)`);
80+
console.log('');
81+
82+
// Deserialize each broadcastable message
83+
console.log('Deserializing BIP322 broadcastable messages...');
84+
const deserializedMessages = [];
85+
86+
for (let i = 0; i < broadcastableMessages.length; i++) {
87+
try {
88+
const message = broadcastableMessages[i];
89+
console.log(` Deserializing message ${i + 1}...`);
90+
91+
const deserializedMessage = transaction.bip322.deserializeBIP322BroadcastableMessage(message);
92+
deserializedMessages.push(deserializedMessage);
93+
94+
console.log(` ✓ Successfully deserialized message ${i + 1}`);
95+
console.log(` Transaction hex length: ${deserializedMessage.txHex.length}`);
96+
console.log(` Message info count: ${deserializedMessage.messageInfo.length}`);
97+
98+
// Log details of each message info
99+
deserializedMessage.messageInfo.forEach((info, infoIndex) => {
100+
console.log(` Message ${infoIndex + 1}: Address: ${info.address}, Script type: ${info.scriptType}`);
101+
});
102+
} catch (error) {
103+
console.error(` ✗ Failed to deserialize message ${i + 1}:`, error.message);
104+
}
105+
}
106+
107+
if (deserializedMessages.length === 0) {
108+
console.log('No messages were successfully deserialized.');
109+
return;
110+
}
111+
112+
console.log(`\nSuccessfully deserialized ${deserializedMessages.length} message(s)`);
113+
console.log('');
114+
115+
// Process deserialized messages with BIP322 verification
116+
console.log('Verifying and generating message list...');
117+
console.log('Note: Verification may fail with test data if transaction hex is not valid Bitcoin data');
118+
console.log('');
119+
120+
try {
121+
const verifiedResults = transaction.bip322.generateBIP322MessageListAndVerifyFromMessageBroadcastable(
122+
deserializedMessages,
123+
coinName
124+
);
125+
126+
console.log(`✓ Successfully verified and processed all messages`);
127+
console.log(`\nResults (${verifiedResults.length} verified message(s)):`);
128+
console.log('');
129+
130+
verifiedResults.forEach((result, index) => {
131+
console.log(`${index + 1}. Address: ${result.address}`);
132+
console.log(` Message: ${result.message}`);
133+
console.log('');
134+
});
135+
136+
// Summary
137+
console.log('=== SUMMARY ===');
138+
console.log(`Total claims processed: ${claimsData.claims.length}`);
139+
console.log(`Broadcastable messages found: ${broadcastableMessages.length}`);
140+
console.log(`Successfully deserialized: ${deserializedMessages.length}`);
141+
console.log(`Successfully verified: ${verifiedResults.length}`);
142+
} catch (error) {
143+
console.error('✗ Failed to verify messages:', error.message);
144+
console.log('');
145+
console.log('This is expected when using test data with invalid transaction hex.');
146+
console.log('In production, you would use actual BIP322 transaction data.');
147+
console.log('');
148+
149+
// Show what would have been extracted from the messages
150+
console.log('However, we can still show the extracted message information:');
151+
console.log('');
152+
153+
const extractedInfo = [];
154+
deserializedMessages.forEach((message, msgIndex) => {
155+
message.messageInfo.forEach((info, infoIndex) => {
156+
extractedInfo.push({
157+
address: info.address,
158+
message: info.message,
159+
scriptType: info.scriptType,
160+
pubkeys: info.pubkeys,
161+
source: `Message ${msgIndex + 1}, Info ${infoIndex + 1}`,
162+
});
163+
});
164+
});
165+
166+
extractedInfo.forEach((info, index) => {
167+
console.log(`${index + 1}. Address: ${info.address}`);
168+
console.log(` Message: ${info.message}`);
169+
console.log(` Script Type: ${info.scriptType}`);
170+
console.log(` Public Keys: ${info.pubkeys.join(', ')}`);
171+
console.log(` Source: ${info.source}`);
172+
console.log('');
173+
});
174+
175+
// Summary
176+
console.log('=== SUMMARY ===');
177+
console.log(`Total claims processed: ${claimsData.claims.length}`);
178+
console.log(`Broadcastable messages found: ${broadcastableMessages.length}`);
179+
console.log(`Successfully deserialized: ${deserializedMessages.length}`);
180+
console.log(`Verification failed (expected with test data): ${deserializedMessages.length}`);
181+
console.log(`Message info extracted: ${extractedInfo.length}`);
182+
}
183+
} catch (error) {
184+
console.error('Error processing BIP322 claims:', error.message);
185+
186+
if (error.code === 'ENOENT') {
187+
console.error(`File not found: ${filePath}`);
188+
} else if (error instanceof SyntaxError) {
189+
console.error('Invalid JSON format in file');
190+
}
191+
192+
process.exit(1);
193+
}
194+
}
195+
196+
/**
197+
* Main function to handle command line arguments and run the processor
198+
*/
199+
async function main(): Promise<void> {
200+
const args = process.argv.slice(2);
201+
202+
if (args.length !== 2) {
203+
console.log('Usage: npx tsx process-bip322-claims.ts <json-file> <coin-name>');
204+
console.log('');
205+
console.log('Arguments:');
206+
console.log(' json-file Path to JSON file containing claims data');
207+
console.log(' coin-name Coin name (e.g., "btc", "tbtc4")');
208+
console.log('');
209+
console.log('Example:');
210+
console.log(' npx tsx process-bip322-claims.ts sample-claims.json btc');
211+
process.exit(1);
212+
}
213+
214+
const [filePath, coinName] = args;
215+
216+
// Resolve file path relative to current working directory
217+
const resolvedPath = path.resolve(filePath);
218+
219+
await processBIP322Claims(resolvedPath, coinName);
220+
}
221+
222+
// Run the main function
223+
main().catch((error) => {
224+
console.error('Unexpected error:', error);
225+
process.exit(1);
226+
});

‎examples/ts/sample-claims.json‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
{
2+
"status": "success",
3+
"claims": [
4+
{
5+
"id": "claim-001",
6+
"userId": "user123",
7+
"amount": "1000000",
8+
"broadcastableMessage": "7b227478486578223a22303130323033222c226d657373616765496e666f223a5b7b2261646472657373223a22736f6d6541646472657373222c226d657373616765223a22736f6d654d657373616765222c227075626b657973223a5b227075626b657931222c227075626b657932225d2c2273637269707454797065223a2270327368227d5d7d",
9+
"timestamp": "2025-01-08T10:00:00Z",
10+
"status": "pending"
11+
},
12+
{
13+
"id": "claim-002",
14+
"userId": "user456",
15+
"amount": "2000000",
16+
"broadcastableMessage": "7b227478486578223a22303430353036222c226d657373616765496e666f223a5b7b2261646472657373223a22616e6f7468657241646472657373222c226d657373616765223a22616e6f746865724d657373616765222c227075626b657973223a5b227075626b657933222c227075626b657934225d2c2273637269707454797065223a2270327368227d5d7d",
17+
"timestamp": "2025-01-08T10:05:00Z",
18+
"status": "pending"
19+
},
20+
{
21+
"id": "claim-003",
22+
"userId": "user789",
23+
"amount": "500000",
24+
"timestamp": "2025-01-08T10:10:00Z",
25+
"status": "processed"
26+
}
27+
],
28+
"count": 3,
29+
"pagination": {
30+
"limit": 100,
31+
"hasNext": false
32+
}
33+
}

0 commit comments

Comments
 (0)