Transaction Types

Type definitions for transactions and broadcasting

Overview

Transaction-related types define the structure of Hive blockchain transactions, broadcasting results, and transaction status tracking.

TransactionType

Represents a complete Hive blockchain transaction.

ref_block_num · number

Reference block number for transaction expiration (uses lower 16 bits of a block number)

ref_block_prefix · number

Reference block prefix for transaction uniqueness (first 4 bytes of block ID)

expiration · string

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]

extensions · Extension[]

Transaction extensions (usually an empty array)

signatures · string[]

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.

tx_id · string

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 determined
• within_irreversible_block: Transaction is included in an irreversible block
• expired_irreversible: Transaction expired in an irreversible block
• too_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 determined
• within_mempool: Transaction is in the memory pool, not yet in a block
• within_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 block
• expired_irreversible: Transaction expired in an irreversible block
• too_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.

digest · Uint8Array

SHA-256 digest of the transaction data (32 bytes)

txId · string

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.

id · number

JSON-RPC request ID

jsonrpc · string

JSON-RPC version (“2.0”)

error · object

Error details object

error.code · number

Error code

error.message · string

Human-readable error message

error.data · any

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.

id · number

JSON-RPC request ID

jsonrpc · string

JSON-RPC version (“2.0”)

result · T

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[]
}

Some operations use specific extension formats:

// 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

1. Creation: Transaction is created with operations
2. Preparation: Reference block and expiration are set
3. Digest: Transaction is serialized and hashed
4. Signing: Private key signs the digest
5. Broadcasting: Signed transaction is sent to the network
6. Mempool: Transaction enters the memory pool (within_mempool)
7. Reversible Block: Transaction is included in a block (within_reversible_block)
8. 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