> ## 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

# Rust: .nota Files

`NotaFileClient` in the Rust SDK creates, signs, parses, validates, and serializes `.nota` files. Everything on this page is off-chain and synchronous: no network, no async, just local cryptography over `serde_json`. Access the client as the `nota` field on the `Notareum` factory: `ntm.nota`.

## Builder pattern

The builder is owned: each method consumes and returns `NotaBuilder`, which makes signing and validation ordering explicit in the type system.

```rust theme={"system"}
use notareum::CreateNotaOptions;

let builder = ntm.nota.create(CreateNotaOptions {
    type_: "address".into(),
    chain_name: "ethereum".into(),
    chain_id: 1,
    identifier: "0xabc...".into(),
    ..CreateNotaOptions::new("address", "ethereum", 1, "0xabc...")
})?;

let signed = builder.validate()?.sign(&private_key_hex)?;
let file   = signed.clone().build();    // NotaFile
let wire   = signed.serialize()?;        // canonical JSON
```

`CreateNotaOptions::new(type_, chain_name, chain_id, identifier)` builds an instance with only the required fields populated; the optional fields default to `None`. The struct field is named `type_` (trailing underscore) because `type` is a reserved Rust keyword.

## `create(options)`

Starts a new builder:

```rust theme={"system"}
pub fn create(
    &self,
    options: CreateNotaOptions,
) -> Result<NotaBuilder, SdkError>
```

`CreateNotaOptions` fields mirror the TS/Python SDKs: `type_`, `chain_name`, `chain_id`, `network`, `identifier`, `name`, `alias`, `description`, `resource_metadata`, `issuer_name`, `issuer_entity_type`.

## `sign(private_key_hex)`

Signs the builder payload with a private key hex string. Produces a 65-byte ECDSA (secp256k1) signature using EIP-191 personal-sign over a canonical message:

```rust theme={"system"}
pub fn sign(
    mut self,
    private_key_hex: &str,
) -> Result<Self, SdkError>
```

After signing, the builder carries an attached `Signature` and any further mutation will fail validation.

## `validate()`

Validates schema, field consistency, and signature (if any):

```rust theme={"system"}
pub fn validate(self) -> Result<Self, SdkError>
```

## `parse(content)` and `serialize(&nota)`

On the client (not the builder):

```rust theme={"system"}
pub fn parse(&self, content: &str) -> Result<NotaFile, SdkError>
pub fn validate(&self, nota: &NotaFile) -> Result<(), SdkError>
pub fn is_valid(&self, nota: &NotaFile) -> bool
pub fn serialize(&self, nota: &NotaFile) -> Result<String, SdkError>
```

`serialize` produces canonical JSON. The same input always produces the same bytes, so hashes line up across SDKs and platforms.

## End-to-end example

```rust theme={"system"}
use notareum::CreateNotaOptions;

// Producer
let signed = ntm.nota
    .create(CreateNotaOptions {
        type_: "address".into(),
        chain_name: "ethereum".into(),
        chain_id: 1,
        identifier: "0xabc...".into(),
        alias: Some("alice.eth".into()),
        issuer_name: Some("Alice".into()),
        ..CreateNotaOptions::new("address", "ethereum", 1, "0xabc...")
    })?
    .validate()?
    .sign(&private_key_hex)?;

let wire = signed.serialize()?;

// Consumer
let parsed = ntm.nota.parse(&wire)?;
ntm.nota.validate(&parsed)?;
println!(
    "{} signed by {}",
    parsed.resource.identifier,
    parsed.signature.signer
);
```

## Errors

All fallible calls return `Result<T, SdkError>`. `SdkError` variants cover parsing failures, schema issues, signature mismatch, and invalid resource type references. Build against the `thiserror` display impl or pattern-match to branch on specific cases; see [Error Codes](../../reference/error-codes.md) for a cross-SDK mapping.

## Lower-level primitives

The off-chain building blocks (`.nota` builder/parser/validator, keccak256, EIP-191 signing, resource id derivation, quorum/tier math) live under \[`notareum::core`] and are re-exported transitively by the high-level clients. Reach into `notareum::core` directly if you need to use the primitives without the contract layer.

## Related

* [.nota File Format protocol page](../../protocol/nota-file-format.md)
* [Registry client](registry.md)
* [Your First .nota File guide](../../guides/your-first-nota-file.md)