Skip to main content
The utils namespace provides helper functions for working with Hive blockchain operations, usernames, and witness configurations.

​
Import

import { utils } from 'hive-tx'

​
Functions

​
validateUsername

Validates a Hive username according to blockchain rules.
​
username
string
required
The username to validate
Returns: null if valid, or an error message string if invalid

​
Validation Rules

  • Must be 3-16 characters long
  • Must start with a lowercase letter
  • Can only contain lowercase letters, digits, and dashes
  • Must end with a lowercase letter or digit
  • Each segment (if using dots) must follow the same rules

​
Example

import { utils } from 'hive-tx'

// Valid username
const result1 = utils.validateUsername('alice')
console.log(result1) // null

// Invalid username - too short
const result2 = utils.validateUsername('ab')
console.log(result2) // "Account name should be longer."

// Invalid username - uppercase letter
const result3 = utils.validateUsername('Alice')
console.log(result3) // "Account name should start with a lowercase letter."

// Valid username with segment
const result4 = utils.validateUsername('alice.smith')
console.log(result4) // null
The function returns null for valid usernames and an error message string for invalid ones. This follows the pattern where absence of error indicates success.

​
makeBitMaskFilter

Creates a bitmask filter for use with get_account_history API calls to filter specific operation types.
​
allowedOperations
number[]
required
Array of operation IDs to include in the filter
Returns: any[] - A two-element array representing the bitmask (low and high bits)

​
Example

import { utils } from 'hive-tx'

// Filter for transfers and votes only
const filter = utils.makeBitMaskFilter([
  utils.operations.transfer,    // 2
  utils.operations.vote         // 0
])

// Use with get_account_history
import { callRPC } from 'hive-tx'

const history = await callRPC('condenser_api.get_account_history', [
  'username',
  -1,     // start
  1000,   // limit
  ...filter  // operation filter
])
Use this in combination with the utils.operations object to create efficient filters that only retrieve the operation types you need.

​
buildWitnessSetProperties

Builds a properly formatted witness_set_properties operation with serialized property values.
​
owner
string
required
The witness account name
​
props
WitnessProps
required
Object containing the witness properties to set
Returns: A tuple ['witness_set_properties', operation_body]

​
WitnessProps Interface

interface WitnessProps {
  account_creation_fee?: string
  account_subsidy_budget?: number
  account_subsidy_decay?: number
  key?: PublicKey | string
  maximum_block_size?: number
  new_signing_key?: PublicKey | string | null
  hbd_exchange_rate?: { base: string; quote: string }
  hbd_interest_rate?: number
  url?: string
}

​
Example

import { Transaction, utils, PrivateKey } from 'hive-tx'

// Build witness properties operation
const operation = utils.buildWitnessSetProperties('witness-account', {
  key: 'STM8GC13uCZbP44HzMLV6zPZGwVQ8Nt4Kji8PapsPiNq1BK153XTX',
  url: 'https://witness.example.com',
  hbd_interest_rate: 1000, // 10%
  account_creation_fee: '3.000 HIVE'
})

// Use in a transaction
const tx = new Transaction()
await tx.addOperation(operation[0], operation[1])

const key = PrivateKey.from('your-active-key')
tx.sign(key)
await tx.broadcast()
Properties are automatically serialized to hex format and sorted alphabetically. Do not manually serialize the values before passing them to this function.

​
Constants

​
operations

An object mapping operation names to their numeric IDs used by the Hive blockchain protocol.

​
Example

import { utils } from 'hive-tx'

console.log(utils.operations.vote)              // 0
console.log(utils.operations.comment)           // 1
console.log(utils.operations.transfer)          // 2
console.log(utils.operations.transfer_to_vesting) // 3
console.log(utils.operations.custom_json)       // 18

​
All Operation IDs

The operations object includes all Hive operations (both real and virtual): Account Operations:
  • vote: 0
  • comment: 1
  • transfer: 2
  • transfer_to_vesting: 3
  • withdraw_vesting: 4
  • account_create: 9
  • account_update: 10
  • account_update2: 43
Market Operations:
  • limit_order_create: 5
  • limit_order_cancel: 6
  • limit_order_create2: 21
  • convert: 8
  • collateralized_convert: 48
Witness Operations:
  • witness_update: 11
  • witness_set_properties: 42
  • account_witness_vote: 12
  • account_witness_proxy: 13
Custom Operations:
  • custom: 15
  • custom_json: 18
  • custom_binary: 35
Other Operations:
  • delete_comment: 17
  • comment_options: 19
  • claim_account: 22
  • create_claimed_account: 23
  • claim_reward_balance: 39
  • delegate_vesting_shares: 40
  • recurrent_transfer: 49
And many more including virtual operations. See the source code for the complete list.

​
Usage with Filters

import { utils, callRPC } from 'hive-tx'

// Create filter for specific operations
const filter = utils.makeBitMaskFilter([
  utils.operations.transfer,
  utils.operations.transfer_to_vesting,
  utils.operations.withdraw_vesting
])

// Get only transfer-related operations
const history = await callRPC('condenser_api.get_account_history', [
  'alice',
  -1,
  100,
  ...filter
])

Build docs developers (and LLMs) love

Get started for freeTalk to us