1. Rename .env.example to .env
2. Replace the values in .env with your own values
3. Make sure you have installed rust and cargo
4. Run the following command to start the server

cargo r -r

1. BLK_DIR: Set this to the path containing your Dogecoin/Bellscoin blockchain data files (blk*.dat files), typically found at /home/<user>/.dogecoin/blocks or /home/<user>/.bells/blocks.
2. INDEX_DIR: This requires a copy of the LevelDB index from your Dogecoin node.

⚠️ Before copying the index:

• Shut down your Dogecoin node completely to prevent data corruption
• Use rsync to create a copy of the index directory

Example of safely copying the index:

# First, stop the Dogecoin node
dogecoin-cli stop
# or if using systemd
sudo systemctl stop dogecoind

# Wait a moment to ensure the node is fully stopped
sleep 5

# Copy the index to your project directory
rsync -av --delete /home/<user>/.dogecoin/blocks/index/ /path/to/your/project/index/

# After copying is complete, you can restart your Dogecoin node if needed
# dogecoin-cli -daemon
# or
# sudo systemctl start dogecoind

If /app/blk-dir is a bind mount to a host directory owned by a different UID/GID (for example, when the host path is a symlink to another application's data), the container user may not have read access and the indexer will fail with Permission denied (os error 13).

Two options:

1. Set the container user to match the owner of the host blk directory via env:

AUTO_RUN_AS_FROM_BLK_DIR=1

This makes the entrypoint detect the UID:GID of /app/blk-dir and run the indexer as that user, while still fixing permissions for writable mounts like /app/index-dir and /app/rocksdb.

2. Explicitly set APP_UID/APP_GID to the host owner of the blk directory.

If you must keep running as appuser (uid 1001), grant read/execute permissions on the host using ACLs:

setfacl -R -m u:1001:rx /path/to/blocks
setfacl -R -d -m u:1001:rx /path/to/blocks

x on directories allows traversal into the folder; without it, the user cannot access files inside even if the files are readable.

This API provides endpoints to interact with addresses, tokens, and events. Below are the available routes, their parameters, and descriptions.

• Description: Retrieves token balances and transfers for a specific address.
• Parameters:
  • address (path): The address to retrieve token balances and transfers for.

[
    {
        "tick": "<tick>",
        "balance": "1000",
        "transferable_balance": "1000",
        "transfers": [
            {
                "outpoint": "<txid:vout>",
                "value": "1000"
            }
        ],
        "transfers_count": 1
    },
    ...
]

• Description: Retrieves the history of token actions for a specific address.
• Parameters:
  • address (path): The address to retrieve token history for.
  • tick (query): The token tick to filter by.
  • offset (query, optional): The offset for pagination. (key: id)
  • limit (query, optional): The maximum number of records to return.

[
    {
        "id": 1,
        "tick": "<tick>",
        "height": 100,
        "type": "Send",
        "amt": "1",
        "recipient": "<address>",
        "adddress": "<address>",
        "txid": "<txid>",
        "vout": 0,
        "created": 198773477
    },
    ...
]

• Description: Retrieves the history of token actions for a specific height.
• Parameters:
  • height (path): The block number to retrieve events history for.

[
    {
        "id": 1,
        "tick": "<tick>",
        "height": 100,
        "type": "Send",
        "amt": "1",
        "recipient": "<address>",
        "adddress": "<address>",
        "txid": "<txid>",
        "vout": 0
    },
    ...
]

• Description: Retrieves events by TXID
• Parameters:
  • txid (path): Transaction Hash (ID)

[
    {
        "id": 1,
        "tick": "<tick>",
        "height": 100,
        "type": "Send",
        "amt": "1",
        "recipient": "<address>",
        "adddress": "<address>",
        "txid": "<txid>",
        "vout": 0
    },
    ...
]

• Description: Retrieves metadata for all tokens.

[
    {
        "genesis": "<inscription_id>",
        "tick": "<tick>",
        "max": "1000000000",
        "lim": "1000",
        "dec": 18,
        "supply": "6000",
        "mint_count": 5,
        "transfer_count": 10,
        "holders": 10
    },
    ...
]

• Description: Subscribes to events related to specific addresses and tokens.
• Parameters:
  • addresses (body, optional): A set of addresses to subscribe to.
  • tokens (body, optional): A set of tokens to subscribe to.

{
  "event_type": "new_block",
  "height": 1,
  "proof": "<hash>",
  "blockhash": "<hash>"
}

{
  "event_type": "reorg",
  "blocks_count": 5,
  "new_height": 67890
}

{
  "id": 1,
  "type": "Deploy",
  "max": "1000000",
  "lim": "500000",
  "dec": 18,
  "address": "<address>",
  "txid": "<txid>",
  "vout": 0
}

{
  "id": 1,
  "type": "Mint",
  "amt": "1000.0",
  "address": "<address>",
  "txid": "<txid>",
  "vout": 0
}

{
  "id": 1,
  "type": "DeployTransfer",
  "amt": "500.0",
  "address": "<address>",
  "txid": "<txid>",
  "vout": 0
}

{
  "id": 1,
  "type": "Send",
  "amt": "250.0",
  "recipient": "<address>",
  "address": "<address>",
  "txid": "<txid>",
  "vout": 0
}

{
  "id": 1,
  "type": "Receive",
  "amt": "250.0",
  "sender": "<address>",
  "address": "<address>",
  "txid": "<txid>",
  "vout": 0
}

{
  "id": 1,
  "type": "SendReceive",
  "amt": "500.0",
  "address": "<address>",
  "txid": "<txid>",
  "vout": 0
}

• Description: Retrieves current status of the server

{
    "height": 0,
    "proof": "<hash>",
    "blockhash": "<hash>"
}

• Description:
• Parameters:
  • offset (query, optional): The offset for pagination. (key: height)
  • limit (query, optional): The maximum number of records to return. (up to 100)

[
    {
        "height": 0,
        "hash": "<hash>"
    },
    ...
]