SDK Reference: Type Conversions

The CRE TypeScript SDK uses Protocol Buffers under the hood. Each protobuf message generates two TypeScript representations:

• Type (runtime form): Uses native binary types like Uint8Array and bigint. These are what the SDK returns from .result() calls.
• TypeJson (JSON-serializable form): Uses string and plain objects. These are what you pass into SDK methods when constructing requests.

Conversion table

This table shows how protobuf types map to their TypeScript runtime and JSON-serializable forms.

ProtoBigInt

BigInt is a CRE-specific protobuf type used to represent arbitrarily large integers. It appears in block numbers, account balances, gas values, and other EVM-related fields.

Structure

The protobuf BigInt encodes a signed arbitrary-precision integer as two fields:

Converting between bigint and ProtoBigInt

Use the SDK helpers to convert between native JavaScript bigint and the protobuf format:

Native bigint to protobuf BigIntJson (for request objects):

import { blockNumber, bigintToProtoBigInt } from "@chainlink/cre-sdk"

// blockNumber() is a convenience alias for bigintToProtoBigInt()
const block = blockNumber(12345678n)
// → { absVal: "ALxhTg==", sign: "1" }

// Equivalent:
const block2 = bigintToProtoBigInt(12345678n)

Protobuf BigInt to native bigint (for response processing):

import { protoBigIntToBigint } from "@chainlink/cre-sdk"

const header = evmClient.headerByNumber(runtime, {}).result()
const blockNum = protoBigIntToBigint(header.header.blockNumber)
// → e.g., 12345678n

Special constants

The SDK provides pre-built BigIntJson constants for common block reference values:

import { LATEST_BLOCK_NUMBER, LAST_FINALIZED_BLOCK_NUMBER } from "@chainlink/cre-sdk"

// LATEST_BLOCK_NUMBER → most recent mined block
// LAST_FINALIZED_BLOCK_NUMBER → most recent finalized block

These are negative sentinel values that the CRE platform interprets as symbolic references rather than literal block heights.

Common patterns

Reading a balance and doing arithmetic:

import { EVMClient, getNetwork, protoBigIntToBigint, LAST_FINALIZED_BLOCK_NUMBER } from "@chainlink/cre-sdk"

const balance = evmClient
  .balanceAt(runtime, {
    account: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb2",
    blockNumber: LAST_FINALIZED_BLOCK_NUMBER,
  })
  .result()

// balance.balance is already a native bigint — no conversion needed
const balanceInEth = balance.balance / 10n ** 18n

Specifying a custom block depth:

import { protoBigIntToBigint, blockNumber } from "@chainlink/cre-sdk"

// Get the latest block number
const header = evmClient.headerByNumber(runtime, {}).result()
const latest = protoBigIntToBigint(header.header.blockNumber)

// Query 100 blocks back
const contractCall = evmClient
  .callContract(runtime, {
    call: encodedCall,
    blockNumber: blockNumber(latest - 100n),
  })
  .result()

bytes fields

Protobuf bytes fields appear as Uint8Array in runtime types and as base64-encoded string in JSON types. When working with EVM data, you often need to convert between hex strings and these representations.

import { hexToBase64, bytesToHex, hexToBytes, base64ToHex } from "@chainlink/cre-sdk"

// Hex → base64 (for request objects)
const base64Data = hexToBase64("0xabcdef")

// base64 → hex (for processing responses)
const hexData = base64ToHex("q83v")

// Hex → Uint8Array
const bytes = hexToBytes("0xabcdef")

// Uint8Array → hex
const hex = bytesToHex(new Uint8Array([0xab, 0xcd, 0xef]))

See the EVM Client helper functions for the full list of conversion utilities.