# Ordinals Parser Implementation Guide
This document outlines the structure and implementation of the `ordinals-parser` library, which provides a lightweight way to parse Bitcoin Ordinals inscriptions without requiring the full Ord codebase.
## Project Structure
The project is organized as follows:
```
ordinals-parser/
├── Cargo.toml # Main package manifest
├── README.md # User documentation
├── LICENSE # MIT license
├── IMPLEMENTATION.md # This implementation guide
├── src/
│ ├── lib.rs # Library entry point and documentation
│ ├── error.rs # Error types
│ ├── tag.rs # Inscription field tags
│ ├── inscription_id.rs # Inscription ID type
│ ├── inscription.rs # Inscription data structure
│ ├── envelope.rs # Envelope parsing
│ └── bin/
│ └── cli.rs # Command-line interface
└── examples/
├── parse_transaction.rs # Example using the library in Rust
├── typescript/ # TypeScript example (reference implementation)
│ ├── package.json
│ ├── tsconfig.json
│ └── parse-inscriptions.ts
└── python/ # Python example (reference implementation)
├── requirements.txt
└── parse_inscriptions.py
```
## Core Components
### 1. Error Handling (`error.rs`)
Custom error types for the library using `thiserror`. The error types are designed to be informative while maintaining compatibility with standard Rust error handling patterns.
### 2. Inscription ID (`inscription_id.rs`)
A unique identifier for inscriptions, consisting of a transaction ID and an index:
- Parses from string in the format `txid:index` or `txidi<index>`
- Supports serialization and deserialization
- Provides conversion to/from binary representation
### 3. Tags (`tag.rs`)
Defines the tags used in inscription fields according to the Ordinals protocol:
- Content type (tag = 1)
- Content encoding (tag = 9)
- Metadata (tag = 5)
- Metaprotocol (tag = 7)
- Parents (tag = 3)
- Delegate (tag = 11)
- Pointer (tag = 2)
- Properties (tag = 17)
- Rune (tag = 13)
### 4. Inscription (`inscription.rs`)
The main data structure representing an inscription with methods for:
- Accessing content type, body, and metadata
- Checking for content encoding
- Retrieving parent inscriptions
- Handling delegation
- Converting to/from Bitcoin scripts
The library also provides an `InscriptionBuilder` for creating new inscriptions using a fluent API.
### 5. Envelope Parsing (`envelope.rs`)
Core logic for parsing inscriptions from Bitcoin transactions:
- Supports both classic and modern inscription formats
- Extracts inscription data from transaction witness scripts
- Handles the Ordinals protocol envelope format
- Processes multiple inscriptions in a single transaction
- Detects JSON content within text/plain inscriptions
### 6. Library API (`lib.rs`)
Public API and re-exports of the main components with comprehensive documentation.
## Recent Improvements
1. **Enhanced JSON Detection**: The library now can detect and parse JSON content within text/plain inscriptions, supporting various protocols like BRC-20.
2. **Support for Modern Inscriptions**: Added support for parsing the newer P2TR-based inscription format that's become common in more recent transactions.
3. **CLI Improvements**: Enhanced CLI tool with better output formatting and JSON detection.
4. **Documentation**: Added extensive documentation with practical examples to make the library easier to use.
## Design Decisions
1. **Independence from Ord**: The library is completely independent of the Ord codebase, requiring only the Bitcoin crate and standard libraries.
2. **Minimal Dependencies**: Using only essential crates to ensure the library is lightweight.
3. **Flexible API**: Designed the API to accommodate various use cases, from simple parsing to creating complex inscriptions.
4. **Comprehensive Error Handling**: Makes integration with other systems more straightforward by providing clear error information.
5. **Future Extensibility**: The architecture allows for easy extension to support future Ordinals protocol enhancements.
## Usage Guidelines
### Performance Considerations
- When parsing large transactions with many inputs, consider that each input is examined separately.
- For applications with high throughput requirements, consider caching parsed results.
### Security Considerations
- The library focuses on parsing inscriptions rather than validating them.
- Applications should validate the content of inscriptions before processing, especially when working with binary or executable content.
### Compatibility
- Tested with both mainnet and testnet inscriptions
- Compatible with Bitcoin Core 24.0+ and libraries using bitcoin 0.30.x
## Future Development
Potential future enhancements include:
1. Async API for non-blocking operations
2. Additional serialization formats for inscriptions
3. Integration with other Bitcoin libraries
4. Advanced filtering capabilities for specific inscription types
5. Native bindings for other programming languages