# Mintbase Agentic Framework Documentation


## Overview

Mintbase is at the forefront of integrating AI with blockchain technology. We are committed to revolutionizing the way blockchain transactions are performed through advanced AI-driven platforms.

## System Architecture

Assistants are specialized web services that facilitate interaction between the Mintbase AI system and various blockchain functionalities. There are two types of assistants:

### Assistants


#### 1. Core Assistants

Core Assistants provide essential functionalities that are commonly used across multiple applications. These are standardized and managed by Mintbase to ensure reliability and efficiency.

**Features:**
- Transaction generation and management
- Basic query handling and response formatting
- Interaction with standard blockchain elements and smart contracts

#### 2. Plugin Assistants

Plugin Assistants are designed for specific tasks and can be developed in-house or by third parties. They are adaptable and can be tailored to meet the needs of specific applications or services.

**Features:**
- Customizable interaction with decentralized apps (DApps)
- Specialized transaction handling, such as swaps or NFT transactions
- Extensibility via OpenAPI specifications for seamless integration

**Examples**:

- **Ref.finance**: github.com/mintbase/ref-finance-agent-next
- **NFT-gated**: github.com/mintbase/gated-agent-next

### Integration via OpenAPI

Plugin Assistants use the OpenAPI specification to define how they can be integrated into the Mintbase ecosystem. This spec includes an `x-mb` extension which outlines necessary metadata for integration:

x-mb:
  account-id: "mintbase.near"
  assistant:
    model: "gpt-4"
    instructions: "Handle user queries about blockchain transactions."
    temperature: 0.5
    tools:
      - type: "generate-transaction"

### Tools

Tools are categorized into three types, each serving unique roles within the ecosystem:

#### 1. Primitives
These are basic building blocks used to perform atomic operations such as generating a blockchain transaction or converting hashes to readable text.

#### 2. Plugins
Defined via OpenAPI, these tools handle complex sequences of operations tailored to specific tasks like financial estimations or data analytics.

#### 3. Native
Hosted by OpenAI, these tools provide generalized AI capabilities including text processing, image generation, and more.

### Outputs
Outputs from the AI system can be categorized as follows:

- **Structured Data**: JSON formatted data outputs from blockchain queries.
- **Text**: Human-readable responses or instructions.
- **Media**: Images or other media files generated in response to queries.
- **UI Elements**: Just-in-time generated UI components to enhance user interaction.

## Registry

The Registry serves as a centralized repository within the Mintbase AI system, managing the registration, tracking, and version control of all Assistants and their associated Tools.

**Functionalities**:

- **Registration and Discovery**: Allows users and developers to register new Assistants and discover existing ones, facilitating easy integration and scalability.
- **Version Control**: Manages different versions of Assistants and Tools, ensuring users can access the latest functionalities while maintaining the option to use older, stable versions.
- **Release Management**: Provides mechanisms for releasing updates to Assistants, including beta releases and official version rollouts.

## Playground and CLI Tools

The Playground and CLI tools provide two alternative environments for developers to test and experiment with their Plugin Assistants and tools before deploying them into production.

### Functionalities

#### Playground

- **Interactive Testing:** Allows developers to interactively test assistants and tools within a web-based environment that simulates real-world operations.
- **Code Editing and Management:** Features in-browser coding tools for immediate feedback on changes without the need to switch contexts.
- **Integration Trials:** Enables testing of integration capabilities of Plugin Assistants within the broader Mintbase ecosystem.

#### CLI Tool

- **Scriptable Interface:** Provides a command-line interface that enables automation and scripting of tests, suitable for integration into continuous integration/continuous deployment (CI/CD) pipelines.
- **Local Testing:** Facilitates local environment testing, offering developers the flexibility to work in their preferred development setups.

### Integration with Registry

Both the Playground and the CLI tool are integrated with the Registry, enabling developers to fetch the latest versions of Assistants and Tools for testing. This seamless integration ensures that developers always have access to up-to-date components and can easily push updates back to the Registry after final testing and adjustments.

## Security Protocols

To maintain the integrity and security of transactions and data interactions within the Mintbase AI system:

- **Transaction Validation**: Mechanisms are in place to flag and prevent potentially fraudulent or anomalous transactions.
- **Data Integrity Checks**: Ensure the accuracy and safety of data returned by Plugin Tools through rigorous security checks.

## Future Development

### Smart Actions

Smart Actions simplify complex blockchain interactions into single-command executions that span multiple tasks across different platforms. This feature will allow users to execute pre-defined or customizable workflows efficiently.

Smart Actions will enable users to translate the following chat

User: Free mint a dog nft
Assistant: Generates image, creates transactions
User: Great. Now list it for sale
Assistant: Generates transaction
User: Now swap 0.1 NEAR for BLACKDRAGON
Assistant: Estimates Swap and generate a transaction

into something like this.

@mintbase-agent-id generate image of red dog and create transaction. 
@ref-agent-id estimates swap and creates transaction.

that gets parsed and executed by the Mintbase AI system.

### Assistant-to-API Payments
Exploring the integration of direct payment protocols within assistants, facilitating automated transactions and enabling new business models within the blockchain ecosystem.

---

# Roadmap

1. Improve AI usability in wallet
- Recover from errors gracefully
- solve issues in AI pinned thread
- feed the error and let the assistant recover from it
- Quasi-deterministic executions / assistant explanations
- prompt engineering
- "@mintbase <action>"
- Reduce user confusion -- especially when users ask for things that the assistants cannot do.
- prompt engineering instructions
2. Dev
- Refactor