Metadata-Version: 2.4
Name: token-network
Version: 0.4.1
Summary: Validate input and return token network config (e.g. network.bitcoin, network.bsc.usdt)
License: MIT
Keywords: blockchain,tokens,networks,crypto,config
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: PyYAML>=6.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: requires-python

# token-network

Resolve blockchain networks and tokens by name and get config (contract addresses, decimals, confirmations). All returned objects are **Pydantic models** (`TokenDto`, `NetworkConfigDto`, `TokenOnNetworkDto`, `NetworkDataDto`).

## Install

```bash
pip install token-network
```

From source:

```bash
pip install -e .
```

## Examples

### Get a network and its settings

```python
from token_network import network

# By name (callable)
bitcoin = network("bitcoin")

bitcoin.decimal               # 8  (base token decimals)
bitcoin.confirmation_number    # 2  (required confirmations)
bitcoin.config                # NetworkConfigDto (Pydantic)
bitcoin.__dict__()            # Full data: {"config": {...}, "tokens": [...]}
```

### List tokens on a network

```python
from token_network import network

ethereum = network("ethereum")
tokens = ethereum.tokens      # list of TokenOnNetworkDto

for t in tokens:
    print(t.token.symbol, t.contract_address or "native", t.decimal)
# ETH None 18
# USDT 0xdAC17F958D2ee523a2206206994597C13D831ec7 6
# ...
```

### Get one token on a network

```python
from token_network import get_token_on_network

usdt = get_token_on_network(network="ethereum", token_abbr="USDT")

usdt.contract_address   # "0xdAC17F958D2ee523a2206206994597C13D831ec7"
usdt.decimal            # 6
usdt.native             # False
usdt.token.symbol       # "USDT"
usdt.__dict__()         # All fields as dict (or use .model_dump())
```

### Same via attribute access

```python
from token_network import network

# network.ethereum.usdt is the same as get_token_on_network(network="ethereum", token_abbr="USDT")
usdt = network.ethereum.usdt
assert usdt.contract_address == "0xdAC17F958D2ee523a2206206994597C13D831ec7"
```

### Get token or network by identifier (Pydantic models)

```python
from token_network import get_token, get_network, get_token_network

# Token by symbol, slug, or name (case-insensitive)
token = get_token("USDT")       # TokenDto
print(token.symbol, token.precision)   # USDT 6

# Network with config + tokens
net = get_network("bitcoin")    # NetworkDataDto
print(net.config.base_token)           # BTC
print(len(net.tokens))                 # 1 (e.g. BTC)

# Token on a specific network
ton = get_token_network("USDT", "bsc")  # TokenOnNetworkDto
print(ton.contract_address)
```

### List all networks and tokens

```python
from token_network import get_networks, get_tokens

get_networks()   # ['bitcoin', 'bsc', 'dogecoin', 'ethereum', 'ripple', 'solana', 'tron']
get_tokens()     # ['AAVE', 'BNB', 'BTC', 'ETH', 'USDT', ...]
```

### Testnet config

```python
from token_network import NetworkAccessor

testnet = NetworkAccessor(testnet=True)
bsc = testnet("bsc")
usdt_test = testnet.bsc.usdt   # USDT on BSC from token_networks_testnet.yaml
```

### Error handling

```python
from token_network import network, get_token_on_network, TokenNetworkError

try:
    network("unknown_chain")
except TokenNetworkError as e:
    print(e)  # Unknown network: 'unknown_chain'. Known networks: ...

try:
    get_token_on_network(network="bitcoin", token_abbr="USDT")
except TokenNetworkError as e:
    print(e)  # Token 'USDT' is not on network 'bitcoin'. Available on this network: ['BTC']
```

## API summary

| What you want | How |
|---------------|-----|
| Network by name | `network("bitcoin")` or `network.bitcoin` |
| Base decimals / confirmations | `network("bitcoin").decimal`, `.confirmation_number` |
| Full network data as dict | `network("bitcoin").__dict__()` or `.to_dict()` |
| Tokens on a network | `network("ethereum").tokens` → list of `TokenOnNetworkDto` |
| One token on a network | `get_token_on_network(network="ethereum", token_abbr="USDT")` or `network.ethereum.usdt` |
| Token info | `get_token("USDT")` → `TokenDto` |
| Network + tokens | `get_network("bitcoin")` → `NetworkDataDto` |
| Token on network by ids | `get_token_network("USDT", "bsc")` → `TokenOnNetworkDto` |

All identifiers are **case-insensitive**. Unknown network/token raises `TokenNetworkError`.

## Pydantic models

- **`TokenDto`** — Token definition (slug, symbol, name, precision, factor). From `get_token()`.
- **`NetworkConfigDto`** — Chain config (slug, name, network_type, base_token_decimal, confirmation_number, …). From `network("x").config` and inside `TokenOnNetworkDto.network`.
- **`TokenOnNetworkDto`** — Token on a network (network, token, contract_address, decimal, native, type). From `get_token_on_network()`, `get_token_network()`, `network.ethereum.usdt`.
- **`NetworkDataDto`** — Result of `get_network()`: `config` + `tokens` (list of `TokenOnNetworkDto`).

Use `.model_dump()` to export any model as a dict.

## Data sources

YAML under `token_network/data/`:

- `networks.yaml` — chain config
- `tokens.yaml` — token definitions
- `token_networks.yaml` — mainnet bindings (token + network → contract, decimals)
- `token_networks_testnet.yaml` — testnet bindings (used with `NetworkAccessor(testnet=True)`)

## Development

```bash
pip install -e ".[dev]"
pytest
```
