Broxus JavaScript Core library

This library provides a comprehensive set of MobX-based models, and utilities for building JavaScript applications
that interact with TVM-based blockchains. It offers reactive state management for smart contracts, tokens,
DEX operations, and more.

Installation

Install the package as development dependency

``shell
npm install @broxus/js-core
`

`shell
yarn add @broxus/js-core
`

`shell
pnpm add @broxus/js-core
`

`shell
bun add @broxus/js-core
`

Core

$3

Base abstract class for creating reactive stores and services with built-in state and data management.

#### Interface

`typescript
abstract class AbstractStore<
T extends ObjectLiteral = ObjectLiteral,
U extends ObjectLiteral = ObjectLiteral
> {
protected _data: T
protected _state: U

setData(dataOrFn: Pick | ((prevData: Readonly) => Pick)): this
setData(key: K, value: T[K]): this

setState(stateOrFn: Pick | ((prevState: Readonly) => Pick)): this
setState(key: K, value?: U[K]): this

toJSON(): T
toJSON(both: true): [T, U]
}
`

#### Example

`typescript
import { AbstractStore } from '@broxus/js-core'
import { makeObservable, observable } from 'mobx'

interface UserData {
balance: string
name: string
}

interface UserState {
error?: string
isLoading: boolean
}

class UserStore extends AbstractStore {

constructor() {
super({
initialData: { name: '', balance: '0' },
initialState: { isLoading: false }
})
makeObservable(this)
}

async loadUser(address: string): Promise {
this.setState('isLoading', true)
try {
// Load user data
this.setData({ balance: '1000', name: 'User' })
}
catch (e: any) {
this.setState('error', e.message)
}
finally {
this.setState('isLoading', false)
}
}

}
`

$3

Abstract class for creating reactive smart contract wrappers with automatic state synchronization and blockchain event watching.

#### Interface

`typescript
abstract class SmartContractModel<
T extends SmartContractModelData | ObjectLiteral = SmartContractModelData,
U extends SmartContractModelState | ObjectLiteral = SmartContractModelState,
> extends AbstractStore {

readonly address: Address
readonly computedStorageData?: {
accountStatus: 'uninit' | 'frozen' | 'active' | 'nonexist'
deleteDueLimit: string
freezeDueLimit: string
storageFee: string
storageFeeDebt?: string
}
readonly contractState?: FullContractState
readonly isDeployed?: boolean
readonly isSyncing?: boolean
readonly syncedAt?: number

syncContractState(options?: { force?: boolean, ttl?: number }): Promise
watch?(callback?: (data: T, state: U) => void): Promise
unwatch?(): Promise
}
`

#### Example

`typescript
import { SmartContractModel } from '@broxus/js-core'
import { ProviderRpcClient } from 'everscale-inpage-provider'

interface CustomContractData {
owner: Address
value: string
}

class CustomContract extends SmartContractModel {
constructor(connection: ProviderRpcClient, address: Address) {
super(connection, address)
}

async sync() {
await this.syncContractState({ force: true })

if (!this.isDeployed) {
throw new Error('Contract not deployed')
}

// Fetch and set contract data
this.setData({
owner: / ... /,
value: / ... /
})
}
}
`

$3

Class for creating type-safe HTTP API endpoints with automatic URL generation and request handling.

#### Interface

`typescript
class Endpoint {
constructor(path: string, basePath?: string)

url(params?: TParams): string
request(routeParams?: TParams, requestInit?: RequestInit, bodyData?: TRequestBody): Promise
fetch(routeParams?: TParams, requestInit?: RequestInit, bodyData?: TRequestBody): Promise
post(routeParams?: TParams, requestInit?: RequestInit, bodyData?: TRequestBody): Promise
put(routeParams?: TParams, requestInit?: RequestInit, bodyData?: TRequestBody): Promise
delete(routeParams?: TParams, requestInit?: RequestInit, bodyData?: TRequestBody): Promise
}
`

#### Example

`typescript
import { Endpoint } from '@broxus/js-core'

interface TokenInfo {
symbol: string
decimals: number
}

// Create endpoint with route parameters
const tokenEndpoint = new Endpoint<{ address: string }, undefined, TokenInfo>(
'/tokens/:address',
'https://api.example.com'
)

// Use the endpoint
const tokenInfo = await tokenEndpoint.fetch({ address: '0:abc...' })
console.log(tokenInfo.symbol) // 'USDT'
`

Network Configuration

$3

Model for accessing masterchain network configuration parameters including gas prices, limits, and message forwarding fees.

#### Features

- Gas prices and limits for masterchain
- Message forwarding prices
- Storage fee parameters
- Real-time configuration updates watching

#### Interface

`typescript
class MasterChainConfig extends SmartContractModel {
readonly gasPrice: string
readonly gasLimit: string
readonly gasCredit: string
readonly blockGasLimit: string
readonly freezeDueLimit: string
readonly deleteDueLimit: string
readonly flatGasLimit: string
readonly flatGasPrice: string
readonly specialGasLimit: string

// Message forwarding prices
readonly lumpPrice: string
readonly bitPrice: string
readonly cellPrice: string
readonly ihrPriceFactor: string
readonly firstFrac: string
readonly nextFrac: string
}
`

#### Example

`typescript
import { MasterChainConfig } from '@broxus/js-core'

const masterConfig = await MasterChainConfig.create(
connection,
'-1:5555555555555555555555555555555555555555555555555555555555555555',
{ sync: true }
)

console.log(masterConfig.gasPrice) // '1000000'
console.log(masterConfig.gasLimit) // '1000000'
console.log(masterConfig.bitPrice) // '1'
console.log(masterConfig.cellPrice) // '500'

// Watch for configuration updates
await masterConfig.watch((data, state) => {
console.log('Gas price updated:', data.gasPrice)
})
`

$3

Model for accessing shardchain (workchain) network configuration parameters including gas prices, limits, and message forwarding fees.

#### Features

- Gas prices and limits for workchain
- Message forwarding prices
- Storage fee parameters
- Real-time configuration updates watching

#### Interface

`typescript
class ShardChainConfig extends SmartContractModel {
readonly gasPrice: string
readonly gasLimit: string
readonly gasCredit: string
readonly blockGasLimit: string
readonly freezeDueLimit: string
readonly deleteDueLimit: string
readonly flatGasLimit: string
readonly flatGasPrice: string
readonly specialGasLimit: string

// Message forwarding prices
readonly lumpPrice: string
readonly bitPrice: string
readonly cellPrice: string
readonly ihrPriceFactor: string
readonly firstFrac: string
readonly nextFrac: string
}
`

#### Example

`typescript
import { ShardChainConfig } from '@broxus/js-core'

const shardConfig = await ShardChainConfig.create(
connection,
'-1:5555555555555555555555555555555555555555555555555555555555555555',
{ sync: true }
)

console.log(shardConfig.gasPrice) // '1000000'
console.log(shardConfig.gasLimit) // '10000000'

// Use gas price for transaction calculations
const gasFee = BigInt(shardConfig.gasPrice) * BigInt(estimatedGas)
`

Models

$3

Model for TVM-based token (TIP-3 standard) with reactive state management and blockchain synchronization.

#### Features

- Automatic token details synchronization (symbol, decimals, totalSupply, etc.)
- Real-time blockchain state watching
- Token wallet management
- Balance queries

#### Interface

`typescript
class TvmToken
extends SmartContractModel {
static Utils: TvmTokenUtils
static Wallet: typeof TvmTokenWallet

readonly symbol: string
readonly decimals: number
readonly name: string
readonly totalSupply?: string
readonly rootOwnerAddress?: Address
readonly verified?: boolean

wallet(ownerAddress: Address | string): Promise
walletOf(ownerAddress: Address | string): Promise