BNS Domain Resolution Tool

This repository contains a Banano Name System (BNS) resolution tool implemented in Python. It allows you to:

1. Identify whether a given domain (e.g., example.ban) exists.
2. Trace the domain’s history (transfers, metadata updates, resolution address changes, etc.).
3. Detect special states, like whether a domain has been frozen or burned.

You can use this tool either:

• Directly from the command line to test domain resolution.
• As a library by importing its classes and methods into your Python application.

Features

• TLD Discovery: Maps a given top-level domain (TLD) to the corresponding TLD account on Banano.
• Domain Existence: Verifies if a domain name was ever issued under that TLD.
• Domain History Crawl: Fetches historical blocks from the domain’s account to identify important events.
• Resolution & Metadata: Detects resolver changes (e.g., updated address) and metadata changes.
• Burn/Freeze Detection: Determines if a domain has been “burned” or frozen.

---

Getting Started

Requirements

• Python 3.7+ (due to f-strings and typing)
• A Banano RPC endpoint that supports the standard Banano node API methods:
  • account_info
  • account_history

In the example code, the default RPC is https://kaliumapi.appditto.com/api.

Installation

1. Clone or download this repository.
2. Make sure you have Python 3.7+ installed, and install any dependencies:

   pip install bananopie

Quick Start (Command-Line Usage)

1. Edit the RPC and TLD mappings in the script if needed.
2. Run the script directly from your terminal:

   python bns_resolver.py

   This will run the sample test domains found at the bottom of the file.

Example Output

Running the script will print output similar to:

Testing burn.ban
Resolved address: No resolution
History entries: 2
Burned: False

Testing example.mictest
Could not resolve
...

The above indicates whether the domain was resolved, how many history entries were processed, and whether the domain is burned or not.

---

Using as a Library

You can import and use the classes in your own Python code. Below is a minimal example:

from bananopie import RPC
from bns_resolver import Resolver

rpc = RPC("https://kaliumapi.appditto.com/api")

# Example TLD mapping
tld_mapping = {
    "ban": "ban_1fdo6b4bqm6pp1w55duuqw5ebz455975o4qcp8of85fjcdw9qhuzxsd3tjb9"
}

# Create a Resolver instance
resolver = Resolver(rpc, tld_mapping)

# Resolve a domain
domain_name = "burn"
tld = "ban"

domain_info = resolver.resolve(domain_name, tld)
if domain_info:
    print("Domain resolution successful!")
    print("Resolved Address:", domain_info.get("resolved_address"))
    print("History length:", len(domain_info["history"]))
    print("Burned:", domain_info.get("burned", False))
else:
    print("Domain not found or not resolvable.")

Reference

• Resolver class

  • __init__(rpc, tld_mapping, max_rpc_calls_after_tld=None)
    Create a Resolver with a given RPC endpoint, a dictionary of TLD mappings (TLD -> TLD Account), and an optional max RPC calls limit.
  • resolve(domain_name, tld, batch_size=500)
    Attempts to resolve the domain. Returns a domain data dictionary if found, otherwise None.

• TLDAccount class
  Scans the TLD account chain to check if a specific domain name exists or was ever created.

• DomainAccount class
  Crawls an individual domain account’s blockchain history for events like transfers, freezing, resolving to an address, etc.

• decode_domain_name(pub_key)
  Utility function to decode domain names from a BANano public key.

---

Customization

• Adjusting TLD Accounts: Modify the test_tld_mapping in the script or pass your own mapping at runtime to cover additional TLDs.
• RPC Endpoints: Switch to a different Banano RPC URL if you have a local node or a different host.
• Batch Size: Tune the batch_size parameter for each resolve() call. A higher number may reduce RPC calls but increase data payloads.

---

Contributing

1. Fork the repository.
2. Create a new branch for your feature/bugfix.
3. Commit your changes and push to your fork.
4. Create a pull request explaining your changes.

---

License

This project is open-source and available under the MIT License. Feel free to use, modify, and distribute this code as permitted by the license.

---

Thank you for using BNS Domain Resolution Tool! If you have any questions or encounter issues, please open an issue on the repository or contact the maintainers.