Andrew Miller
5ae6dbfc3f
transaction.getInterchain / block.getInterchain take an optional
{ perChain?, chains? } that maps to prime-node's ?perChain=&chains= params.
Default (no options) returns one anchor per chain. Shared buildInterchainQuery
helper + InterchainOptions type, exported; jest-tested.
279 lines
6.5 KiB
Markdown
279 lines
6.5 KiB
Markdown
# Dragonchain Node.js SDK
|
|
|
|
Official Node.js and TypeScript SDK for interacting with Dragonchain blockchain nodes.
|
|
|
|
## Features
|
|
|
|
- 🔒 **HMAC-SHA256 Authentication** - Secure request signing
|
|
- 📦 **Full TypeScript Support** - Complete type definitions included
|
|
- 🌐 **Dual Package** - Works with both ESM and CommonJS
|
|
- ✅ **Comprehensive Testing** - Thoroughly tested with Jest
|
|
- 🎯 **Modern Best Practices** - Built with latest Node.js standards
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install @dragonchain-inc/prime-sdk
|
|
```
|
|
|
|
Or with yarn:
|
|
|
|
```bash
|
|
yarn add @dragonchain-inc/prime-sdk
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```typescript
|
|
import { DragonchainSDK } from '@dragonchain-inc/prime-sdk';
|
|
|
|
// Initialize the SDK
|
|
const sdk = new DragonchainSDK(
|
|
'your-public-id',
|
|
'your-auth-key-id',
|
|
'your-auth-key',
|
|
'https://your-dragonchain-endpoint.com'
|
|
);
|
|
|
|
// Check system health
|
|
await sdk.system.health();
|
|
|
|
// Get system status
|
|
const status = await sdk.system.status();
|
|
console.log(`Chain ID: ${status.id}, Level: ${status.level}`);
|
|
|
|
// Create a transaction
|
|
const txnResponse = await sdk.transaction.create({
|
|
txn_type: 'my-transaction-type',
|
|
payload: JSON.stringify({ message: 'Hello Dragonchain' }),
|
|
tag: 'example-tag',
|
|
});
|
|
console.log(`Created transaction: ${txnResponse.transaction_id}`);
|
|
```
|
|
|
|
## Using Configuration Files
|
|
|
|
The SDK supports loading credentials from YAML configuration files:
|
|
|
|
```yaml
|
|
default: my-chain-id
|
|
chains:
|
|
- name: my-chain
|
|
publicId: my-chain-id
|
|
authKeyId: my-auth-key-id
|
|
authKey: my-auth-key
|
|
endpoint: https://mychain.dragonchain.com
|
|
```
|
|
|
|
```typescript
|
|
import { DragonchainSDK } from '@dragonchain-inc/prime-sdk';
|
|
import { loadConfig, getDefaultChain } from '@dragonchain-inc/prime-sdk';
|
|
|
|
// Load config from file
|
|
const config = loadConfig('~/.dragonchain/credentials.yaml');
|
|
const chain = getDefaultChain(config);
|
|
|
|
if (chain) {
|
|
const sdk = new DragonchainSDK(
|
|
chain.publicId,
|
|
chain.authKeyId,
|
|
chain.authKey,
|
|
chain.endpoint
|
|
);
|
|
}
|
|
```
|
|
|
|
## API Reference
|
|
|
|
### System
|
|
|
|
```typescript
|
|
// Check system health
|
|
await sdk.system.health();
|
|
|
|
// Get system status
|
|
const status = await sdk.system.status();
|
|
```
|
|
|
|
### Transactions
|
|
|
|
```typescript
|
|
// Create a transaction
|
|
const response = await sdk.transaction.create({
|
|
txn_type: 'my-type',
|
|
payload: JSON.stringify({ data: 'example' }),
|
|
tag: 'optional-tag',
|
|
});
|
|
|
|
// Create multiple transactions
|
|
const bulkResponse = await sdk.transaction.createBulk({
|
|
transactions: [
|
|
{ txn_type: 'type1', payload: 'data1' },
|
|
{ txn_type: 'type2', payload: 'data2' },
|
|
],
|
|
});
|
|
|
|
// Get a transaction by ID
|
|
const txn = await sdk.transaction.get('transaction-id');
|
|
|
|
// List all transactions
|
|
const txns = await sdk.transaction.list();
|
|
```
|
|
|
|
### Transaction Types
|
|
|
|
```typescript
|
|
// Create a transaction type
|
|
await sdk.transactionType.create({
|
|
txn_type: 'my-new-type',
|
|
});
|
|
|
|
// Get a transaction type
|
|
const txnType = await sdk.transactionType.get('my-type');
|
|
|
|
// List all transaction types
|
|
const types = await sdk.transactionType.list();
|
|
|
|
// Delete a transaction type
|
|
await sdk.transactionType.delete('my-type');
|
|
```
|
|
|
|
### Blocks
|
|
|
|
```typescript
|
|
// Get a block by ID
|
|
const block = await sdk.block.get('block-id');
|
|
```
|
|
|
|
### Interchain trace
|
|
|
|
`transaction.getInterchain` / `block.getInterchain` trace a prime block to the
|
|
public-chain anchors covering it. By default they return the **first anchor per
|
|
chain** (anchor proofs are chained, so the earliest per chain is the meaningful
|
|
one). Tune with options:
|
|
|
|
```typescript
|
|
// Default: first anchor per chain (ETH, BTC, …)
|
|
const trace = await sdk.block.getInterchain('42');
|
|
|
|
// Up to 3 anchors per chain
|
|
await sdk.block.getInterchain('42', { perChain: 3 });
|
|
|
|
// All anchors, only the ETH-mainnet chain ("1"); "0" = BTC
|
|
await sdk.block.getInterchain('42', { perChain: 0, chains: ['1'] });
|
|
```
|
|
|
|
### Proof Measure (public, unauthenticated)
|
|
|
|
`proof-measure` is a separate, **public, unauthenticated** Dragonchain service
|
|
(the measured-immutability / "securedBy" metric) at
|
|
`https://proof-measure.dragonchain.com`. It needs no credentials. Decimal fields
|
|
are returned as strings (full precision) and timestamps as unix-second numbers.
|
|
|
|
```typescript
|
|
// Via the main SDK (targets the default public endpoint):
|
|
const sec = await sdk.proofMeasure.getSecurity('BTC', Math.floor(Date.now() / 1000) - 3600);
|
|
console.log(`BTC secured by ${sec.valueUsdFormatted} (${sec.raw.value} ${sec.raw.unit})`);
|
|
|
|
// Or standalone — no prime credentials needed:
|
|
import { ProofMeasureClient } from '@dragonchain-inc/prime-sdk';
|
|
|
|
const pm = new ProofMeasureClient(); // or new ProofMeasureClient({ baseURL: '...' })
|
|
|
|
const report = await pm.report({
|
|
transactionId: 'tx-123',
|
|
primeId: 'my-prime',
|
|
blockId: '42',
|
|
anchors: [
|
|
{ network: 'BTC', txHash: '0x...', timestamp: anchorUnix },
|
|
{ network: 'ETH', txHash: '0x...', timestamp: anchorUnix },
|
|
],
|
|
});
|
|
console.log(`Secured by ${report.totalValueUsdFormatted} across ${report.anchors.length} anchors`);
|
|
|
|
await pm.health();
|
|
```
|
|
|
|
## TypeScript Support
|
|
|
|
This SDK is written in TypeScript and includes complete type definitions:
|
|
|
|
```typescript
|
|
import {
|
|
DragonchainSDK,
|
|
TransactionCreateRequest,
|
|
TransactionCreateResponse,
|
|
SystemStatus,
|
|
} from '@dragonchain-inc/prime-sdk';
|
|
|
|
const sdk = new DragonchainSDK(
|
|
publicId,
|
|
authKeyId,
|
|
authKey,
|
|
baseURL
|
|
);
|
|
|
|
// Full type safety
|
|
const request: TransactionCreateRequest = {
|
|
txn_type: 'my-type',
|
|
payload: JSON.stringify({ foo: 'bar' }),
|
|
};
|
|
|
|
const response: TransactionCreateResponse = await sdk.transaction.create(request);
|
|
```
|
|
|
|
## Authentication
|
|
|
|
The SDK uses HMAC-SHA256 authentication with the following components:
|
|
|
|
1. **Public ID** - Your Dragonchain public identifier
|
|
2. **Auth Key ID** - Your authentication key identifier
|
|
3. **Auth Key** - Your secret authentication key
|
|
4. **Endpoint** - The base URL of your Dragonchain node
|
|
|
|
Each request is signed with:
|
|
- `Authorization` header: `DC1-HMAC-SHA256 {authKeyId}:{signature}`
|
|
- `Dragonchain` header: Your public ID
|
|
- `Timestamp` header: Unix timestamp of the request
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Run tests
|
|
npm test
|
|
|
|
# Run tests with coverage
|
|
npm run test:coverage
|
|
|
|
# Build the package
|
|
npm run build
|
|
|
|
# Lint the code
|
|
npm run lint
|
|
|
|
# Format the code
|
|
npm run format
|
|
```
|
|
|
|
## Requirements
|
|
|
|
- Node.js >= 16.0.0
|
|
- TypeScript >= 5.0.0 (for TypeScript projects)
|
|
|
|
## License
|
|
|
|
Apache-2.0
|
|
|
|
## Support
|
|
|
|
For issues and questions, please visit:
|
|
- Repository: https://git.dragonchain.com/dragonchain/dragonchain-prime-node-sdk
|
|
- Documentation: https://dragonchain-core-docs.dragonchain.com
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please feel free to submit a Pull Request.
|