@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.

Installation

``bash
npm install @btc-vision/plugin-sdk
`

Quick Start

`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() },
});
}
}
}
`

Plugin Manifest (plugin.json)

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
}
}
}
`

API Reference

See OIP-0003 for the complete specification.

$3

| Interface | Description |
|-----------|-------------|
| IPlugin | Main plugin interface with all lifecycle hooks |
| IPluginContext | Runtime context provided to plugins |
| PluginBase | Abstract base class with no-op defaults |

$3

#### Lifecycle Hooks
- onLoad(context) - Called when plugin is loaded
- onUnload() - Called when plugin is unloaded
- onEnable() - Called when plugin is enabled
- onDisable() - 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 changed
- onEpochFinalized(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 startup
- onPurgeBlocks(from, to) - Purge data for block range

$3

| API | Description |
|-----|-------------|
| IPluginDatabaseAPI | MongoDB-like database access |
| IPluginFilesystemAPI | Sandboxed file system access |
| IPluginLogger | Logging with automatic plugin name prefix |
| IPluginConfig | Plugin configuration management |

$3

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;
};
}
``

License

Apache-2.0

Contributing

See CONTRIBUTING.md for guidelines.