# Bee Engine SDK — Integration Documentation

## Getting Started

This section describes the minimal steps required to integrate **Bee Engine SDK** into your application and start client-side [NACKL](https://docs.ackinacki.com/glossary#nackl) mining.

{% hint style="info" %}
Repository with artifacts is here:\
<https://github.com/gosh-sh/bee-engine>
{% endhint %}

## 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](https://t.me/EugeneDAO) \
  and provide to get it:
  * your App name;
  * App link;
  * link to your logo\
    the image must be preliminarily [converted into webp format](https://squoosh.app/)
* 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](https://docs.ackinacki.com/glossary#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](https://github.com/ackinacki/ackinacki/blob/main/contracts/mvsystem/Miner.sol)
* Is necessary for the user to authenticate in the developer’s application

In the example, insert it into the `APP_ID` variable.

**Example:**

```ts
const APP_ID = "your_app_dapp_id_here";
```

### Step 2. Install Bee SDK

Install the SDK via npm:

```bash
npm install @teamgosh/bee-sdk
```

### Step 3. Integration Example (React + Vite)

A minimal integration example is available [in the repository](https://github.com/gosh-sh/bee-engine) :

File: `App.tsx`\
Folder: `miner-react` ([download this folder](https://github.com/gosh-sh/bee-engine/blob/main/examples/javascript/miner-react))

#### 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**](https://ackinacki.com/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.

{% hint style="info" %}
**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.
{% endhint %}

***

#### 2. Mining Key Generation (Developer Side)

The developer must:

* Generate a **Mining key pair**.

{% hint style="info" %}
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.
{% endhint %}

```ts
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.

{% hint style="info" %}
Mining keys are not secret. If someone else uses them, they will simply mine on behalf of the key owner.
{% endhint %}

{% hint style="info" %}
After scanning the QR code, the AN Wallet does not return any response
{% endhint %}

***

#### 4. Waiting for Authorization Confirmation (Developer Side)

The developer calls the following function:

```ts
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.

{% hint style="info" %}
The developer is responsible for managing and storing the session state after successful authentication.
{% endhint %}

***

#### 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:

```ts
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**

#### 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

{% hint style="warning" %}

### 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](https://t.me/ackinackibot/ackinacki_app?startapp=)
   * [Batteries](https://t.me/ackinacki_miner_bot/ackinacki_miner_app?startapp=)
   * [Popits](https://t.me/LudoBidBot/LudoBid?startapp=)
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**
{% endhint %}

### 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dev.ackinacki.com/bee-engine/bee-engine-sdk-integration-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.