# near-utils

LangChain Tool for constructing, validating, and simulating NEAR blockchain transactions before execution.

## Overview

`near-utils` is a Python package that provides a LangChain-compatible tool for building complex NEAR Protocol transactions safely. It enables AI agents to construct transfers, function calls, batch actions, and simulate transactions with accurate gas estimation before committing to the blockchain.

## Installation

Install via pip:

pip install near-utils

### Dependencies

- Python 3.8+
- langchain >= 0.1.0
- aiohttp >= 3.8.0
- pydantic >= 2.0.0

## Quick Start

from near_utils import NEARTransactionBuilder

# Initialize the builder
builder = NEARTransactionBuilder(
    network="mainnet",
    rpc_url="https://rpc.mainnet.near.org"
)

# Build a simple transfer
tx = await builder.build_transfer(
    signer_id="alice.near",
    receiver_id="bob.near",
    amount_yocto="1000000000000000000000000"  # 1 NEAR
)

# Simulate before sending
simulation = await builder.simulate(tx, signer_id="alice.near")
print(f"Estimated gas: {simulation.gas_used}")

## API Reference

### NEARTransactionBuilder

Main class for constructing NEAR transactions.

#### Constructor

NEARTransactionBuilder(
    network: str = "mainnet",
    rpc_url: str = "https://rpc.mainnet.near.org",
    timeout: int = 30
)

**Parameters:**
- `network` (str): Network identifier - "mainnet" or "testnet"
- `rpc_url` (str): NEAR RPC endpoint URL
- `timeout` (int): Request timeout in seconds

#### build_transfer()

Constructs a simple transfer transaction.

async def build_transfer(
    signer_id: str,
    receiver_id: str,
    amount_yocto: str,
    memo: str = None
) -> Transaction

**Parameters:**
- `signer_id` (str): Account ID sending the transaction
- `receiver_id` (str): Account ID receiving tokens
- `amount_yocto` (str): Amount in yoctoNEAR (10^-24 NEAR)
- `memo` (str, optional): Transaction memo

**Returns:** `Transaction` object

**Example:**

import asyncio

async def transfer_example():
    builder = NEARTransactionBuilder()
    
    tx = await builder.build_transfer(
        signer_id="alice.near",
        receiver_id="bob.near",
        amount_yocto="1000000000000000000000000",
        memo="Payment for services"
    )
    
    return tx

result = asyncio.run(transfer_example())

#### build_function_call()

Constructs a smart contract function call transaction.

async def build_function_call(
    signer_id: str,
    contract_id: str,
    method_name: str,
    args: dict,
    gas: str = "30000000000000",
    deposit_yocto: str = "0"
)