SDK for developing OPNet node plugins
npm install @btc-vision/plugin-sdk!Bitcoin
!TypeScript
!NodeJS
!NPM
!Gulp
!ESLint

TypeScript SDK for developing OPNet node plugins. Provides type definitions, interfaces, and base classes for plugin development.
``bash`
npm install @btc-vision/plugin-sdk
`typescript
import { PluginBase, IPluginContext, IBlockProcessedData, IReorgData } from '@btc-vision/plugin-sdk';
export default class MyPlugin extends PluginBase {
public async onLoad(context: IPluginContext): Promise
await super.onLoad(context);
this.context.logger.info('Plugin loaded!');
}
public async onBlockChange(block: IBlockProcessedData): Promise
this.context.logger.info(New block: ${block.blockNumber});
// Store data in plugin database
if (this.context.db) {
await this.context.db.collection('blocks').insertOne({
height: block.blockNumber.toString(),
hash: block.blockHash,
timestamp: Date.now(),
});
}
}
public async onReorg(reorg: IReorgData): Promise
// CRITICAL: Handle chain reorg - delete data for reorged blocks
if (this.context.db) {
await this.context.db.collection('blocks').deleteMany({
height: { $gte: reorg.fromBlock.toString() },
});
}
}
}
`
Every plugin requires a plugin.json manifest file:
`json`
{
"name": "my-plugin",
"version": "1.0.0",
"opnetVersion": "^1.0.0",
"main": "dist/index.jsc",
"target": "bytenode",
"type": "plugin",
"checksum": "sha256:...",
"author": { "name": "Your Name" },
"pluginType": "standalone",
"permissions": {
"database": {
"enabled": true,
"collections": ["my-plugin_blocks"]
},
"blocks": {
"onChange": true
}
}
}
See OIP-0003 for the complete specification.
| Interface | Description |
|-----------|-------------|
| IPlugin | Main plugin interface with all lifecycle hooks |IPluginContext
| | Runtime context provided to plugins |PluginBase
| | Abstract base class with no-op defaults |
#### Lifecycle Hooks
- onLoad(context) - Called when plugin is loadedonUnload()
- - Called when plugin is unloadedonEnable()
- - Called when plugin is enabledonDisable()
- - Called when plugin is disabled
#### Block Hooks
- onBlockPreProcess(block) - Before block processing (raw Bitcoin data)onBlockPostProcess(block)
- - After block processing (OPNet data)onBlockChange(block)
- - New block confirmed
#### Epoch Hooks
- onEpochChange(epoch) - Epoch number changedonEpochFinalized(epoch)
- - Epoch merkle tree complete
#### Mempool Hooks
- onMempoolTransaction(tx) - New transaction in mempool
#### Critical Hooks (BLOCKING)
- onReorg(reorg) - Chain reorganization (MUST handle for data consistency)onReindexRequired(check)
- - Reindex required at startuponPurgeBlocks(from, to)
- - Purge data for block range
| API | Description |
|-----|-------------|
| IPluginDatabaseAPI | MongoDB-like database access |IPluginFilesystemAPI
| | Sandboxed file system access |IPluginLogger
| | Logging with automatic plugin name prefix |IPluginConfig
| | Plugin configuration management |
Plugins declare required permissions in their manifest:
`typescript``
interface IPluginPermissions {
database?: {
enabled: boolean;
collections: string[];
};
blocks?: {
preProcess: boolean;
postProcess: boolean;
onChange: boolean;
};
epochs?: {
onChange: boolean;
onFinalized: boolean;
};
mempool?: {
txFeed: boolean;
};
api?: {
addEndpoints: boolean;
addWebsocket: boolean;
};
filesystem?: {
configDir: boolean;
tempDir: boolean;
};
}
Apache-2.0
See CONTRIBUTING.md for guidelines.