Blueprint Skill

The hathor-blueprint skill gives your LLM domain-specific guidance for creating, reviewing, and debugging Hathor nano contract blueprints written in Python.

For installation, see the LLM Integration overview.

tip

New to nano contracts? Start with the Nano Contracts documentation before using this skill.

warning

Code samples in this article are conservative drafts. Verify Blueprint SDK imports, decorators, Context fields, persistent container support, and token action APIs against the official SDK reference and validation tooling before production use.

Prerequisites

• The hathor-blueprint skill installed (install guide)
• Python development environment
• Access to the official Nano Contracts documentation and Blueprint SDK reference
• A local validation workflow such as Hathor Forge for testing

Activate the skill

Invoke explicitly:

/hathor-blueprint

Or let Claude Code activate it when your request mentions blueprints, nano contracts, @public, @view, @export, Context, NCFail, deposits, withdrawals, or self.syscall.

Verify it's working:

/hathor-blueprint

Help me design a simple token vault blueprint.
Do not write code yet — give me the persistent fields, public methods, and validation risks.

Standard workflow

1. Describe the contract behavior you want to enforce.
2. Ask the LLM to identify state, public methods, view methods, and failure cases.
3. Ask for a design before code — get validation risks before generating anything.
4. Ask for a minimal implementation.
5. Ask for a self-review against blueprint rules.
6. Ask for test scenarios before deploying or connecting to a wallet flow.

Build a token vault blueprint — quick start

Step 1 — Define the contract design

/hathor-blueprint

I want to create a token vault blueprint.

Give me the contract design before writing code:
- persistent fields
- public methods
- view methods
- deposit and withdrawal rules
- expected failures
- validation constraints to watch for

Expected guidance:

• Blueprint stores accepted token_uid and a balances mapping by address
• deposit and withdraw are public methods; get_balance is a view
• Withdrawals should fail when the caller's balance is insufficient
• Verify decorator arguments (allow_deposit, allow_withdrawal) and Context fields against the SDK reference

Step 2 — Review validation risks before coding

/hathor-blueprint

Before writing the token vault, list the validation risks I should avoid:
class structure, persistent fields, method decorators, Context usage,
imports, unsupported syntax, container limitations, integer arithmetic.

Key constraints:

• Class must inherit from Blueprint and use @export
• Persistent fields declared as class attributes and initialized in initialize
• State-changing methods use @public; read-only methods use @view
• No floating-point arithmetic, no unsupported imports or containers

Step 3 — Generate the blueprint

/hathor-blueprint

Generate the token vault blueprint.

Requirements:
- minimal implementation
- integer amounts only
- clear contract-level failures
- one initialize, one deposit, one withdraw, one get_balance
- add comments where behavior must be verified against official Hathor docs

warning

The import path and symbol names below are illustrative. Verify the exact module structure, class names, and decorator names against the official Blueprint SDK reference before using this in a real project.

Blueprint skeleton:

# TODO: Verify the exact import path and symbol names in the official Blueprint SDK reference.
from hathor import Blueprint, Context, TokenUid, Address, Amount, NCFail, export, public, view


class InvalidAmount(NCFail):
    pass


class InsufficientBalance(NCFail):
    pass


@export
class TokenVault(Blueprint):
    token_uid: TokenUid
    balances: dict[Address, Amount]

    @public
    def initialize(self, ctx: Context, token_uid: TokenUid) -> None:
        self.token_uid = token_uid
        self.balances = {}

    @public(allow_deposit=True)
    def deposit(self, ctx: Context, amount: Amount) -> None:
        if amount <= 0:
            raise InvalidAmount

        # TODO: Validate deposit action uses self.token_uid.
        # TODO: Confirm caller address field from Context.
        caller: Address = ctx.caller_id
        self.balances[caller] = self.get_balance(caller) + amount

    @public(allow_withdrawal=True)
    def withdraw(self, ctx: Context, amount: Amount) -> None:
        if amount <= 0:
            raise InvalidAmount

        # TODO: Validate withdrawal action uses self.token_uid.
        # TODO: Confirm caller address field from Context.
        caller: Address = ctx.caller_id
        current = self.get_balance(caller)

        if amount > current:
            raise InsufficientBalance

        self.balances[caller] = current - amount

    @view
    def get_balance(self, address: Address) -> Amount:
        return self.balances.get(address, 0)

Step 4 — Review the output

/hathor-blueprint

Review the generated blueprint:
- class exported and inherits from correct base
- persistent fields declared and initialized
- public methods use Context; view methods are read-only
- deposits/withdrawals enabled only where needed
- no unsupported imports, syntax, or floating-point arithmetic
- TODO comments mark unverified SDK behavior

Step 5 — Test scenarios

Scenario	Expected result
Initialize with valid token_uid	token_uid stored, balances empty
get_balance before any deposit	Returns 0
Deposit valid amount	Caller balance increases
Deposit 0 or negative	Fails with InvalidAmount
Withdraw ≤ available balance	Caller balance decreases
Withdraw more than balance	Fails with InsufficientBalance

For local AI-assisted testing, use Hathor Forge.

Prompt patterns

Design a new blueprint

/hathor-blueprint

I need a blueprint for [contract behavior].

Before writing code, define:
- persistent state
- public methods with expected actions
- view methods
- failure cases
- validator-sensitive risks

Debug a validation error

/hathor-blueprint

My blueprint fails validation. Help me debug it.

Error: [error]
Method: [method name]
Code: [paste relevant section]

Start by identifying the likely cause — do not rewrite the whole contract.

Review existing code

/hathor-blueprint

Review this blueprint before validation:
- correct class structure and export
- persistent fields declared and initialized
- correct use of @public, @view, Context
- deposits/withdrawals enabled only where needed
- no unsupported imports, syntax, or float arithmetic

[paste blueprint]

Plan wallet integration

/hathor-blueprint

My blueprint is ready. Help me plan how users interact with it through a wallet:
- which methods users call
- which calls require deposits or withdrawals
- what the backend should validate
- which parts to handle with the Headless Wallet skill

LLM guardrails

When using this skill, the LLM should:

• Never treat generated blueprint code as production-ready without validation
• Never invent decorators, imports, or runtime capabilities — point to the official SDK reference
• Always ask for contract design before generating code
• Never use floating-point arithmetic for amounts
• Mark assumptions that require verification against official Hathor documentation

Next steps

• Validate the blueprint locally with Hathor blueprint tooling or Hathor Forge
• Use Headless Wallet Skill to create or execute the contract through a wallet
• Read the Nano Contracts documentation for deeper protocol concepts