fulmine

⚡️fulmine

Fulmine is a Bitcoin wallet daemon that integrates Ark protocol's batched transaction model with Lightning Network infrastructure, enabling routing nodes, service providers and payment hubs to optimize channel liquidity while minimizing on-chain fees, without compromising on self-custody.

🚀 Usage

🐳 Using Docker (Recommended)

The easiest way to run fulmine is using Docker. Make sure you have Docker installed on your machine.

docker run -d \
  --name fulmine \
  -p 7000:7000 \
  -p 7001:7001 \
  -v fulmine-data:/app/data \
  ghcr.io/arklabshq/fulmine:latest

Once the container is running, you can access the web UI at http://localhost:7001.

To view logs:

docker logs -f fulmine

To stop the container:

docker stop fulmine

💻 Using the Binary

Alternatively, you can download the latest release from the releases page for your platform. After downloading:

1. Extract the binary
2. Make it executable (on Linux/macOS): chmod +x fulmine
3. Run the binary: ./fulmine

🔧 Environment Variables

The following environment variables can be configured:

When using Docker, you can set these variables using the -e flag:

docker run -d \
  --name fulmine \
  -p 7001:7001 \
  -e FULMINE_HTTP_PORT=7001 \
  -e FULMINE_ARK_SERVER="https://server.example.com" \
  -v fulmine-data:/app/data \
  ghcr.io/arklabshq/fulmine:latest

👨‍💻 Development

To get started with fulmine development you need Go 1.23.1 or higher and Node.js 18.17.1 or higher.

git clone https://github.com/ArkLabsHQ/fulmine.git
cd fulmine
go mod download
make run

Now navigate to http://localhost:7001/ to see the dashboard.

🤝 Contributing

We welcome contributions to fulmine! Here's how you can help:

1. Fork the repository and create your branch from main
2. Install dependencies: go mod download
3. Make your changes and ensure tests pass: make test
4. Run the linter to ensure code quality: make lint
5. Submit a pull request

For major changes, please open an issue first to discuss what you would like to change.

🛠️ Development Commands

The Makefile contains several useful commands for development:

• make run: Run in development mode
• make build: Build the binary for your platform
• make test: Run unit tests
• make lint: Lint the codebase
• make proto: Generate protobuf stubs (requires Docker)

📚 API Documentation

🔌 API Interfaces

fulmine provides two main interfaces:

1. Web UI - Available at http://localhost:7001 by default
2. API Services - Both REST and gRPC interfaces

The REST API is accessible at the same port as the Web UI, while the gRPC service runs on a separate port (default: 7002).

Here's a high-level overview of the main API endpoints, including examples using curl:

💰 Wallet Service

1. Generate Seed

   curl -X GET http://localhost:7001/api/v1/wallet/genseed
   

2. Create Wallet

   Password must:

   • Be 8 chars or longer
   • Have at least one number
   • Have at least one special char

   Private key supported formats:

   • 64 chars hexadecimal
   • Nostr nsec (NIP-19)

   curl -X POST http://localhost:7001/api/v1/wallet/create \
        -H "Content-Type: application/json" \
        -d '{"private_key": <hex or nsec>, "password": <strong password>, "server_url": "https://server.example.com"}'
   

3. Unlock Wallet

   curl -X POST http://localhost:7001/api/v1/wallet/unlock \
        -H "Content-Type: application/json" \
        -d '{"password": <strong password>}'
   

4. Lock Wallet

   curl -X POST http://localhost:7001/api/v1/wallet/lock \
        -H "Content-Type: application/json" \
        -d '{"password": <strong password>}'
   

5. Get Wallet Status

   curl -X GET http://localhost:7001/api/v1/wallet/status
   

⚡ Service API

1. Get Address

   curl -X GET http://localhost:7001/api/v1/address
   

2. Get Balance

   curl -X GET http://localhost:7001/api/v1/balance
   

3. Send funds offchain

   curl -X POST http://localhost:7001/api/v1/send/offchain \
        -H "Content-Type: application/json" \
        -d '{"address": <ark address>, "amount": <in sats>}'
   

4. Send funds onchain

   curl -X POST http://localhost:7001/api/v1/send/onchain \
        -H "Content-Type: application/json" \
        -d '{"address": <bitcoin address>, "amount": <in sats>}'
   

5. Get transaction history

   curl -X GET http://localhost:7001/api/v1/transactions
   

🔔 Notification Service

1. Add Webhook

   curl -X POST http://localhost:7001/api/v1/notifications/webhook \
        -H "Content-Type: application/json" \
        -d '{"endpoint": "https://your-webhook.com/endpoint", "event_type": "WEBHOOK_EVENT_TYPE_ROUND", "secret": "your_secret"}'
   

2. Remove Webhook

   curl -X DELETE http://localhost:7001/api/v1/notifications/webhook/{webhook_id}
   

3. List Webhooks

   curl -X GET http://localhost:7001/api/v1/notifications/webhooks
   

Note: Replace http://localhost:7001 with the appropriate host and port where your fulmine is running. Also, ensure to replace placeholder values (like strong password, ark_address, etc.) with actual values when making requests.

For more detailed information about request and response structures, please refer to the proto files in the api-spec/protobuf/fulmine/v1/ directory.