Valyrian Spellbook

The Valyrian Spellbook, formerly known as the Bitcoin Spellbook, is an open platform provided by Valyrian Tech, designed to simplify the creation and management of Bitcoin-related applications and integrations with Large Language Models (LLMs). It is aimed at speeding up development, enhancing automation, and enabling even those with minimal coding experience to deploy sophisticated applications in the cryptocurrency realm.

Table of Contents

• Features
  • Bitcoin Blockchain Features
  • Large Language Model (LLM) Features
  • Actions and Triggers System
• Installation
• Usage
  • Starting the Server
  • Using the CLI
• Triggers
• Actions
• Scripts
• Example Apps
• Additional Tools
• Development
• License
• Donations and Social Media

---

Features

Bitcoin Blockchain Features

• Transaction Management: Send and receive Bitcoin transactions.
• Data Extraction: Fetch and analyze data from the blockchain.
• Explorer Management: Add, configure, and manage blockchain explorers.

Large Language Model (LLM) Features

• Integration of Multiple Models: Manage various LLMs through dynamic API end points.
• Text Processing and Interaction: Automate responses and generate text.
• TLS Certificate Verification: Outbound LLM requests verify TLS certificates against the system certificate store by default. To trust a custom certificate (e.g. a self-signed certificate for a self-hosted LLM), set the ca_bundle option in the [LLMs] section of the configuration to the path of a CA bundle.

Actions and Triggers System

• Automated Workflow: Setup triggers that automatically invoke actions based on specific conditions.
• Extensibility: Easily extendible with custom scripts and integrations to fit any use case.

---

Installation

Run the following commands to set up the Valyrian Spellbook: The install script will install the required dependencies and set up the configuration files.

cd /
wget https://raw.githubusercontent.com/ValyrianTech/ValyrianSpellbook/master/install-spellbook.sh
sh install-spellbook.sh

Refer to the provided configuration/ directory to adjust settings for your environment.

---

Usage

Starting the Server

python spellbookserver.py

CORS / Cross-origin access

The REST API supports cross-origin requests (CORS) for clients such as the Web UI/admin. Set the allowed_origins option in the [RESTAPI] section of configuration/spellbook.conf to a comma-separated allow-list of origins permitted to make cross-origin requests. The server echoes the request's Origin header back with Access-Control-Allow-Credentials: true only when it is in the allow-list. When allowed_origins is empty (the default), no cross-origin requests are allowed, so the Web UI/admin must set this option to call the REST API from another origin.

Using the CLI

The CLI tool spellbook.py helps manage triggers, actions, and configurations:

spellbook.py -h

---

Triggers

Triggers invoke actions based on specific conditions:

• Balance: Activates if the balance of a specified address is above a certain threshold.
• Received/Sent: Monitors received or sent amounts for a given address.
• Block Height: Triggers once the blockchain reaches a specified height.
• Timestamp and Recurring: Schedule triggers based on time.
• HTTP Requests: Activates upon HTTP GET, POST, or DELETE requests.
• Manual Activation: Trigger manually via a specific API endpoint (POST).
• Dead Man's Switch: A time-based trigger that sends notifications if not reset periodically.

---

Actions

Actions perform tasks when triggered. Here are a few example actions:

• Send Transaction: Automates Bitcoin transactions.
• Send Email: Configures and sends emails automatically. Email templates, referenced images, and attachments are confined to the email_templates/ and apps/ directories (paths escaping those directories are rejected), and recipient addresses are validated before sending.
• Command and SpawnProcess: Executes system commands or spawns new processes.
• Reveal Secret: Reveals a pre-configured secret upon trigger activation; the secret (reveal_text/reveal_link) is not exposed via the REST API action-config endpoint until the action has been activated (allow_reveal is True).
• Webhook: Sends data to specified webhooks. Webhook URLs are validated to be publicly reachable (SSRF-safe), the outbound connection is pinned to the pre-resolved validated public IP (defeating DNS-rebinding), and redirects are disabled.

---

Scripts

Custom Python scripts can be added and managed, providing tailor-made functionalities enacted by triggers: custom scripts must live under the spellbookscripts/ or apps/ directories, and the script name supplied to a trigger is confined to those directories (path-traversal out of them is rejected).

# Template script
from spellbookscripts.spellbookscript import SpellbookScript

class CustomScript(SpellbookScript):
    def run(self):
        # Your code here

---

Example Apps

Comprehensive scenarios showcasing what the Valyrian Spellbook can achieve:

• Payment Processor: Automates handling of Bitcoin transactions.
• Notary Service: Utilizes blockchain for timestamping documents.
• Lottery System: A Bitcoin-based lottery implementation.
• Take a look at the apps/ directory for more.

---

Additional Tools

• bitcoinwand.py: Sign messages or verify signatures using Bitcoin keys.
• transaction_listener.py: Listens to transaction broadcasts relevant to watched addresses.
• hot_wallet.py: Manages and secures private keys using authenticated AES-GCM encryption with scrypt-derived keys. For security, the wallet password is provided via the SPELLBOOK_WALLET_PASSWORD environment variable (or an interactive prompt) rather than a command-line argument, and must be at least 12 characters (and cannot be empty) by default. Set the SPELLBOOK_ALLOW_INSECURE_WALLET_PASSWORD environment variable to a truthy value to override this requirement at your own risk. Existing wallets encrypted with an empty password will no longer decrypt silently and now require setting SPELLBOOK_ALLOW_INSECURE_WALLET_PASSWORD to a truthy value; the recommended fix is to re-encrypt the wallet with a strong password (at least 12 characters) via the hot_wallet.py CLI — see the Breaking section of CHANGELOG.md for the migration steps.
• notify_transaction.py: Standalone utility that posts a transaction-notification webhook (payment_request_id + txid) via an HTTP POST.

---

Blockexplorers

The default configuration will use Blockchain.info and BTC.com as explorers.
It is recommended to keep the default explorers configuration, but if you want to change this:

Use the spellbook.py CLI to add the blockexplorers you want to use.

You can add multiple blockexplorers and set a priority for each one, if the first one is offline, the next one will be used.
example: spellbook.py save_explorer blockchain.info Blockchain.info 1

Run spellbook.py save_explorer -h for more information

Currently supported blockchain explorers are:

• Blockchain.info
• BTC.com
• Any Insight blockexplorer (blockexplorer.com)
• Blocktrail.com (testnet seems to be broken, no longer maintained)
• Chain.so (not recommended)

Block explorer HTTP requests now use a timeout, so a slow or unresponsive explorer is handled gracefully and the next configured explorer can be used.

Similarly, all other outbound HTTP requests made by the framework — fee lookups, IP lookups, LNbits calls, Twitter media downloads, the CLI HTTP helpers, and streaming LLM endpoints — now use explicit timeouts, so a slow or unresponsive remote endpoint can no longer hang a server worker.

Requesting an unknown explorer, or running with no block explorers configured at all, now returns an error instead of crashing.

The currently selected block explorer is now stored per-request/per-context (thread-safe) rather than in a shared global, so concurrent requests can no longer leak their explorer selection into each other, while existing data.EXPLORER usages keep working for backward compatibility.

Segwit

There currently is partial segwit support. It is possible to send to segwit addresses (including bech32 addresses).

What is not possible yet:

• sending from segwit addresses (I'm working on it)
• looking up transactions or balances from bech32 addresses (this is because blockchain.info and BTC.com do not support this yet)

Development

The project maintains a high quality bar for its source code:

• Lint-clean (ruff)
• Type-check-clean (mypy)
• 100% docstring coverage (interrogate)
• 100% unit-test coverage (pytest)

Source modules follow PEP 8 snake_case naming conventions.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.

Donations and Social Media

If you find this project useful, consider making a donation to support development: 1Woutere8RCF82AgbPCc5F4KuYVvS4meW

Visit www.valyrian.tech to keep up with the latest developments!

Twitter: @WouterGlorieux

LinkedIn