Ctrlk
Buy ShellAcki Nacki docsFor Node Owners
For the complete documentation index, see llms.txt. This page is also available as Markdown.

API reference

Complete reference for all public/external functions, events, and error codes across the Accumulator contract system.

ShellAccumulatorRootUSDC

Source: contracts/accumulator/ShellAccumulatorRootUSDC.sol · Version: 1.0.2 &#xNAN;It will be available after the next node release

Entry points

buyShellFor(address buyer)

function buyShellFor(address buyer) public

Accepts eccUSDC attached to the message and processes a buy on behalf of buyer. Used by Exchange to forward purchases. Does not check for multi-currency messages — only verifies eccUSDC is present.

claimUSDC(uint16 D, uint64 orderId, address seller)

function claimUSDC(uint16 D, uint64 orderId, address seller) public

Called by a SellOrderLot to claim its eccUSDC payout. Verifies caller address deterministically, checks the order is sold (orderId <= soldPrefix[D]), sends eccUSDC to seller, then calls onReceiveUSDC on the lot.

Admin

setPubkey(uint256 pubkey)

function setPubkey(uint256 pubkey) public onlyOwnerPubkey accept

Replaces the owner public key. Only callable by the current owner (verified via msg.pubkey()).

Getters

getQueueState(uint16 D)

Returns the FIFO queue state for denomination D (1, 10, 100, or 1000).

  • nextId — next order ID to assign (1-based)

  • available — lots waiting to be matched by a buyer

  • soldPrefix — contiguous count of sold lots from the start

  • owedCount — sold lots that haven't been claimed yet

getDetails()

Returns high-level contract state.

  • sellerShellPool — total SHELL held from seller deposits (nanoSHELL)

  • usdcBalance — total eccUSDC tracked by the contract (microUSDC)

  • owedTotal — total eccUSDC owed to sellers awaiting claim (microUSDC)

getSellOrderAddress(uint16 D, uint64 orderId)

Computes the deterministic address of a lot contract given its denomination and order ID. Useful for off-chain address resolution without deploying.

owedUsdcTotal()

Returns total eccUSDC owed to all sellers across all denominations (microUSDC).

getSellerShellPool()

Returns total ECC SHELL in the seller pool (nanoSHELL).

getUsdcBalance()

Returns the eccUSDC balance tracked by the contract (microUSDC). This is the accounting balance, not necessarily the on-chain ECC balance.

getNacklInfo()

Returns NACKL emission state.

  • supply — current M(t) from the emission curve (nanoNACKL)

  • burned — total NACKL burned via redeemNACKL to date (nanoNACKL)

  • unixstart — emission start timestamp (Unix seconds)

The effective circulating supply is supply - burned.

getVersion()

Returns ("1.0.2", "ShellAccumulatorRootUSDC").

ShellSellOrderLot

Source: contracts/accumulator/ShellSellOrderLot.sol · Version: 1.0.2 &#xNAN;It will be available after the next node release

Entry points

claim()

Initiates eccUSDC payout claim. Sets _claimed = true and calls Root.claimUSDC(denom, orderId, owner). If the root rejects (order not yet sold), the bounced message resets _claimed = false via onBounce.

Can be called by anyone (no msg.sender check), but the payout always goes to _owner (the original seller).

onReceiveUSDC(uint128 amount)

Callback from the Root confirming payout was sent. Verifies amount == _denom * USDC_DECIMALS_FACTOR, emits OrderDestroyed, and self-destructs.

Getters

getDetails()

Returns all lot metadata.

  • root — parent Accumulator address

  • owner — seller address (receives eccUSDC payout)

  • denom — lot denomination (1, 10, 100, 1000)

  • orderId — FIFO position within the denomination queue

  • claimed — true if claim() was called and is pending or completed

getVersion()

Returns ("1.0.2", "ShellSellOrderLot").

Exchange

Source: contracts/exchange/Exchange.sol · Version: 1.0.4 &#xNAN;It will be available after the next node release

Entry points

onTransferReceived(address from, address to, uint128 value, uint128 balance)

ISubscriber callback from the Exchange's TIP-3 USDC wallet. Mints equivalent eccUSDC and sends it to from (the depositor). Only callable by _usdcWallet.

mintAndSend(address recipient, uint128 value, uint64 nonce)

Admin-only. Mints eccUSDC and sends to recipient. Requires nonce == _mintNonce + 1.

mintAndSendAccumulator(address buyer, uint128 value, uint64 nonce)

Admin-only. Mints eccUSDC and calls Accumulator.buyShellFor(buyer) with the minted eccUSDC attached. Requires whole eccUSDC units and nonce == _mintAccumulatorNonce + 1. Uses separate nonce space from mintAndSend.

Admin

setPubkey(uint256 pubkey)

Replaces the owner public key.

triggerTransaction(address txAddr)

Sends 1 vmshell to txAddr. Used to trigger Transaction contracts for wallet setup (e.g., SET_SUBSCRIBER_TYPE).

Getters

getUsdcWallet()

Returns the TIP-3 USDC TokenWallet address used for the bridge.

getOwnerPubkey()

Returns the current owner public key.

getTotalMinted()

Returns total eccUSDC minted by this contract across all methods (microUSDC).

getNonces()

Returns current nonces for both mint paths. The next valid nonce for each path is current + 1.

getVersion()

Returns ("1.0.4", "Exchange").

AccumulatorLib

Source: contracts/accumulator/libraries/AccumulatorLib.sol · Version: 1.0.2 &#xNAN;It will be available after the next node release

calculateSellOrderAddress(TvmCell code, address root, uint16 denom, uint64 orderId)

Computes the deterministic address of a SellOrderLot. The address is makeAddrStd(0, hash(stateInit)).

composeSellOrderStateInit(TvmCell code, address root, uint16 denom, uint64 orderId)

Builds the full stateInit for a lot: salted code + static variables _denom and _orderId.

buildSellOrderCode(TvmCell originalCode, address root)

Salts the lot code with abi.encode(versionLib, root). This binds the lot to a specific Root contract and library version.

Events

All events are emitted to external addresses (directed events) for off-chain subscription. The external address is constructed as address.makeAddrExtern(eventId, 256).

Root events

Event
Ext Addr
Fields
Emitted when

SellOrderCreated

610 + seller's address

(address seller, uint16 denom, uint64 orderId, uint128 shellAmount)

New lot created. Emitted twice: to addr 610 and to the seller's external address

ShellPurchased

611

(address buyer, uint128 usdcAmount, uint128 shellFromSellers, uint128 shellMinted)

Buy completed

UsdcClaimed

612

(uint64 orderId, uint16 denom, address seller, uint128 payout)

Seller claimed eccUSDC

NacklRedeemed

613

(address recipient, uint128 burnAmount, uint128 payout)

NACKL burned for USDC

MatchedOrders

617

(uint64 lastSold1, uint64 lastSold10, uint64 lastSold100, uint64 lastSold1000)

Updated soldPrefix values after a buy

Lot events

Event
Target
Fields

ClaimInitiated

internal

(uint64 orderId, uint16 denom, address owner)

OrderDestroyed

internal

(uint64 orderId, uint16 denom, uint128 amount)

Exchange events

Event
Ext Addr
Fields
Emitted when

UsdcMigrated

615

(address from, uint128 value)

TIP-3 USDC bridged to ECC

UsdcMinted

616

(address recipient, uint128 value)

Admin-minted eccUSDC (from mintAndSend and mintAndSendAccumulator)

Error Codes

Accumulator errors (Root + SellOrderLot)

Code
Name
Meaning

200

ERR_INVALID_DENOM

Denomination is not 1, 10, 100, or 1000

201

ERR_WRONG_SHELL_AMOUNT

SHELL amount doesn't divide evenly by SHELL_PER_USDC

202

ERR_WRONG_USDC_AMOUNT

eccUSDC amount mismatch in onReceiveUSDC or balance check

203

ERR_NOT_WHOLE_USDC

eccUSDC amount is not a whole number (not divisible by 10⁶)

204

ERR_ZERO_AMOUNT

Zero amount supplied

205

ERR_ORDER_NOT_SOLD

Lot's orderId > soldPrefix (not yet matched)

206

ERR_NO_OWED

No owed claims remaining for this denomination

207

ERR_INVALID_SENDER

Caller is not the expected contract

208

ERR_ALREADY_CLAIMED

claim() already called on this lot

209

ERR_NOT_OWNER

msg.pubkey() doesn't match owner

210

ERR_INSUFFICIENT_REDEEMABLE

Not enough free reserve for NACKL redemption

211

ERR_WRONG_CODE

(reserved)

212

ERR_WRONG_ADDRESS

Caller address doesn't match deterministic lot address

213

ERR_MULTIPLE_CURRENCIES

Message carries more than one ECC currency type

214

ERR_OVERFLOW

Amount exceeds uint64 max

Exchange errors

Code
Name
Meaning

204

ERR_ZERO_AMOUNT

Zero value

207

ERR_INVALID_SENDER

Caller is not the eccUSDC wallet

209

ERR_NOT_OWNER

msg.pubkey() doesn't match owner

213

ERR_NOT_WHOLE_USDC

Value not divisible by 10⁶

214

ERR_OVERFLOW

Value exceeds uint64 max

215

ERR_INVALID_NONCE

Nonce is not current + 1

Error code 213 means different things in different contracts: ERR_MULTIPLE_CURRENCIES in the Accumulator vs ERR_NOT_WHOLE_USDC in the Exchange. When debugging failed transactions, check which contract emitted the error.

Constants

Token IDs and decimals

Constant
Value
Used in

NACKL_ECC_ID

1

Root

SHELL_ECC_ID

2

Root

USDC_ECC_ID

3

Root, Exchange

SHELL_DECIMALS_FACTOR

1,000,000,000 (10⁹)

Root

USDC_DECIMALS_FACTOR

1,000,000 (10⁶)

Root, Exchange

SHELL_PER_USDC

100,000,000,000 (100 × 10⁹)

Root

NACKL emission

Constant
Value
Meaning

NACKL_T

10,400,000,000,000,000,000

Max supply cap (nanoNACKL)

NACKL_T_KM

10,400,104,000,000,000,000

T × (1 + K_M), K_M = 0.00001

NACKL_U_M_FP18

5,756,467,732

Growth rate × 10¹⁸

FP18

10¹⁸

Fixed-point scaling factor

INV_E_FP18

367,879,441,171,442,322

exp(-1) × 10¹⁸

Denominations

PreviousSell/Buy/Burn Flows
NextBee Engine Overview

Last updated