@turnkey/encoding

Encoding and decoding utilities

@turnkey/encoding provides pure-JS encoding and decoding utilities used internally throughout the Turnkey SDK. It handles base64url, hex, and Base58 conversions without runtime dependencies on Node.js built-ins or browser globals.

This is primarily an internal package. Its functions are consumed by @turnkey/http, @turnkey/crypto, @turnkey/api-key-stamper, and other SDK packages. You are welcome to use these utilities in your own code, but be aware that interfaces may change between major versions.

Installation

npm

npm install @turnkey/encoding

Hex utilities

uint8ArrayToHexString

Converts a Uint8Array into a lowercase hex string.

import { uint8ArrayToHexString } from "@turnkey/encoding";

uint8ArrayToHexString(new Uint8Array([0xde, 0xad, 0xbe, 0xef]));
// => "deadbeef"

input · Uint8Array · required

The byte array to convert.

uint8ArrayFromHexString

Creates a Uint8Array from a hex string. Optionally pads the result to a target byte length.

import { uint8ArrayFromHexString } from "@turnkey/encoding";

uint8ArrayFromHexString("deadbeef");
// => Uint8Array([0xde, 0xad, 0xbe, 0xef])

// With target length — pads with leading zero bytes
uint8ArrayFromHexString("ff", 4);
// => Uint8Array([0x00, 0x00, 0x00, 0xff])

hexString · string · required

A valid even-length hex string (only [0-9A-Fa-f] characters).

length · number

Optional target length in bytes. The result will be left-padded with zero bytes if needed. Throws if the hex value cannot fit.

hexToAscii

Converts a hex string to an ASCII string by interpreting each byte pair as a character code.

import { hexToAscii } from "@turnkey/encoding";

hexToAscii("48656c6c6f");
// => "Hello"

normalizePadding

Pads or trims a Uint8Array to a target byte length by adding or removing leading zero bytes.

import { normalizePadding } from "@turnkey/encoding";

// Pad to 32 bytes
normalizePadding(new Uint8Array([0xff]), 32);

// Trim leading zeros
normalizePadding(new Uint8Array([0x00, 0x00, 0xff]), 1);
// => Uint8Array([0xff])

byteArray · Uint8Array · required

The input byte array.

targetLength · number · required

The desired output length in bytes.

Base64url utilities

stringToBase64urlString

Encodes a plain string to a base64url string. Uses a pure-JS btoa implementation that works in React Native and other environments without a native btoa.

import { stringToBase64urlString } from "@turnkey/encoding";

stringToBase64urlString("hello world");
// => "aGVsbG8gd29ybGQ"

hexStringToBase64url

Converts a hex string to a base64url string.

import { hexStringToBase64url } from "@turnkey/encoding";

hexStringToBase64url("deadbeef");
// => "3q2-7w"

// With target byte length (pads the hex buffer)
hexStringToBase64url("ff", 4);

base64StringToBase64UrlEncodedString

Converts a standard base64 string to base64url format by replacing + with -, / with _, and stripping = padding.

import { base64StringToBase64UrlEncodedString } from "@turnkey/encoding";

base64StringToBase64UrlEncodedString("aGVsbG8+d29ybGQ=");
// => "aGVsbG8-d29ybGQ"

base64UrlToBase64

Converts a base64url string back to a standard base64 string (restores +, /, and = padding).

import { base64UrlToBase64 } from "@turnkey/encoding";

base64UrlToBase64("aGVsbG8-d29ybGQ");
// => "aGVsbG8+d29ybGQ="

decodeBase64urlToString

Decodes a base64url string to a plain UTF-8 string.

import { decodeBase64urlToString } from "@turnkey/encoding";

decodeBase64urlToString("aGVsbG8gd29ybGQ");
// => "hello world"

atob

A pure-JS implementation of the standard atob function. Exported for environments that may not have it available globally.

import { atob } from "@turnkey/encoding";

atob("aGVsbG8=");
// => "hello"

Point encoding

pointEncode

Compresses an uncompressed P-256 public key (65 bytes, 0x04 prefix) into its 33-byte compressed form.

import { pointEncode } from "@turnkey/encoding";

const compressed = pointEncode(uncompressedPublicKeyBytes);
// Returns Uint8Array of 33 bytes (prefix 0x02 or 0x03 depending on y parity)

raw · Uint8Array · required

A 65-byte uncompressed public key starting with 0x04.

Base58 utilities

@turnkey/encoding exports bs58 and bs58check for Base58 and Base58Check encoding, used primarily for Solana key formats and credential bundles.

import { bs58, bs58check } from "@turnkey/encoding";

// Base58
bs58.encode(bytes);   // Uint8Array → base58 string
bs58.decode(string);  // base58 string → Uint8Array

// Base58Check (includes 4-byte checksum)
bs58check.encode(bytes);  // Uint8Array → base58check string
bs58check.decode(string); // base58check string → Uint8Array (throws on bad checksum)

Constants

import { DEFAULT_JWK_MEMBER_BYTE_LENGTH } from "@turnkey/encoding";

// DEFAULT_JWK_MEMBER_BYTE_LENGTH = 32
// Used when padding JWK key member fields (e.g. x, y coordinates)