Daemon for TFChain (Substrate) to Mycelium Ledger (NEAR) token transfers.

Rust 98.6%
Makefile 0.7%
Dockerfile 0.7%

Find a file

rawdaGastan 48a266a9a9 All checks were successful Test / test (push) Successful in 4m37s Details Test / test (pull_request) Successful in 2m55s Details Merge pull request 'add refund option if tx failed with no enough spores to transfer' (#11 ) from development_no_enough_spores_to_transfer into main Reviewed-on: #11 Reviewed-by: Mahmoud Emad <emadm@incubaid.com>		2026-03-17 14:17:08 +00:00
.forgejo/workflows	ci: add fmt check and make clippy a hard failure	2026-02-26 00:34:41 +02:00
docs	fix: resolve mermaid syntax and clippy lint errors	2026-02-26 15:02:53 +02:00
migrations	initial version of the tfspores daemon	2026-02-20 02:06:52 +02:00
src	fix gas leak	2026-03-17 16:08:15 +02:00
tests	feat: add automatic TFT refund system for invalid transfers	2026-02-26 00:25:19 +02:00
.dockerignore	feat: add Docker support, configurable operational tuning, and server tests	2026-02-26 01:03:09 +02:00
.env.example	perf: add concurrent block scanning with configurable batch size:	2026-02-26 14:31:28 +02:00
.gitignore	feat: add Docker support, configurable operational tuning, and server tests	2026-02-26 01:03:09 +02:00
Cargo.lock	remove rhai from hero_ledger in cargo toml	2026-03-17 14:55:14 +02:00
Cargo.toml	remove rhai from hero_ledger in cargo toml	2026-03-17 14:55:14 +02:00
docker-compose.yml	feat: add Docker support, configurable operational tuning, and server tests	2026-02-26 01:03:09 +02:00
Dockerfile	fix: bump Dockerfile Rust version to 1.92 (required by dependencies)	2026-02-26 09:48:37 +02:00
Makefile	feat: add Docker support, configurable operational tuning, and server tests	2026-02-26 01:03:09 +02:00
README.md	docs: update documentation with refund flow	2026-02-26 14:50:11 +02:00

README.md

hero_tfspores

Bridge daemon that converts TFT (TFChain/Substrate) to SPORE (Mycelium Ledger/NEAR). Optionally refunds TFT for invalid transfers.

Quick Start

cp .env.example .env   # Edit with your values
make build
make run

Docker

cp .env.example .env   # Edit with your values
make docker-build
make docker-run        # Starts via docker compose
make docker-logs       # Tail logs

Configuration

Create a .env file from the template. See docs/configuration.md for the full reference.

Required variables:

TFCHAIN_NETWORK=devnet
TFCHAIN_TREASURY_ADDRESS=5G...
NEAR_NODE_URL=http://YOUR_NEAR_NODE:3030
NEAR_BRIDGE_ACCOUNT_ID=your_bridge_account_hex
NEAR_BRIDGE_PRIVATE_KEY=ed25519:...

Block Cursor

The daemon tracks progress in node.json. On first run it defaults to block 0 — scanning from genesis is extremely slow on a live chain.

For a fresh deployment, set the cursor to a recent block:

echo '{"last_block":20417000}' > node.json
make run

Or use the env var override:

RESCAN_FROM_BLOCK=20417000 make run

Refunds (Optional)

Enable automatic TFT refunds for transfers with no or invalid memo:

REFUND_ENABLED=true
TFCHAIN_TREASURY_MNEMONIC=word1 word2 ... word12
REFUND_FEE_PLANCK=100000  # 0.01 TFT fee

See docs/configuration.md for details.

HTTP API

The daemon exposes a JSON API on API_PORT (default 3030):

Endpoint	Description
`GET /health`	Liveness probe
`GET /status`	Uptime, cursor position, tx counts
`GET /txs`	List/filter transactions
`GET /txs?tx=<hash>`	Look up a single transaction

See docs/api.md for endpoint details and docs/api-integration.md for the frontend polling guide.

Documentation

Doc	Description
Configuration	Environment variables reference
Architecture	Component overview and database schema
Flows	Token conversion flow diagrams
HTTP API	REST endpoint reference
API Integration	Frontend integration and polling guide
CLI	Commands, admin operations, and recovery

Development

make help       # Show all available commands
make check      # Type check
make test       # Run tests
make fmt        # Check formatting
make clippy     # Run linter