Metadata-Version: 2.4
Name: near-langchain-tx-builder
Version: 0.1.1
Summary: LangChain tools to build, validate, and simulate NEAR transactions
Project-URL: Homepage, https://github.com/mastrophot/near-langchain-tx-builder
Project-URL: Repository, https://github.com/mastrophot/near-langchain-tx-builder
Project-URL: Issues, https://github.com/mastrophot/near-langchain-tx-builder/issues
Author-email: Mastrophot <butrikmax@gmail.com>
License: MIT
License-File: LICENSE
Keywords: langchain,near,python,tool,transactions
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27.0
Requires-Dist: langchain-core>=0.2.30
Requires-Dist: pydantic>=2.7.0
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: respx>=0.21.1; extra == 'dev'
Description-Content-Type: text/markdown

# near-langchain-tx-builder

LangChain tools for building and simulating NEAR transactions before execution.

## Features

- Build transfer transactions
- Build function-call transactions
- Batch multiple actions into one transaction
- Simulate transactions before sending (validation + account checks + optional RPC preflight)
- Estimate gas and rough transaction cost in NEAR
- Reusable transaction templates
- Clear, structured error messages

## Install

```bash
pip install near-langchain-tx-builder
```

## Quick Start (LangChain)

```python
from near_langchain_tx_builder import get_near_transaction_tools

tools = get_near_transaction_tools()

# Tool names:
# - near_build_transfer_tx
# - near_build_function_call_tx
# - near_build_batch_tx
# - near_estimate_tx_gas
# - near_simulate_tx
# - near_apply_tx_template
# - near_list_tx_templates
```

## Manual Usage

```python
from near_langchain_tx_builder import NEARTransactionBuilder

builder = NEARTransactionBuilder()

tx = builder.build_transfer_tx(
    signer_id="alice.near",
    receiver_id="bob.near",
    amount_near="1.5",
    network="mainnet",
)

estimate = builder.estimate_gas(tx)
simulation = builder.simulate_transaction(tx, check_accounts=False)
```

## Transaction Templates

Built-in templates:

- `simple_transfer`
- `ft_transfer`
- `nft_transfer`
- `contract_call`

Example:

```python
tx = builder.apply_template(
    template_name="ft_transfer",
    signer_id="alice.near",
    receiver_id="usdc.fakes.testnet",
    variables={
        "method_name": "ft_transfer",
        "args": {"receiver_id": "bob.near", "amount": "1000000"},
        "deposit_near": "0.000000000000000000000001",
        "gas_tgas": 30,
    },
    network="testnet",
)
```

## Error Handling

Methods raise `NEARTxBuilderError` with machine-readable codes:

- `invalid_account_id`
- `invalid_amount`
- `invalid_action`
- `rpc_error`
- `simulation_error`

## Notes on Simulation

NEAR RPC does not provide a full dry-run for unsigned arbitrary state-changing transactions.
This package simulates via:

- strict local validation,
- optional account existence checks,
- gas/cost estimation using RPC gas price,
- optional preflight `call_function` for likely view-compatible calls.

## License

MIT


## Reliability

- NEAR RPC fallback endpoints with retries/backoff
- Improved RPC error details for easier debugging
- CI workflow (tests + build)
