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

# TypeScript: .nota Files

`NotaFileClient` produces, signs, parses, validates, and serializes `.nota` files. Everything on this page happens off-chain: no gas, no RPC calls, just local cryptography and JSON handling. The client is reached via `ntm.nota`.

## The builder pattern

`.nota` files are constructed through a fluent builder. Each method returns a new or mutated `NotaBuilder` so you can chain:

```typescript theme={"system"}
const nota = await ntm.nota
  .create({
    type: "address",
    chainName: "ethereum",
    chainId: 1,
    identifier: "0xabc...",
  })
  .validate()
  .sign(signer);

const file = nota.build();          // the NotaFile object
const json = nota.serialize();      // canonical JSON string
```

## `create(options)`

Starts a new builder from an options object:

```typescript theme={"system"}
create(options: CreateNotaOptions): NotaBuilder
```

`CreateNotaOptions`:

```typescript theme={"system"}
interface CreateNotaOptions {
  type: string;             // "address" | "transaction" | "contract" | "ipfs" | "nft" | "metadata" | custom
  chainName: string;        // canonical chain name, e.g. "ethereum", "polygon", "bitcoin"
  chainId: number;          // EIP-155 chain id (0 for non-EVM)
  network?: string;         // "mainnet", "sepolia", "testnet4", etc.
  identifier: string;       // the resource identifier (address, tx hash, CID, tokenId)
  name?: string;            // human-readable name
  alias?: string;           // requested on-chain alias (e.g. "alice.eth")
  description?: string;
  resourceMetadata?: Record<string, unknown>;
  issuerName?: string;
  issuerEntityType?: "individual" | "organization";
}
```

## `sign(signer)`

Signs the current builder payload with an ethers `Signer`. Produces a 65-byte ECDSA signature over the canonical JSON digest and populates the `signature` section.

```typescript theme={"system"}
async sign(signer: Signer): Promise<NotaBuilder>
```

The builder is immutable after signing in the sense that further modifications invalidate the signature. Always `sign` last.

## `validate()`

Runs structural validation against the `.nota` schema. Throws if any required field is missing, if chain/type values are inconsistent, or if the signature is present and does not match the payload.

```typescript theme={"system"}
validate(): NotaBuilder
```

Validation is cheap and intended to run on every received file before trust is placed in its contents.

## `parse(content)`

Turns a serialized `.nota` JSON string back into a typed `NotaFile` object:

```typescript theme={"system"}
parse(content: string): NotaFile
```

It also verifies the signature (if present) against the embedded public key or derived signer address. A failing signature raises an error.

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

Canonical JSON serialization. The output is deterministic: same logical content always produces byte-identical output, so hashes line up across SDKs and platforms.

```typescript theme={"system"}
// on the builder
serialize(): string

// on the client, for a raw NotaFile
serialize(nota: NotaFile): string
```

Use `serialize` before computing any on-chain `proofHash` or storing the file in IPFS.

## End-to-end example

```typescript theme={"system"}
import { Notareum } from "@notareum/sdk";
import { Wallet } from "ethers";

const signer = new Wallet(process.env.PRIVATE_KEY!);
const ntm = Notareum({ provider: signer.provider!, signer, contracts });

// Producer side
const signed = await ntm.nota
  .create({
    type: "address",
    chainName: "ethereum",
    chainId: 1,
    identifier: await signer.getAddress(),
    alias: "alice.eth",
    issuerName: "Alice",
  })
  .validate()
  .sign(signer);

const wire = signed.serialize();

// Consumer side
const received = ntm.nota.parse(wire);
ntm.nota.validate(received);      // throws on any mismatch
console.log(received.resource.identifier, received.signature.signer);
```

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