token-network 0.1.1
Validate input and return token network config (e.g. network.bitcoin, network.bsc.usdt)
License: MIT
Requires Python: >=3.8
Keywords: blockchain, tokens, networks, crypto, config

# token-network

Python library that validates input and returns token network config. Resolve networks and tokens by name/symbol and get merged config (e.g. USDT on BSC with contract address and decimals).

## Install

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

From source (development):

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

## Quick start

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

# Attribute access
network.bitcoin.config          # Bitcoin network config
network.bsc.usdt               # USDT on BSC (contract, decimal, etc.)

# By name/symbol
get_network("bitcoin")         # Full network data
get_token("USDT")              # Token info by symbol, slug, or name
get_token_network("USDT", "bsc")  # Token-on-network config
```

---

## API reference

All identifiers (network name, token symbol/slug/name) are **case-insensitive**. Unknown network or token raises `TokenNetworkError`.

### Attribute access: `network`

Use `network.<network>` and optionally `network.<network>.<token>` for direct access.

| Usage | Returns |
|--------|--------|
| `network.bitcoin` | Network node (see below) |
| `network.bitcoin.config` | Network config dict |
| `network.bitcoin.tokens` | List of token bindings on this network |
| `network.bitcoin.to_dict()` | `{"config": {...}, "tokens": [...]}` |
| `network.bsc.usdt` | Token-on-network dict (network + token + contract_address, decimal, native) |

**Example**

```python
network.bitcoin.config
# {'network_type': 'UTXO', 'token_standard': 'BTC', 'base_token': 'BTC', 'base_token_decimal': 8, ...}

network.bsc.usdt
# {'network': {...}, 'token': {...}, 'contract_address': '0x55d398326f99059fF775485246999027B3197955', 'decimal': 18, 'native': False}
```

---

### `get_networks()`

Returns a sorted list of all network ids.

**Returns:** `list[str]` — e.g. `['bitcoin', 'bsc', 'dogecoin', 'ethereum', 'ripple', 'solana', 'tron']`

**Example**

```python
from token_network import get_networks
get_networks()
# ['bitcoin', 'bsc', 'dogecoin', 'ethereum', 'ripple', 'solana', 'tron']
```

Also available as `network.get_networks()`.

---

### `get_tokens()`

Returns a sorted list of all token symbols.

**Returns:** `list[str]` — e.g. `['AAVE', 'BNB', 'BTC', 'ETH', 'USDT', ...]`

**Example**

```python
from token_network import get_tokens
get_tokens()
# ['AAVE', 'BNB', 'BTC', 'DOGE', 'ETH', 'LINK', 'SHIB', 'SOL', 'TRX', 'UNI', 'USDC', 'USDT', 'XRP']
```

Also available as `network.get_tokens()`.

---

### `get_token(identifier)`

Get token object by **symbol**, **slug**, or **name** (case-insensitive).

**Parameters**

- `identifier` — Token symbol (e.g. `USDT`), slug (e.g. `usdt`), or name (e.g. `tether`).

**Returns:** `dict` — Token info: `slug`, `symbol`, `standard_symbol`, `name`, `precision`, `factor`.

**Raises:** `TokenNetworkError` if no token matches.

**Example**

```python
from token_network import get_token
get_token("USDT")
# {'slug': 'usdt', 'symbol': 'USDT', 'standard_symbol': 'USDT', 'name': 'tether', 'precision': 6, 'factor': '1e6'}
get_token("tether")   # same
get_token("btc")      # Bitcoin token info
```

Also available as `network.get_token(identifier)`.

---

### `get_network(identifier)`

Get network object by **network name/id** (case-insensitive).

**Parameters**

- `identifier` — Network name (e.g. `bitcoin`, `bsc`, `ethereum`).

**Returns:** `dict` with keys:
- `config` — Network config (network_type, token_standard, base_token, confirmation_number, etc.).
- `tokens` — List of token bindings on this network.

**Raises:** `TokenNetworkError` if network is unknown.

**Example**

```python
from token_network import get_network
get_network("bitcoin")
# {'config': {'network_type': 'UTXO', 'base_token': 'BTC', ...}, 'tokens': [...]}
get_network("BSC")
```

Also available as `network.get_network(identifier)`. Same shape as `network.bitcoin.to_dict()`.

---

### `get_token_network(token_identifier, network_identifier)`

Get token_network config for a **token** on a **network** (case-insensitive).

**Parameters**

- `token_identifier` — Token symbol, slug, or name (e.g. `USDT`, `usdt`, `tether`).
- `network_identifier` — Network name (e.g. `bsc`, `ethereum`).

**Returns:** `dict` with keys:
- `network` — Network config.
- `token` — Token info (slug, symbol, name, precision, factor).
- `contract_address` — Contract address or `None` for native.
- `decimal` / `decimals` — Decimals on this network.
- `native` / `type` — Whether it is the chain’s native asset.

**Raises:** `TokenNetworkError` if token or network is unknown, or if the token is not on that network.

**Example**

```python
from token_network import get_token_network
get_token_network("USDT", "bsc")
# {'network': {...}, 'token': {...}, 'contract_address': '0x55d398326f99059fF775485246999027B3197955', 'decimal': 18, 'native': False}
get_token_network("tether", "BSC")   # same
get_token_network("ETH", "ethereum")
```

Same data as `network.bsc.usdt`. Also available as `network.get_token_network(token_identifier, network_identifier)`.

---

### `TokenNetworkError`

Exception raised when:
- A network name is unknown.
- A token (symbol/slug/name) is unknown.
- A token is requested on a network where it is not defined.

**Example**

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

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

try:
    get_token("unknown_token")
except TokenNetworkError as e:
    print(e)  # Unknown token: 'unknown_token'. Known tokens: [...]

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

---

## Data sources

Config is loaded from YAML in the package’s `data` directory:

| File | Content |
|------|--------|
| `networks.yaml` | Chain config (network_type, token_standard, base_token, confirmation_number, …) |
| `tokens.yaml` | Token definitions (symbol, slug, name, precision, factor) |
| `token_networks.yaml` | Token–network bindings (contract_address, decimal, native) |

To change data, edit the YAML files in `token_network/data/`.

---

## Publishing to PyPI

To allow `pip install token-network` from PyPI:

1. Create an account on [pypi.org](https://pypi.org).
2. `pip install build twine`
3. `python -m build` then `twine upload dist/*`

For testing: `twine upload --repository testpypi dist/*`, then  
`pip install --index-url https://test.pypi.org/simple/ token-network`.

---

## Development

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