Blueprint Skill

The hathor-blueprint skill helps LLMs guide developers through the process of creating, reviewing, and debugging Hathor nano contract blueprints.

We recommend using this skill when you want to integrate with LLMs to help you design contract logic, create blueprint code, review persistent state, avoid validator errors, or debug nano contract behavior.

tip

If you would like a more in-depth introduction to nano contracts, please refer to the Nano Contracts documentation.

Preparing for Blueprint Development

Before asking an LLM to write blueprint code, make sure you understand the basic relationship between nano contracts and blueprints.

A blueprint defines reusable contract logic. A nano contract is created from a blueprint and stores its own state. This means several nano contracts can share the same blueprint code while keeping separate state.

Use the official Hathor documentation as the source of truth for concepts, protocol behavior, and deployment details:

• For a conceptual introduction, start with Nano Contracts.
• For LLM skill installation and activation, use the LLM Integration overview.
• For local development and AI-assisted testing, use Hathor Forge LLM Integration.
• For wallet-driven contract creation or execution flows, use Headless Wallet Skill.

warning

The hathor-blueprint skill helps your LLM work with blueprint source code and development workflows. It does not replace official Hathor documentation, validation tools, tests, or security review.

Verifying Skill Availability

After a correct skill installation, your LLM should use this skill when your request mentions:

• Hathor blueprints
• nano contracts
• Hathor smart contracts
• blueprint validation
• persistent fields
• @public
• @view
• @export
• Context
• NCFail
• deposits, withdrawals, or authorities
• self.syscall

To verify this, start a new agent session and run:

/hathor-blueprint

You can then ask a small test question:

/hathor-blueprint

Help me design a simple Hathor nano contract blueprint.
Do not write code yet. Give me the architecture, required methods, and validation rules I should consider.

A useful response should focus on blueprint structure, validation constraints, persistent state, public and view methods, and where official Hathor documentation should be checked.

Recommended Use Cases

This skill can help you with development tasks such as:

• Designing the structure of a new blueprint.
• Creating a minimal blueprint from a product requirement.
• Reviewing whether persistent fields are declared and initialized correctly.
• Checking whether public methods use Context correctly.
• Separating state-changing methods from read-only views.
• Debugging validator errors.
• Avoiding unsupported Python syntax or imports.
• Reviewing token deposit and withdrawal flows.
• Designing contract-level error handling.
• Creating safe examples such as counters, token vaults, membership registries, or oracle-based workflows.
• Identifying when you should switch to the Headless Wallet skill for contract execution through a wallet.

If you are still learning what nano contracts are, start with the Nano Contracts documentation. If you already know the contract behavior you want to build and need help turning it into blueprint code, use this skill with your LLM.

Standard LLM Workflow

When working with any LLM within the Hathor ecosystem, follow this general workflow to get the most out of the hathor-blueprint skill:

1. Describe the product behavior you want the nano contract to enforce.
2. Ask the LLM to identify the required state, public methods, view methods, and failure cases.
3. Ask for a blueprint design before asking for code.
4. Ask the LLM to list validator-sensitive constraints that may affect the implementation.
5. Ask for a minimal implementation.
6. Ask for a self-review against the blueprint rules.
7. Ask for test scenarios before deploying or integrating the contract with a wallet flow.

Example prompt:

/hathor-blueprint

I want to create a token vault blueprint.

Before writing code, give me:
1. The contract goal.
2. The persistent fields.
3. The public methods.
4. The view methods.
5. The deposit and withdrawal rules.
6. The validation constraints I should be careful with.
7. A step-by-step implementation plan.

Do not write the blueprint yet.

Asking Better Questions

Avoid asking the LLM to generate a complete blueprint without first describing the contract behavior and constraints.

Ambiguous Prompt

Write a Hathor smart contract.

Comprehensive Prompt

/hathor-blueprint

I need to create a Hathor nano contract blueprint for a token vault.

The contract should:
- let users deposit one specific token
- track each user's balance
- let users withdraw up to their available balance
- expose a read-only method to check a user's balance
- fail clearly when a user tries to withdraw more than they deposited

Before writing code, help me define:
- persistent fields
- public methods
- view methods
- expected actions
- validation risks
- test cases

The comprehensive prompt gives the LLM a clear product requirement and asks for design validation before code generation.

Development Example

This use case shows how a developer can use the skill with an LLM to build a practical token vault blueprint while relying on official Hathor documentation and validation tools for final confirmation.

Use Case Description

A developer wants to create a nano contract blueprint that works as a simple token vault.

The blueprint should:

• Store the token identifier accepted by the vault.
• Let users deposit that token.
• Track balances by user address.
• Let users withdraw up to their available balance.
• Expose a view method to read a user's balance.
• Fail when a withdrawal amount is greater than the stored balance.

Before implementing this flow, the developer should understand that a blueprint defines reusable contract logic, while each nano contract created from that blueprint stores its own state.

LLM-defined Contract Design

As a general best-practice approach, start by asking for the contract design, not the code.

/hathor-blueprint

I want to create a token vault blueprint.

Give me the recommended contract design before writing code.

Include:
- what state the blueprint needs
- which methods should be public
- which methods should be views
- what should happen during deposit
- what should happen during withdrawal
- what errors should be expected
- which official Hathor documentation is relevant for each step

A good LLM answer should describe the expected contract shape before producing code.

Example of expected output:

• The blueprint should store the accepted token identifier.
• The blueprint should store balances by address.
• The deposit method should accept deposits and update the caller's balance.
• The withdrawal method should check the caller's stored balance before allowing withdrawal.
• A view method should return a user's balance.
• Expected failures should use contract-level errors.
• The implementation should be reviewed against blueprint validation rules.

Identifying Validation Risks

Before generating code, ask the LLM to list the constraints that usually break blueprint validation.

/hathor-blueprint

Before writing the token vault blueprint, list the validation risks I should avoid.

Focus on:
- class structure
- persistent fields
- method decorators
- Context usage
- imports
- unsupported syntax
- container limitations
- integer arithmetic

Example of expected output:

• The blueprint class should use @export.
• The class should inherit from the correct blueprint base class.
• Persistent fields should be declared as class attributes.
• Persistent fields should be initialized in the initialization method.
• State-changing methods should use @public.
• Read-only methods should use @view.
• Public methods should receive execution context.
• Avoid unsupported imports and syntax.
• Avoid floating-point arithmetic.
• Avoid unsupported container methods.

Blueprint Module Skeleton

Before generating the full blueprint, it is useful to ask the LLM for a minimal module skeleton that follows the Blueprint SDK constraints.

Blueprints must be implemented as a single Python module, use only supported imports, and expose exactly one exported class that inherits from Blueprint.

from hathor import Blueprint, Context, TokenUid, Address, Amount, NCFail, export, public, view


class InvalidAmount(NCFail):
    pass


class InsufficientBalance(NCFail):
    pass


class InvalidToken(NCFail):
    pass


@export
class TokenVault(Blueprint):
    """Simple token vault blueprint.

    This blueprint stores the token accepted by the vault and tracks
    user balances using contract attributes.

    Verify this implementation against the official Blueprint SDK
    guidelines and validation tools before using it in production.
    """

    token_uid: TokenUid
    balances: dict[Address, Amount]

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

    @view
    def get_balance(self, address: Address) -> Amount:
        if address in self.balances:
            return self.balances[address]

        return 0

warning

This is not the complete vault logic yet. It only shows the expected module shape, imports, custom failures, exported class, persistent fields, initialization method, and view method.

Implementation Plan

Once the behavior and validation risks are clear, ask for an implementation plan.

/hathor-blueprint

Now give me a development plan for implementing the token vault blueprint.

Do not write code yet.

Include:
1. imports to confirm
2. persistent fields
3. initialization method
4. public deposit method
5. public withdrawal method
6. view method
7. expected contract-level failures
8. validation checklist
9. test scenarios

Example of expected plan:

1. Confirm the allowed imports required by the blueprint.
2. Declare the accepted token identifier.
3. Declare a balance mapping by user address.
4. Initialize all persistent fields.
5. Add a deposit method that updates the caller balance.
6. Add a withdrawal method that checks balance before withdrawal.
7. Add a view method to read balances.
8. Review the code against validator-sensitive rules.
9. Test successful deposit, successful withdrawal, insufficient balance, and zero or invalid values.

Asking for Code

After the plan is approved, ask for code.

/hathor-blueprint

Generate the token vault blueprint.

Requirements:
- keep the implementation minimal
- use integer amounts only
- use clear contract-level failures
- include one public initialization method
- include one public deposit method
- include one public withdrawal method
- include one view method for balances
- add comments where I must verify behavior against official Hathor documentation or validators

Example of a deposit-oriented method draft:

@public(allow_deposit=True)
def deposit(self, ctx: Context, amount: Amount) -> None:
    """Register a deposit for the caller.

    The actual token transfer into the contract balance is handled by
    Hathor engine after this public method succeeds. This method should
    validate the expected action details according to the official SDK
    and then update the contract's own accounting state.
    """

    if amount <= 0:
        raise InvalidAmount

    # TODO: Verify the exact caller identifier available through Context.
    # TODO: Verify the received deposit action from ctx according to the
    # Blueprint SDK API before treating this as production-ready.
    caller: Address = ctx.caller_id

    current_balance: Amount = self.get_balance(caller)
    self.balances[caller] = current_balance + amount

note

This sample intentionally includes TODO comments because the method must be checked against the official Context and action APIs before production use.

Example of a withdrawal-oriented method draft:

@public(allow_withdrawal=True)
def withdraw(self, ctx: Context, amount: Amount) -> None:
    """Allow the caller to withdraw up to their recorded balance.

    The contract should reduce its own accounting state only after
    checking that the caller has enough recorded balance.
    """

    if amount <= 0:
        raise InvalidAmount

    # TODO: Verify the exact caller identifier available through Context.
    # TODO: Verify the requested withdrawal action from ctx according to
    # the Blueprint SDK API.
    caller: Address = ctx.caller_id

    current_balance: Amount = self.get_balance(caller)

    if amount > current_balance:
        raise InsufficientBalance

    self.balances[caller] = current_balance - amount

The accounting update and the withdrawal action validation should be reviewed together. The method should fail before state is committed when the caller requests more than their available balance.

The generated code should be treated as a first draft. It should still be reviewed, validated, tested, and compared with the official Hathor documentation.

Example First Draft

The following example shows how the generated blueprint might look as a first draft.

warning

This example is intentionally conservative. It should be validated against the official Blueprint SDK, tested locally, and reviewed before being used in a real application.

from hathor import Blueprint, Context, TokenUid, Address, Amount, NCFail, export, public, view


class InvalidAmount(NCFail):
    pass


class InsufficientBalance(NCFail):
    pass


class InvalidToken(NCFail):
    pass


@export
class TokenVault(Blueprint):
    """A simple token vault blueprint.

    The vault accepts one token and tracks user balances in contract state.
    Balance-changing methods must be reviewed against the official action
    and Context APIs before production use.
    """

    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 that the deposit action uses self.token_uid.
        # TODO: Validate that the deposited amount matches `amount`.
        # TODO: Confirm the correct caller address field from Context.
        caller: Address = ctx.caller_id

        current_balance: Amount = self.get_balance(caller)
        self.balances[caller] = current_balance + amount

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

        # TODO: Validate that the withdrawal action uses self.token_uid.
        # TODO: Validate that the withdrawal amount matches `amount`.
        # TODO: Confirm the correct caller address field from Context.
        caller: Address = ctx.caller_id

        current_balance: Amount = self.get_balance(caller)

        if amount > current_balance:
            raise InsufficientBalance

        self.balances[caller] = current_balance - amount

    @view
    def get_balance(self, address: Address) -> Amount:
        if address in self.balances:
            return self.balances[address]

        return 0

LLM Output Self-review

Before testing the generated blueprint, request the LLM to review its own output.

/hathor-blueprint

Review the generated blueprint.

Check it against this checklist:
- The class is exported correctly.
- The class inherits from the expected blueprint base.
- Persistent fields are declared correctly.
- Persistent fields are initialized.
- Public methods use the expected execution context.
- View methods are read-only.
- Deposits and withdrawals are explicitly enabled only where needed.
- Errors are intentional and clear.
- No unsupported imports are used.
- No unsupported syntax is used.
- No floating-point arithmetic is used.
- No unsupported container methods are used.
- The implementation includes test scenarios.

If the LLM finds that the code assumes too much or uses unsupported syntax, ask it to revise the blueprint before testing.

You can also ask the LLM to review the code and return a structured report:

/hathor-blueprint

Review this token vault blueprint as if you were preparing it for validation.

Return the review using this format:

1. Import compliance
2. Class and export compliance
3. Persistent field compliance
4. Method decorator compliance
5. Context usage risks
6. Deposit action risks
7. Withdrawal action risks
8. View method safety
9. Unsupported syntax or builtin risks
10. Required changes before validation

Here is the code:

```python
<paste blueprint code here>

This helps separate code generation from code review, which is especially useful before local testing or wallet integration.

Testing and Integration Planning

Once the blueprint has been reviewed, ask for a testing checklist.

/hathor-blueprint

Give me a testing checklist for this token vault blueprint.

Focus on:
- successful initialization
- successful deposit
- successful withdrawal
- insufficient balance
- unauthorized or invalid calls
- view method behavior
- integer amount handling
- validator-sensitive syntax
- integration with a wallet-driven execution flow

For local development and AI-assisted testing, use Hathor Forge LLM Integration. If your next step is creating or executing a nano contract through Headless Wallet, use Headless Wallet Skill.

Example of expected checklist:

• Confirm the blueprint validates successfully.
• Confirm initialization sets the expected token identifier.
• Confirm deposits update only the caller's balance.
• Confirm withdrawals fail when the caller has insufficient balance.
• Confirm view methods do not change state.
• Confirm all amounts use integer units.
• Confirm unsupported syntax and imports are not present.
• Confirm wallet-driven contract calls are planned separately.

Example test scenarios:

Scenario	Setup	Expected Result
Initialize vault	Create contract with a supported token_uid	token_uid is stored and balances start empty
Read empty balance	Call get_balance(address) before deposits	Returns 0
Deposit valid amount	Caller deposits the accepted token	Caller balance increases by the deposited amount
Deposit invalid amount	Caller deposits 0 or a negative amount	Method fails with InvalidAmount
Withdraw valid amount	Caller withdraws less than or equal to their balance	Caller balance decreases
Withdraw too much	Caller withdraws more than their recorded balance	Method fails with InsufficientBalance
Read after withdrawal	Caller deposits and then withdraws part of the balance	View returns the remaining balance
Wrong token action	Caller attempts to deposit or withdraw a different token	Method should fail after action validation is implemented

Pseudo-code for the expected testing flow:

create token vault with token_uid
assert get_balance(alice) == 0

call deposit as alice with amount 100
assert get_balance(alice) == 100

call withdraw as alice with amount 40
assert get_balance(alice) == 60

call withdraw as alice with amount 100
expect InsufficientBalance

The exact test implementation depends on the local tooling used to validate and execute blueprints.

Prompt Patterns for Common Tasks

Designing a Blueprint

/hathor-blueprint

Help me design a Hathor nano contract blueprint.

The contract should:
- describe the intended user behavior
- define the required persistent state
- define public methods
- define view methods
- identify expected failure cases
- identify validation-sensitive constraints

Do not write code yet.

Use this when you know the product behavior but have not designed the contract structure.

Generating a Minimal Blueprint

/hathor-blueprint

Generate a minimal blueprint from this design.

Requirements:
- keep the code small and explicit
- initialize all persistent fields
- use public methods only for state changes
- use view methods only for reads
- avoid unsupported imports and syntax
- add comments where behavior must be verified with official Hathor docs or validation tools

Use this after the LLM has already produced a design and validation checklist.

Debugging Blueprint Validation

/hathor-blueprint

My blueprint fails validation.

Help me debug it step by step.

Ask me to provide:
- the validation error
- the blueprint code
- the method or line that seems related
- the imports
- the persistent field declarations
- the public and view methods

Do not rewrite the whole contract first.
Start by identifying likely validation issues.

Use this when the validator reports a failure and you need focused debugging.

Reviewing Existing Blueprint Code

/hathor-blueprint

Review this blueprint.

Check whether:
- the contract structure is valid
- persistent fields are declared and initialized
- public methods and view methods are used correctly
- Context is used only where appropriate
- token actions are handled explicitly
- errors are intentional and clear
- unsupported imports, syntax, builtins, or container methods are present
- integer arithmetic is used instead of floats
- the code is ready for validation and testing

Here is the code:

This is especially useful before opening a pull request, validating the blueprint, or integrating it with a wallet-driven flow.

Planning Wallet Integration

/hathor-blueprint

I have a blueprint design and now need to plan how users will interact with it through a wallet.

Help me identify:
- which methods users will call
- which calls require deposits or withdrawals
- which data the frontend should collect
- which data the backend should validate
- which parts should be handled with the Headless Wallet skill
- what security checks are needed before testing

Use this when the blueprint logic is ready and the next step is application or wallet integration.

LLM Guardrails

When using this skill, the LLM should follow these rules:

• Do not treat generated blueprint code as production-ready without validation and testing.
• Do not invent protocol behavior, decorators, imports, or runtime capabilities.
• Do not replace official Hathor documentation or validation tools.
• Do not skip the design step before generating code.
• Do not use unsupported imports, syntax, builtins, or container methods.
• Do not use floating-point arithmetic for token amounts or contract state.
• Do not make public methods broader than necessary.
• Do not enable deposits, withdrawals, or authorities unless the method requires them.
• Do not mix wallet execution details into blueprint logic.
• Explain assumptions clearly and point to the relevant Hathor documentation when details must be verified.