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

{
  "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:

Serialize the resource object as canonical JSON (keys sorted alphabetically, no extra whitespace).
Prepend the string "Notareum v1.0 | ".
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.

TypeScript:

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:

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:

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.

Resource Registry for on-chain anchoring
Verification Engine for the attestation flow
TypeScript SDK: .nota Files
Python SDK: .nota Files
Rust SDK: .nota Files

Getting Started

Protocol

Token

SDKs

Guides

Use Cases

Smart Contracts

Reference

Resources

Nota file format

.nota File Format

Top-level structure

Resource types

Chain object

Resource object

Signature object

Canonical message construction

Verification object

File size constraints

Security considerations

​.nota File Format

​Top-level structure

​Resource types

​Chain object

​Resource object

​Signature object

​Canonical message construction

​Verification object

​Create and sign in every language

​File size constraints

​Security considerations

​Related pages

.nota File Format

Top-level structure

Resource types

Chain object

Resource object

Signature object

Canonical message construction

Verification object

Create and sign in every language

File size constraints

Security considerations

Related pages