# Chain & State

## Chain Information

### get_chain_identifier

Get the unique identifier of the connected chain.

```python
async def get_chain_identifier() -> str
```

**Returns**: `str`. Chain identifier.

### get_server_version

Get the server's software version.

```python
async def get_server_version() -> str
```

**Returns**: `str`

### get_protocol_version

Get the current protocol version number.

```python
async def get_protocol_version() -> int
```

**Returns**: `int`

### get_architecture_version

Get the current model architecture version required by the protocol.

```python
async def get_architecture_version() -> int
```

**Returns**: `int`. Must match `ARCHITECTURE_VERSION` in `soma-models`.

### get_embedding_dim

Get the required embedding dimension for the current architecture.

```python
async def get_embedding_dim() -> int
```

**Returns**: `int`. For example, `2048` for V1.

### get_model_min_stake

Get the minimum stake required to register a model, in shannons.

```python
async def get_model_min_stake() -> int
```

**Returns**: `int`. Minimum stake in shannons.

### check_api_version

Verify that the SDK and server API versions are compatible. Raises an exception on mismatch.

```python
async def check_api_version() -> None
```

#### Example

```python
await client.check_api_version()  # raises on mismatch
```

## Objects & Balances

### get_object

Fetch a network object by ID.

```python
async def get_object(object_id: str) -> ObjectRef
```

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `object_id` | `str` | Yes | - | Hex-encoded object ID |

**Returns**: [`ObjectRef`](https://docs.soma.org/reference/sdk/types/#objectref)

### get_object_with_version

Fetch a specific version of a network object.

```python
async def get_object_with_version(object_id: str, version: int) -> ObjectRef
```

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `object_id` | `str` | Yes | - | Hex-encoded object ID |
| `version` | `int` | Yes | - | Object version number |

**Returns**: [`ObjectRef`](https://docs.soma.org/reference/sdk/types/#objectref)

### get_balance

Get the SOMA balance for an address.

```python
async def get_balance(address: str) -> float
```

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `address` | `str` | Yes | - | SOMA address |

**Returns**: `float`. Balance in SOMA.

#### Example

```python
balance = await client.get_balance("0x1234...")
print(f"{balance} SOMA")
```

### list_owned_objects

List objects owned by an address.

```python
async def list_owned_objects(
    owner: str,
    object_type: Optional[str] = None,
    limit: Optional[int] = None,
) -> list[ObjectRef]
```

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `owner` | `str` | Yes | - | Owner address |
| `object_type` | `str` | No | `None` | Filter by object type |
| `limit` | `int` | No | `None` | Maximum number of results |

**Returns**: `list[`[`ObjectRef`](https://docs.soma.org/reference/sdk/types/#objectref)`]`

## System State

### get_latest_system_state

Fetch the full system state for the current epoch, including validators, parameters, and model registry.

```python
async def get_latest_system_state() -> SystemState
```

**Returns**: [`SystemState`](https://docs.soma.org/reference/sdk/types/#systemstate)

### get_epoch

Get information about a specific epoch, or the current epoch if not specified.

```python
async def get_epoch(epoch: Optional[int] = None) -> EpochInfo
```

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `epoch` | `int` | No | `None` | Epoch number (current if omitted) |

**Returns**: [`EpochInfo`](https://docs.soma.org/reference/sdk/types/#epochinfo)

## Checkpoints

### get_latest_checkpoint

Get the most recent finalized checkpoint.

```python
async def get_latest_checkpoint() -> CheckpointSummary
```

**Returns**: [`CheckpointSummary`](https://docs.soma.org/reference/sdk/types/#checkpointsummary)

### get_checkpoint_summary

Get a checkpoint by sequence number.

```python
async def get_checkpoint_summary(sequence_number: int) -> CheckpointSummary
```

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `sequence_number` | `int` | Yes | - | Checkpoint sequence number |

**Returns**: [`CheckpointSummary`](https://docs.soma.org/reference/sdk/types/#checkpointsummary)

## Epoch Helpers

### wait_for_next_epoch

Block until the next epoch begins.

```python
async def wait_for_next_epoch(timeout: float = 120.0) -> int
```

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `timeout` | `float` | No | `120.0` | Maximum seconds to wait |

**Returns**: `int`. The new epoch number.

#### Example

```python
new_epoch = await client.wait_for_next_epoch(timeout=300)
print(f"Epoch {new_epoch} started")
```

### get_next_epoch_timestamp

Get the estimated UNIX timestamp (ms) when the next epoch starts. Computed as `epoch_start_timestamp_ms + epoch_duration_ms` from the current system state.

```python
async def get_next_epoch_timestamp() -> int
```

**Returns**: `int`. Estimated UNIX timestamp in milliseconds.

### get_following_epoch_timestamp

Get the estimated UNIX timestamp (ms) when the epoch after next starts. Computed as `epoch_start_timestamp_ms + 2 * epoch_duration_ms`. Useful for scheduling actions that require two epoch boundaries (e.g., `claim_rewards` after `submit_data`).

```python
async def get_following_epoch_timestamp() -> int
```

**Returns**: `int`. Estimated UNIX timestamp in milliseconds.