@embarkai/core API

API reference for the core SDK package.

The @embarkai/core package provides authentication, ERC-4337 bundler operations, contract encoding utilities, encrypted vault backup, and server-side wallet management.


import { loginWithEmail, sendUserOperationWithRetry, encodeERC20Transfer } from '@embarkai/core';

Auth

Functions for user authentication and JWT token management.


function loginWithUserId(userId: string): Promise<LoginResponse>
function loginWithEmail(email: string): Promise<LoginResponse>
function loginWithTelegram(telegramData: object): Promise<LoginResponse>

Each login method initiates an authentication flow and returns a LoginResponse containing JWT tokens.

Token Management


function verifyToken(token: string): Promise<VerifyResponse>
function ensureValidToken(): Promise<string>
function getValidTokens(): Promise<JwtTokens>
function logout(): Promise<void>

verifyToken — validates a JWT and returns the decoded payload.
ensureValidToken — returns a valid access token, refreshing if expired.
getValidTokens — returns both access and refresh tokens, refreshing if needed.

Authenticated Requests


function authenticatedFetch(url: string, init?: RequestInit): Promise<Response>

A drop-in replacement for fetch that automatically attaches a valid bearer token.

JWT Token Manager


class JwtTokenManager {
  getAccessToken(): string | null
  getRefreshToken(): string | null
  setTokens(tokens: JwtTokens): void
  clear(): void
}
 
function createJwtTokenManager(storage: TokenStorage): JwtTokenManager
function configureJwtModule(options: { storage: TokenStorage }): void

jwtTokenManager — the default singleton instance.
configureJwtModule — sets up the token storage backend.

Token Storage Adapters


interface TokenStorage {
  get(key: string): string | null
  set(key: string, value: string): void
  remove(key: string): void
}
 
class LocalStorageAdapter implements TokenStorage {}
class MemoryStorageAdapter implements TokenStorage {}

JWT Helpers


function base64urlEncode(data: Uint8Array): string
function base64urlDecode(str: string): Uint8Array

Bundler

ERC-4337 bundler client for submitting and tracking user operations.

Sending Operations


function sendUserOperationRaw(op: PackedUserOperationV07, entrypoint?: string): Promise<string>
function sendUserOperationWithRetry(op: PackedUserOperationV07, options?: { retries?: number }): Promise<string>
function getUserOperationReceipt(hash: string): Promise<object>

sendUserOperationRaw — sends a packed user operation and returns the operation hash.
sendUserOperationWithRetry — wraps sendUserOperationRaw with automatic retry on transient network errors.
isNetworkError(error: unknown): boolean — helper to detect retryable errors.

Gas Estimation


function estimateUserOperationGas(op: UserOperationV07): Promise<GasEstimationResult>
function estimateUserOperationGasWithSignature(op: UserOperationV07, sig: string): Promise<GasEstimationResult>
function estimateUserOperationGasWithDynamicFees(op: UserOperationV07): Promise<GasEstimationResult>

Simulation & Validation


function simulateUserOperation(op: UserOperationV07): Promise<SimulationResult>
function validateUserOperation(op: UserOperationV07): Promise<boolean>

Fee Calculation


function calculateLegacyFees(chain: FeeChainContext): Promise<CalculatedFees>
function calculateDynamicFees(chain: FeeChainContext): Promise<CalculatedFees>
function calculateFastFees(chain: FeeChainContext): Promise<CalculatedFees>
function calculateEconomyFees(chain: FeeChainContext): Promise<CalculatedFees>
function getFeeEstimates(chain: FeeChainContext): Promise<CalculatedFees>
function getCurrentBaseFee(chain: FeeChainContext): Promise<bigint>
function getCurrentPriorityFee(chain: FeeChainContext): Promise<bigint>

Operation Helpers


function packUserOperationV07(op: UserOperationV07): PackedUserOperationV07
function createDummyUserOperation(): UserOperationV07
function createUserOperationWithDynamicFees(op: Partial<UserOperationV07>): Promise<UserOperationV07>

Public Client


function setPublicClient(client: object): void
function getPublicClient(): object
function hasPublicClient(): boolean

Constants


const ENTRYPOINT_V07: `0x${string}`
const ENTRYPOINT: `0x${string}`      // alias for ENTRYPOINT_V07
const DUMMY_SIGNATURE: `0x${string}`
const DEFAULT_FEE_CONFIG: FeeConfig
const CONSERVATIVE_FEE_CONFIG: FeeConfig

Contract Encoding (Utils)

Pre-built calldata encoders for common token standards.

ERC-20


function encodeERC20Transfer(to: `0x${string}`, amount: bigint): `0x${string}`
function encodeERC20Approve(spender: `0x${string}`, amount: bigint): `0x${string}`
function encodeERC20TransferFrom(from: `0x${string}`, to: `0x${string}`, amount: bigint): `0x${string}`

ERC-721


function encodeERC721TransferFrom(from: `0x${string}`, to: `0x${string}`, tokenId: bigint): `0x${string}`
function encodeERC721SafeTransferFrom(from: `0x${string}`, to: `0x${string}`, tokenId: bigint): `0x${string}`
function encodeERC721Approve(to: `0x${string}`, tokenId: bigint): `0x${string}`
function encodeERC721SetApprovalForAll(operator: `0x${string}`, approved: boolean): `0x${string}`

ERC-1155


function encodeERC1155SafeTransferFrom(from: `0x${string}`, to: `0x${string}`, id: bigint, amount: bigint, data: `0x${string}`): `0x${string}`
function encodeERC1155SafeBatchTransferFrom(from: `0x${string}`, to: `0x${string}`, ids: bigint[], amounts: bigint[], data: `0x${string}`): `0x${string}`
function encodeERC1155SetApprovalForAll(operator: `0x${string}`, approved: boolean): `0x${string}`

Generic Encoding


function encodeContractCall(abi: object[], functionName: string, args: unknown[]): `0x${string}`

Vault

Encrypted keyshare backup and recovery via the EmbarkAI vault service.


function checkBackupExists(userId: string): Promise<boolean>
function backupToVault(data: KeyshareBackupData, password: string): Promise<void>
function restoreFromVault(userId: string, password: string): Promise<KeyshareBackupData>
function configureVaultModule(options: { apiUrl: string }): void

Config & Clients

Server-side wallet manager and chain configuration.


function createServerWalletManager(config: ServerWalletManagerConfig): ServerWalletManager
 
class ServerWalletManager {
  getWallet(chainId: number): Promise<ServerWallet>
  getAllWallets(): Promise<ServerWallet[]>
}
 
class MemoryKeyshareStorage implements KeyshareStorage {}
 
const SUPPORTED_CHAINS: Record<number, ChainContext>

Types


interface UserOperationV07 { sender: string; nonce: bigint; /* ... */ }
interface PackedUserOperationV07 { /* packed fields */ }
interface GasEstimationResult { preVerificationGas: bigint; verificationGasLimit: bigint; callGasLimit: bigint }
interface SimulationResult { success: boolean; returnData?: string }
interface BundlerRpcError { code: number; message: string }
interface ChainContext { chainId: number; rpcUrl: string; bundlerUrl: string }
interface FeeChainContext extends ChainContext {}
interface FeeConfig { multiplier: number; maxRetries: number }
interface CalculatedFees { maxFeePerGas: bigint; maxPriorityFeePerGas: bigint }
interface JwtTokens { accessToken: string; refreshToken: string }
interface LoginResponse { tokens: JwtTokens; userId: string }
interface RefreshResponse { tokens: JwtTokens }
interface VerifyResponse { valid: boolean; payload: object }

Version


const VERSION: '0.1.0'