6. Utilities

Complete reference for utility functions in the Amadeus Protocol SDK.

Crypto Utilities

Cryptographic operations for key generation and key derivation.

generateKeypair()

Generate a new BLS12-381 keypair.

import { generateKeypair } from '@amadeus-protocol/sdk'

const keypair = generateKeypair()

console.log('Public Key:', keypair.publicKey) // Base58 encoded
console.log('Private Key:', keypair.privateKey) // Base58 encoded seed

Returns: KeyPair with publicKey and privateKey (both Base58 encoded)

generatePrivateKey()

Generate a new random 64-byte seed.

import { generatePrivateKey } from '@amadeus-protocol/sdk'

const seed = generatePrivateKey() // Returns Uint8Array (64 bytes)

Returns: Uint8Array (64 bytes)

getPublicKey(seed: Uint8Array)

Derive a public key from a 64-byte seed.

import { getPublicKey } from '@amadeus-protocol/sdk'

const seed = generatePrivateKey()
const publicKey = getPublicKey(seed) // Returns Uint8Array (48 bytes)

Parameters:

• seed (Uint8Array): 64-byte seed

Returns: Uint8Array (48 bytes) - BLS12-381 public key

derivePublicKeyFromSeedBase58(seedBase58: string)

Derive public key from Base58-encoded seed.

import { derivePublicKeyFromSeedBase58 } from '@amadeus-protocol/sdk'

const publicKey = derivePublicKeyFromSeedBase58('5Kd3N...')
console.log('Public Key:', publicKey) // Base58 encoded

Parameters:

• seedBase58 (string): Base58-encoded seed

Returns: string - Base58-encoded public key

deriveSkAndSeed64FromBase58Seed(seedBase58: string)

Derive secret key and seed from Base58-encoded seed.

import { deriveSkAndSeed64FromBase58Seed } from '@amadeus-protocol/sdk'

const { sk, seed64 } = deriveSkAndSeed64FromBase58Seed('5Kd3N...')

console.log('Secret Key:', sk) // Uint8Array
console.log('Seed64:', seed64) // Uint8Array

Parameters:

• seedBase58 (string): Base58-encoded seed

Returns: { sk: Uint8Array, seed64: Uint8Array }

Encoding Utilities

Convert between different binary formats and string encodings.

Base58 Encoding

toBase58(bytes: Uint8Array): string

Encode bytes to Base58 string.

import { toBase58 } from '@amadeus-protocol/sdk'

const bytes = new Uint8Array([1, 2, 3])
const encoded = toBase58(bytes)
console.log('Base58:', encoded)

Parameters:

• bytes (Uint8Array): Bytes to encode

Returns: string - Base58 encoded string

fromBase58(str: string): Uint8Array

Decode Base58 string to bytes.

import { fromBase58 } from '@amadeus-protocol/sdk'

const bytes = fromBase58('5Kd3N...')
console.log('Bytes:', bytes)

Parameters:

• str (string): Base58 string to decode

Returns: Uint8Array - Decoded bytes

Base64 Encoding

uint8ArrayToBase64(bytes: Uint8Array): string

Convert Uint8Array to Base64 string.

import { uint8ArrayToBase64 } from '@amadeus-protocol/sdk'

const bytes = new Uint8Array([1, 2, 3])
const base64 = uint8ArrayToBase64(bytes)
console.log('Base64:', base64)

Parameters:

• bytes (Uint8Array): Bytes to encode

Returns: string - Base64 encoded string

base64ToUint8Array(base64: string): Uint8Array

Convert Base64 string to Uint8Array.

import { base64ToUint8Array } from '@amadeus-protocol/sdk'

const bytes = base64ToUint8Array('AQID')
console.log('Bytes:', bytes)

Parameters:

• base64 (string): Base64 encoded string

Returns: Uint8Array - Decoded bytes

arrayBufferToBase64(buffer: ArrayBuffer): string

Convert ArrayBuffer to Base64 string.

import { arrayBufferToBase64 } from '@amadeus-protocol/sdk'

const buffer = new ArrayBuffer(8)
const base64 = arrayBufferToBase64(buffer)

Parameters:

• buffer (ArrayBuffer): Buffer to encode

Returns: string - Base64 encoded string

base64ToArrayBuffer(base64: string): ArrayBuffer

Convert Base64 string to ArrayBuffer.

import { base64ToArrayBuffer } from '@amadeus-protocol/sdk'

const buffer = base64ToArrayBuffer('AQID')

Parameters:

• base64 (string): Base64 encoded string

Returns: ArrayBuffer - Decoded buffer

Array Conversion

uint8ArrayToArrayBuffer(bytes: Uint8Array): ArrayBuffer

Convert Uint8Array to ArrayBuffer.

import { uint8ArrayToArrayBuffer } from '@amadeus-protocol/sdk'

const bytes = new Uint8Array([1, 2, 3])
const buffer = uint8ArrayToArrayBuffer(bytes)

Parameters:

• bytes (Uint8Array): The Uint8Array to convert

Returns: ArrayBuffer

arrayBufferToUint8Array(buffer: ArrayBuffer): Uint8Array

Convert ArrayBuffer to Uint8Array.

import { arrayBufferToUint8Array } from '@amadeus-protocol/sdk'

const buffer = new ArrayBuffer(8)
const bytes = arrayBufferToUint8Array(buffer)

Parameters:

• buffer (ArrayBuffer): The ArrayBuffer to convert

Returns: Uint8Array - View of the buffer

Serialization

Canonical serialization using VecPack format.

encode(value: SerializableValue): Uint8Array

Encode a value using VecPack canonical serialization.

import { encode } from '@amadeus-protocol/sdk'

const data = {
	foo: 'bar',
	count: 42,
	items: [1, 2, 3],
	nested: {
		value: true
	}
}

const encoded = encode(data)
console.log('Encoded:', encoded) // Uint8Array

Parameters:

• value: Serializable value (null, boolean, number, bigint, string, Uint8Array, array, object, Map)

Returns: Uint8Array - Encoded bytes

Supported Types:

• null

• boolean

• number / bigint

• string

• Uint8Array

• Arrays

• Objects / Maps

decode(bytes: Uint8Array | number[]): DecodedValue

Decode VecPack-encoded bytes.

import { decode } from '@amadeus-protocol/sdk'

const decoded = decode(encoded)
console.log('Decoded:', decoded)

Parameters:

• bytes (Uint8Array | number[]): Encoded bytes

Returns: DecodedValue - Decoded value

Conversion Utilities

Convert between human-readable amounts and atomic units.

toAtomicAma(amount: number): number

Convert AMA amount to atomic units.

import { toAtomicAma } from '@amadeus-protocol/sdk'

const atomic = toAtomicAma(1.5) // Returns 1500000000
console.log('Atomic units:', atomic)

Parameters:

• amount (number): Amount in AMA (e.g., 1.5)

Returns: number - Amount in atomic units

Note: AMA tokens use 9 decimal places.

fromAtomicAma(atomic: number | string): number

Convert atomic units to AMA amount.

import { fromAtomicAma } from '@amadeus-protocol/sdk'

const ama = fromAtomicAma(1500000000) // Returns 1.5
console.log('AMA:', ama)

Parameters:

• atomic (number | string): Amount in atomic units

Returns: number - Amount in AMA

Encryption Utilities

Password-based encryption for securing sensitive wallet data.

encryptWithPassword(plaintext: string, password: string): Promise<EncryptedPayload>

Encrypt plaintext using AES-GCM encryption with PBKDF2 key derivation.

import { encryptWithPassword } from '@amadeus-protocol/sdk'

const encrypted = await encryptWithPassword('sensitive data', 'my-password')

console.log('Encrypted Data:', encrypted.encryptedData) // Base64
console.log('IV:', encrypted.iv) // Base64
console.log('Salt:', encrypted.salt) // Base64

// Store encrypted.encryptedData, encrypted.iv, encrypted.salt

Parameters:

• plaintext (string): Data to encrypt

• password (string): Password for encryption

Returns: Promise<EncryptedPayload> - Object containing:

• encryptedData (string): Base64-encoded encrypted data

• iv (string): Base64-encoded initialization vector

• salt (string): Base64-encoded salt

Security Features:

• AES-GCM encryption with 256-bit keys

• PBKDF2 key derivation with 100,000 iterations

• Unique salt and IV for each encryption

• Authenticated encryption (prevents tampering)

decryptWithPassword(payload: EncryptedPayload, password: string): Promise<string>

Decrypt encrypted data using the provided password.

import { decryptWithPassword } from '@amadeus-protocol/sdk'

const decrypted = await decryptWithPassword(encrypted, 'my-password')
console.log('Decrypted:', decrypted)

Parameters:

• payload (EncryptedPayload): Encrypted payload with encryptedData, iv, and salt

• password (string): Password used for encryption

Returns: Promise<string> - Decrypted plaintext

Throws: Error if decryption fails (wrong password or corrupted data)

generateSalt(): Uint8Array

Generate a cryptographically secure random salt.

import { generateSalt } from '@amadeus-protocol/sdk'

const salt = generateSalt() // Returns Uint8Array (16 bytes)

Returns: Uint8Array - Random salt (16 bytes / 128 bits)

generateIV(): Uint8Array

Generate a cryptographically secure random IV for AES-GCM.

import { generateIV } from '@amadeus-protocol/sdk'

const iv = generateIV() // Returns Uint8Array (12 bytes)

Returns: Uint8Array - Random IV (12 bytes / 96 bits)

deriveKey(password: string, salt: Uint8Array | ArrayBuffer): Promise<CryptoKey>

Derive an AES-GCM key from a password using PBKDF2.

import { deriveKey, generateSalt } from '@amadeus-protocol/sdk'

const salt = generateSalt()
const key = await deriveKey('my-password', salt)

Parameters:

• password (string): Password string

• salt (Uint8Array | ArrayBuffer): Salt for key derivation

Returns: Promise<CryptoKey> - Derived AES-GCM key (256 bits)

Constants

AMADEUS_PUBLIC_KEY_BYTE_LENGTH

Byte length of BLS12-381 public key: 48

AMADEUS_SEED_BYTE_LENGTH

Byte length of seed: 64

AMA_TOKEN_DECIMALS

Number of decimal places for AMA tokens: 9

AMA_TOKEN_DECIMALS_MULTIPLIER

Multiplier for conversions: 1000000000 (10^9)

AMA_TRANSFER_FEE

Network transfer fee: 0.02

EXPLORER_URL

Default explorer URL: https://explorer.ama.one

NODE_API_URL

Default node API URL: https://nodes.amadeus.bot/api

Usage Examples

Complete Encryption Flow

import { encryptWithPassword, decryptWithPassword, generateKeypair } from '@amadeus-protocol/sdk'

// Generate keypair
const keypair = generateKeypair()

// Encrypt private key
const encrypted = await encryptWithPassword(keypair.privateKey, 'user-password')

// Store encrypted data
localStorage.setItem('encryptedData', encrypted.encryptedData)
localStorage.setItem('iv', encrypted.iv)
localStorage.setItem('salt', encrypted.salt)

// Later: Decrypt private key
const encryptedPayload = {
	encryptedData: localStorage.getItem('encryptedData')!,
	iv: localStorage.getItem('iv')!,
	salt: localStorage.getItem('salt')!
}

const privateKey = await decryptWithPassword(encryptedPayload, 'user-password')

Address Validation

import { fromBase58, AMADEUS_PUBLIC_KEY_BYTE_LENGTH } from '@amadeus-protocol/sdk'

function isValidAddress(address: string): boolean {
	try {
		const bytes = fromBase58(address)
		return bytes.length === AMADEUS_PUBLIC_KEY_BYTE_LENGTH
	} catch {
		return false
	}
}

Amount Conversion

import { toAtomicAma, fromAtomicAma } from '@amadeus-protocol/sdk'

// Convert for transaction
const amount = 10.5
const atomic = toAtomicAma(amount) // 10500000000

// Convert for display
const display = fromAtomicAma(atomic) // 10.5

Next Steps

• Examples: See complete utility usage examples

• Best Practices: Security and development guidelines

• API Modules: Learn about API endpoints