Bee Engine SDK — Integration Documentation

The page is under development

Getting Started

This section describes the minimal steps required to integrate Bee Engine SDK into your application and start client-side NACKL mining.

Repository with artifacts is here: https://github.com/gosh-sh/bee-engine

Integration Overview

Before users can start mining, you must complete the following steps:

1. Application Registration (for Mainnet)

2. Install Bee SDK

3. Integrate into your application (React + Vite example)

4. User Authorization via AN Wallet

5. Work with Bee Engine Miner API

Step 1. Application Registration

To connect your application to the Bee Engine system:

You must obtain your application identifier in the system: app_dapp_id.

• At the current stage of development, to obtain it, please contact us and provide to get it:

  • your App name;

  • App link;

  • link to your logo the image must be preliminarily converted into webp format

• In the future, the developer will:

  • deploy their own application smart contract system in the Acki Nacki blockchain

  • retrieve app_dapp_id, which will equal the DAPP ID of the first deployed contract

Why app_dapp_id is required

This identifier:

• Is required when initializing the Bee Engine Miner

• Is used for public mining key binding inside the Miner contract

• Is necessary for the user to authenticate in the developer’s application

In the example, insert it into the APP_ID variable.

Example:

const APP_ID = "your_app_dapp_id_here";

Step 2. Install Bee SDK

Install the SDK via npm:

npm install @teamgosh/bee-sdk

Step 3. Integration Example (React + Vite)

A minimal integration example is available in the repository :

File: App.tsx Folder: miner-react (download this folder)

This Example Demonstrates:

• Miner initialization

• Starting and stopping mining

• Subscribing to miner events (in progress)

• Using add_tap()

• Polling and waiting for mining keys to be propagated in the Miner contract (ensure_mining_keys_propagated)

• Retrieving the user’s Miner contract address (get_miner_address_by_wallet_name)

It is strongly recommended to use this example as the baseline for your integration.

Step 4. User Authorization (in progress)

To enable mining, users must authorize via Acki Nacki Wallet (AN Wallet).

Authorization Overview:

There are two user flows:

1. User already has an Acki Nacki Wallet

2. User does not have an Acki Nacki Wallet (in progress)

Flow 1 — User Already Has AN Wallet

If the user already has an Acki Nacki Wallet, the authorization process works as follows:

1. Collecting Information from the User

The developer needs to obtain:

• The AN Wallet name that the user will use to log in.

The AN Wallet name is a human-readable identifier that the user chooses when creating the wallet.

The bee-sdk abstracts all address-related operations internally, so the developer only needs the wallet name to interact with the system.

---

2. Mining Key Generation (Developer Side)

The developer must:

• Generate a Mining key pair.

Mining keys are cryptographic keys used to sign and submit mining results. These keys are generated by the application developer and are created separately for each application.

const resultOfGenKeys = await gen_mining_keys(APP_ID);

The output of the key generation process has the following type:

{
  deep_link: string, 
  secret: string
  public: string
}

The handling of the deep_link is left to the developer’s discretion. It can be implemented either as a connection button to the AN Wallet application or as a QR code that opens the application.

---

3. Operation Confirmation by the User

The user:

• Either scans the QR code

• Or clicks the button from the previous step

This opens the AN Wallet application, where the user is asked to confirm registration in the developer’s application.

If the user confirms:

• The mining keys are written to their Miner contract.

Mining keys are not secret. If someone else uses them, they will simply mine on behalf of the key owner.

After scanning the QR code, the AN Wallet does not return any response

---

4. Waiting for Authorization Confirmation (Developer Side)

The developer calls the following function:

await ensure_mining_keys_propagated({
    client_config: {
      network: {
        endpoints: ENDPOINTS,
      },
    },
    miner_address: minerAddress,
    app_id: APP_ID,
    expected_owner_public: resultOfGenKeys.public,
    max_attempts: 30,
    interval_ms: 1000,
  });

The implementation of the function’s result handling is the responsibility of the developer. A successful execution indicates that the user has confirmed authorization in the application. Otherwise, the function will return an error.

The developer is responsible for managing and storing the session state after successful authentication.

---

5. Additional Verification — First Tap (Developer Side)

For final verification, it is necessary to send the first tap to the Miner contract. To do this, use the following function:

add_tap(x: number, y: number)

• The tap is signed with the private mining key.

• The signature must correspond to the public key stored in the Miner contract.

If the Miner contract does not reject the message:

→ The user is indeed the owner of the connected AN Wallet.

---

As a Result, This Ensures:

• A cryptographic binding between the user and the application

• A separate mining key pair for each application

• Secure authorization without sharing the user’s private wallet keys with the application

AN Wallet Authorization Scope

Authorization through AN Wallet is limited to the wallet scenarios and Mobile Verifiers system (mvsystem) processes required by Bee Engine.

Acki Nacki Wallet is not intended for calling arbitrary methods of user contracts, because it operates under the system DAPP ID.

If your application requires users to interact with your smart contracts, deploy your own DAPP and implement that interaction there. DAPP development prerequisites

If you need to call contract methods through a wallet, use Multisig Wallet, which supports sending an ABI-encoded payload as part of a transaction. Deployment guide

Flow 2 — User Does NOT Have AN Wallet (in progress)

General Description

The developer independently implements the wallet creation flow for their users in the AN Wallet application.

Additional functionality to support and simplify this flow will be provided in the future.

After the wallet is created, the developer must generate the user’s mining keys and register them in the user’s Miner contract, as described above.

Limitations

• One wallet can be connected to no more than 100 applications

• Exceeding this limit will cause new connections to be rejected

Important — Mining Rewards Activation

Mining will only generate rewards if the user has activated ecosystem participation.

The user must:

1. Visit one of the official ecosystem applications:

   • Ludo

   • Batteries

   • Popits

2. Complete the required task

3. Place the first part in the Mambaboard

After activation, the user will start earning mining rewards in your application. This is a required condition. Programmatic initialization of Mamaboard is not supported

Step 5. Working with the Bee Engine API

Below are the core bee_engine_miner methods used to control mining.

can_start() -> bool

Checks whether mining can be started.

Returns true if:

• the Bee Engine Miner is not running

• there is no active mining process

• there are available seeds to work with

⚠️ If you call start() without checking and mining is not possible, an error will be thrown.

start(duration_ms: number, callback: (event: object) -> void) -> void

Starts the mining process for a specified duration.

• duration_ms — session duration in milliseconds

• callback — function receiving miner events

After starting:

• the Bee Engine Miner begins hashing with reduced difficulty

• events (status, progress, errors) are delivered via callback

add_tap(x: number, y: number) -> void

Adds a user action (tap) to the Merkle Tree.

Features:

• this hash is computed with increased difficulty

• used to bind user activity to mining

• coordinates (x, y) are defined by the application

stop() -> void

Forcefully stops the Bee Engine Miner.

When called:

• mining is terminated

• results are sent to the contract for validation

If not called, the Bee Engine Miner:

• stops automatically after duration_ms

• submits results on its own

get_reward() -> void

Collects available rewards from previous mining sessions.

Recommendations:

• no need to call more than once per epoch (~1000 blocks)

• rewards are collected automatically when submitting data to the contract

Use this method if:

• the application has just launched

• you need to explicitly synchronize the user’s balance

polling()

A special function that:

• polls the mining contract

• waits for the key pair requested by Bee Engine via AN Wallet

• is used to synchronize state during authorization

What’s Next

After basic integration, you can:

• Start and stop the mining process

• bind add_tap to user actions

• use miner events for UI / telemetry

• integrate reputation and economics into your application