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

# .nota File Format

The `.nota` file is the portable, cryptographically signed JSON container at the heart of the Notareum Protocol. This page documents the v1.0 schema in full: every field, every resource type, and how the canonical message for signing is constructed. MIME type is `application/vnd.notareum.nota+json` and the file extension is `.nota`.

## Top-level structure

A `.nota` file has six top-level objects. Four are required: `version`, `type`, `chain`, `resource`, and `signature`. Two are optional but strongly recommended: `verification` and `issuer`.

```json theme={"system"}
{
  "version": "1.0",
  "type": "address",
  "chain": { "name": "ethereum", "chainId": 1, "network": "mainnet" },
  "resource": {
    "identifier": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "name": "Alice Main Wallet",
    "alias": "alice.nota",
    "description": "Publicly known Ethereum address",
    "metadata": { "ens": "vitalik.eth" }
  },
  "verification": {
    "status": "verified",
    "level": "enhanced",
    "validators": ["0xVal1...", "0xVal2...", "0xVal3..."],
    "proofHash": "0xabcdef1234..."
  },
  "signature": {
    "algorithm": "ECDSA",
    "curve": "secp256k1",
    "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "message": "Notareum v1.0 | {...} | 1700000000",
    "signature": "0x...",
    "timestamp": 1700000000
  },
  "issuer": {
    "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "name": "Alice",
    "verified": true,
    "entityType": "individual"
  }
}
```

## Resource types

The `type` field MUST be one of six well-known values. Each maps to a `uint8` constant used when computing the resource ID.

| Type String     | Enum Value | Description                               |
| --------------- | ---------- | ----------------------------------------- |
| `"address"`     | `0`        | Wallet addresses                          |
| `"transaction"` | `1`        | Transaction hashes and payment requests   |
| `"contract"`    | `2`        | Smart contract addresses                  |
| `"ipfs"`        | `3`        | IPFS content identifiers                  |
| `"nft"`         | `4`        | Non-fungible tokens                       |
| `"metadata"`    | `5`        | Arbitrary structured data and credentials |

Additional types can be added through governance by calling `addResourceType()` on the registry. Parsers MUST reject types that are not registered in `validResourceTypes`.

## Chain object

The `chain` object provides EIP-155 chain context.

| Field     | Type    | Required         | Description                                                                                                                |
| --------- | ------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `name`    | string  | Required         | Canonical chain name: `ethereum`, `bitcoin`, `solana`, `polygon`, `arbitrum`, `optimism`, `base`, `bnb`, `avalanche`, etc. |
| `chainId` | integer | Required for EVM | EIP-155 chain ID. MUST be `0` for non-EVM chains.                                                                          |
| `network` | string  | Optional         | `mainnet`, `testnet`, `devnet`. Defaults to `mainnet`.                                                                     |

Common EVM chain IDs: Ethereum `1`, Polygon `137`, Arbitrum One `42161`, Optimism `10`, BNB Chain `56`, Avalanche C-Chain `43114`, Base `8453`.

## Resource object

| Field         | Type   | Required | Description                                                                 |
| ------------- | ------ | -------- | --------------------------------------------------------------------------- |
| `identifier`  | string | Required | Canonical resource identifier. Format depends on `type`.                    |
| `name`        | string | Optional | Human-readable name.                                                        |
| `alias`       | string | Optional | Short alias like `alice.nota`. Must match the on-chain alias if registered. |
| `description` | string | Optional | Free-form description, SHOULD be under 500 characters.                      |
| `metadata`    | object | Optional | Type-specific structured metadata.                                          |

Identifier formats by type:

| Type          | Identifier Format                      | Example                                      |
| ------------- | -------------------------------------- | -------------------------------------------- |
| `address`     | Checksummed hex (EVM) or native format | `0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045` |
| `transaction` | `0x`-prefixed 32-byte hash             | `0xabcdef1234...`                            |
| `contract`    | Checksummed hex address                | `0x1234567890abcdef...`                      |
| `ipfs`        | CIDv0 or CIDv1, optionally `ipfs://`   | `ipfs://QmXoypiz...`                         |
| `nft`         | `<contract-address>/<token-id>`        | `0xBC4CA0...F13D/1`                          |
| `metadata`    | DID string or arbitrary URI            | `did:ethr:0x1234...`                         |

## Signature object

| Field       | Type    | Required | Description                                                        |
| ----------- | ------- | -------- | ------------------------------------------------------------------ |
| `algorithm` | string  | Required | `ECDSA` for EVM, `EdDSA` for ed25519 chains.                       |
| `curve`     | string  | Required | `secp256k1` for EVM, `ed25519` for non-EVM.                        |
| `address`   | string  | Required | Signing address (checksummed for EVM).                             |
| `message`   | string  | Required | The canonical message that was signed.                             |
| `signature` | string  | Required | The cryptographic signature (65-byte `r, s, v` hex for EVM ECDSA). |
| `timestamp` | integer | Required | Unix timestamp in seconds at signing time.                         |

## Canonical message construction

When signing a `.nota` file, the signer MUST follow this exact procedure:

1. Serialize the `resource` object as canonical JSON (keys sorted alphabetically, no extra whitespace).
2. Prepend the string `"Notareum v1.0 | "`.
3. Append `" | " + timestamp` where `timestamp` is Unix seconds.

Example canonical message:

```
Notareum v1.0 | {"alias":"alice.nota","description":"Main wallet","identifier":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","name":"Alice Main Wallet"} | 1700000000
```

For EVM chains, the message MUST be signed using EIP-191 personal sign: the signing implementation prepends `"\x19Ethereum Signed Message:\n" + len(message)` before hashing.

## Verification object

| Field        | Type   | Required | Description                                                    |
| ------------ | ------ | -------- | -------------------------------------------------------------- |
| `status`     | string | Required | `unverified`, `pending`, `verified`, `disputed`, or `revoked`. |
| `level`      | string | Optional | `basic`, `enhanced`, or `institutional`.                       |
| `validators` | array  | Optional | Array of attesting validator addresses.                        |
| `proofHash`  | string | Optional | `bytes32` hex of off-chain proof material anchored on-chain.   |

## Create and sign in every language

**TypeScript:**

```typescript theme={"system"}
const nota = await ntm.nota
  .create({
    type: "address",
    chainId: 1,
    chainName: "ethereum",
    identifier: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    name: "Alice Main Wallet",
    alias: "alice.nota",
  })
  .sign(signer);

console.log(nota.serialize());
```

**Python:**

```python theme={"system"}
nota = ntm.nota.create(
    type="address",
    chain_id=1,
    chain_name="ethereum",
    identifier="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    name="Alice Main Wallet",
    alias="alice.nota",
)
signed = nota.sign(private_key)
print(signed.serialize())
```

**Rust:**

```rust theme={"system"}
let signed = ntm.nota.create(CreateNotaOptions {
    type_: "address".into(),
    chain_id: 1,
    chain_name: "ethereum".into(),
    identifier: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045".into(),
    name: Some("Alice Main Wallet".into()),
    alias: Some("alice.nota".into()),
    ..CreateNotaOptions::new(
        "address",
        "ethereum",
        1,
        "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    )
})?
.validate()?
.sign(&private_key_hex)?;

println!("{}", signed.serialize()?);
```

## File size constraints

* Typical size: 1 to 2 KB
* Maximum permitted size: 64 KB
* `resource.metadata` maximum: 32 KB

## Security considerations

**Signature replay.** The `timestamp` field provides replay resistance. Verifiers SHOULD reject signatures older than 30 days for off-chain verification. No expiry for on-chain anchored resources.

**Address encoding.** EVM addresses MUST pass EIP-55 checksum validation. Parsers MUST reject non-checksummed addresses to prevent homograph attacks.

**Metadata injection.** Implementations MUST sanitize metadata before rendering in UI contexts to prevent XSS or JSON injection.

**Schema validation.** Parsers MUST reject files with missing required fields, invalid types, or malformed identifiers rather than silently ignoring invalid data.

## Related pages

* [Resource Registry](resource-registry.md) for on-chain anchoring
* [Verification Engine](verification-engine.md) for the attestation flow
* [TypeScript SDK: .nota Files](../sdks/typescript/nota-files.md)
* [Python SDK: .nota Files](../sdks/python/nota-files.md)
* [Rust SDK: .nota Files](../sdks/rust/nota-files.md)