> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notareum.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Nota files

# Python: .nota Files

`NotaFileClient` creates, signs, parses, validates, and serializes `.nota` files from Python. Everything on this page is purely off-chain and requires no RPC connection, only a private key for signing. The client is reachable as `ntm.nota`.

## Builder pattern

`.nota` files are produced through a fluent builder chain. Each method returns a `NotaBuilder` so you can chain until you call `serialize()`, `build()`, or `sign()`:

```python theme={"system"}
nota = (
    ntm.nota
    .create(
        type="address",
        chain_name="ethereum",
        chain_id=1,
        identifier="0xabc...",
    )
    .validate()
    .sign("0xYOUR_PRIVATE_KEY_HEX")
)

file_obj = nota.build()       # dict representation
wire = nota.serialize()       # canonical JSON string
```

## `create(...)`

Creates a new builder. Accepts the same fields as the TypeScript SDK but in `snake_case`:

```python theme={"system"}
def create(
    self,
    *,
    type: str,               # "address" | "transaction" | "contract" | "ipfs" | "nft" | "metadata" | custom
    chain_name: str,
    chain_id: int,
    identifier: str,
    network: str | None = None,
    name: str | None = None,
    alias: str | None = None,
    description: str | None = None,
    resource_metadata: dict[str, Any] | None = None,
    issuer_name: str | None = None,
    issuer_entity_type: str | None = None,  # "individual" | "organization"
) -> NotaBuilder
```

## `sign(private_key)`

Signs the builder payload with a private key in hex form. Produces a 65-byte ECDSA signature over the canonical JSON digest:

```python theme={"system"}
def sign(self, private_key: str) -> NotaBuilder
```

The key is never stored by the SDK. Sign as the final step; any mutation after signing invalidates the signature.

## `validate()`

Runs schema and structural validation. Raises on schema mismatch, missing required fields, or (post-signing) a failing signature check:

```python theme={"system"}
def validate(self) -> NotaBuilder
```

## `parse(content)`

Parses a serialized `.nota` JSON string back into a typed dict, verifying the signature if one is present:

```python theme={"system"}
def parse(self, content: str) -> dict[str, Any]
```

## `serialize()` / `serialize(nota)`

Produces canonical, deterministic JSON output. Same content, same bytes, every time:

```python theme={"system"}
# on the builder
def serialize(self) -> str

# on the client, for a raw dict
def serialize(self, nota: dict[str, Any]) -> str
```

Use this output to compute `proof_hash` for on-chain registration, to store in IPFS, or to ship over the wire.

## End-to-end example

```python theme={"system"}
from notareum import Notareum
from eth_account import Account
from eth_utils import keccak

acct = Account.create()

ntm = Notareum(provider=w3, contracts=addresses)  # no account needed for signing

# Producer
nota = (
    ntm.nota
    .create(
        type="address",
        chain_name="ethereum",
        chain_id=1,
        identifier=acct.address,
        alias="alice.eth",
        issuer_name="Alice",
    )
    .validate()
    .sign(acct.key.hex())
)

wire = nota.serialize()

# Consumer
parsed = ntm.nota.parse(wire)
ntm.nota.validate(parsed)   # raises if anything is off
print(parsed["resource"]["identifier"], parsed["signature"]["signer"])

# Proof hash for on-chain registration
proof_hash = "0x" + keccak(wire.encode()).hex()
```

## Related pages

* [.nota File Format](../../protocol/nota-file-format.md)
* [Registry client](registry.md) for turning a `.nota` into an on-chain record
* [Your First .nota File](../../guides/your-first-nota-file.md)