Overview
Transaction-related types define the structure of Hive blockchain transactions, broadcasting results, and transaction status tracking.
TransactionType
Represents a complete Hive blockchain transaction.
Reference block number for transaction expiration (uses lower 16 bits of a block number)
Reference block prefix for transaction uniqueness (first 4 bytes of block ID)
Transaction expiration time in ISO 8601 format (e.g., “2024-03-04T12:00:00”)
operations
[OperationName, OperationBody<OperationName>][]
Array of operations to execute in this transaction. Each operation is a tuple of [operationName, operationBody]
Transaction extensions (usually an empty array)
Array of cryptographic signatures authorizing the transaction
Example Structure
const transaction: TransactionType = {
ref_block_num: 12345,
ref_block_prefix: 987654321,
expiration: "2024-03-04T12:30:00",
operations: [
['vote', {
voter: 'alice',
author: 'bob',
permlink: 'test-post',
weight: 10000
}]
],
extensions: [],
signatures: ['1f3b4c...']
}
BroadcastResult
Result returned after successfully broadcasting a transaction.
Unique transaction ID (hash) that can be used to track the transaction on the blockchain
status
'unknown' | 'within_irreversible_block' | 'expired_irreversible' | 'too_old'
Current status of the transaction:
unknown: Status cannot be determinedwithin_irreversible_block: Transaction is included in an irreversible blockexpired_irreversible: Transaction expired in an irreversible blocktoo_old: Transaction is too old to query
Example
import { Transaction } from 'hive-tx'
import { PrivateKey } from 'hive-tx/helpers'
const tx = new Transaction()
await tx.create([
['vote', {
voter: 'alice',
author: 'bob',
permlink: 'test-post',
weight: 10000
}]
])
const privateKey = PrivateKey.from('5J...')
const result = await tx.broadcast(privateKey)
console.log('Transaction ID:', result.tx_id)
console.log('Status:', result.status)
// Output:
// Transaction ID: 4b3c2a1...
// Status: within_irreversible_block
TransactionStatus
Detailed status information for a transaction query.
status
'unknown' | 'within_mempool' | 'within_reversible_block' | 'within_irreversible_block' | 'expired_reversible' | 'expired_irreversible' | 'too_old'
Detailed transaction status:
unknown: Status cannot be determinedwithin_mempool: Transaction is in the memory pool, not yet in a blockwithin_reversible_block: Transaction is in a reversible block (not yet final)within_irreversible_block: Transaction is in an irreversible block (final)expired_reversible: Transaction expired while in a reversible blockexpired_irreversible: Transaction expired in an irreversible blocktoo_old: Transaction is too old to track
Example
import { call } from 'hive-tx'
const status = await call('transaction_status_api', 'find_transaction', {
transaction_id: '4b3c2a1...'
})
console.log(status.status)
// Output: within_irreversible_block
DigestData
Transaction digest data used for signing and transaction ID generation.
SHA-256 digest of the transaction data (32 bytes)
Transaction ID derived from the digest (hex-encoded)
Example
import { Transaction } from 'hive-tx'
const tx = new Transaction()
await tx.create([
['transfer', {
from: 'alice',
to: 'bob',
amount: '10.000 HIVE',
memo: 'Payment'
}]
])
const digest = tx.digest()
console.log('Digest:', digest.digest)
console.log('Transaction ID:', digest.txId)
BroadcastError
Error response when transaction broadcast fails.
Human-readable error message
Additional error data (optional)
Example Error Handling
import { Transaction } from 'hive-tx'
import { PrivateKey } from 'hive-tx/helpers'
const tx = new Transaction()
try {
await tx.create([
['transfer', {
from: 'alice',
to: 'bob',
amount: '10.000 HIVE',
memo: ''
}]
])
const result = await tx.broadcast(PrivateKey.from('5J...'))
console.log('Success:', result.tx_id)
} catch (error) {
if (error.error) {
console.error('Broadcast failed:', error.error.message)
console.error('Error code:', error.error.code)
}
}
CallResponse
Generic API call response type.
API response result (generic type)
Example
import { call } from 'hive-tx'
import type { CallResponse } from 'hive-tx'
interface AccountInfo {
name: string
created: string
post_count: number
}
const response: CallResponse<AccountInfo> = await call(
'database_api',
'find_accounts',
{ accounts: ['alice'] }
)
console.log(response.result)
Extension Type
Flexible extension type used throughout the library.
type Extension = [] | [string, any] | any[]
Common Usage
Most operations use an empty array for extensions:
const operation = {
// ... operation fields
extensions: [] as Extension[]
}
// Comment options with beneficiaries
const commentOptions = {
author: 'alice',
permlink: 'post',
// ...
extensions: [[
{ account: 'bob', weight: 2500 },
{ account: 'charlie', weight: 2500 }
]]
}
// Recurrent transfer with pair_id
const recurrentTransfer = {
from: 'alice',
to: 'bob',
// ...
extensions: [
{ type: 0, value: { pair_id: 1 } }
]
}
Complete Transaction Example
import { Transaction } from 'hive-tx'
import { PrivateKey } from 'hive-tx/helpers'
import type {
TransactionType,
BroadcastResult,
DigestData
} from 'hive-tx'
async function createAndBroadcast() {
// Create transaction
const tx = new Transaction()
await tx.create([
['vote', {
voter: 'alice',
author: 'bob',
permlink: 'test-post',
weight: 10000
}],
['transfer', {
from: 'alice',
to: 'bob',
amount: '1.000 HIVE',
memo: 'Thanks for the post!'
}]
])
// Get transaction object
const txObject: TransactionType = tx.transaction
console.log('Transaction:', txObject)
// Get digest before signing
const digest: DigestData = tx.digest()
console.log('Transaction ID will be:', digest.txId)
// Sign and broadcast
const privateKey = PrivateKey.from('5J...')
const result: BroadcastResult = await tx.broadcast(privateKey)
console.log('Broadcast successful!')
console.log('TX ID:', result.tx_id)
console.log('Status:', result.status)
return result
}
createAndBroadcast()
Transaction Lifecycle
- Creation: Transaction is created with operations
- Preparation: Reference block and expiration are set
- Digest: Transaction is serialized and hashed
- Signing: Private key signs the digest
- Broadcasting: Signed transaction is sent to the network
- Mempool: Transaction enters the memory pool (
within_mempool)
- Reversible Block: Transaction is included in a block (
within_reversible_block)
- Irreversible: After ~45 seconds, block becomes irreversible (
within_irreversible_block)
Status Transitions
unknown
↓
within_mempool
↓
within_reversible_block → expired_reversible
↓
within_irreversible_block → expired_irreversible → too_old
