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

# Your first nota file

# Your First .nota File

This guide takes you from an empty project to a signed `.nota` file you can share with anyone. By the end, you will have:

1. Created a `.nota` file describing a wallet address.
2. Signed it with an Ethereum key.
3. Serialized it to a canonical JSON string.
4. Handed it to a recipient.
5. Verified the signature on the recipient side.

No on-chain calls are involved. Everything here runs locally with one dependency: a signer.

## Prerequisites

* Node.js 20+ (Python 3.10+ or Rust 1.75+ also work; examples here use TypeScript)
* An Ethereum private key for signing (a throwaway is fine for the tutorial)

## Step 1: Install the SDK

```bash theme={"system"}
npm init -y
npm install @notareum/sdk ethers
```

## Step 2: Create the file

Create `alice.ts`:

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

const signer = new Wallet(process.env.PRIVATE_KEY!);

// Dummy contracts object, no on-chain calls below need real addresses
const contracts = {
  notaToken: "0x" + "00".repeat(20),
  veNota: "0x" + "00".repeat(20),
  validatorStaking: "0x" + "00".repeat(20),
  notaRegistry: "0x" + "00".repeat(20),
  verificationEngine: "0x" + "00".repeat(20),
  slashingManager: "0x" + "00".repeat(20),
  feeManager: "0x" + "00".repeat(20),
  accessManager: "0x" + "00".repeat(20),
};

const ntm = Notareum({ provider: signer.provider!, signer, contracts });

const signed = await ntm.nota
  .create({
    type: "address",
    chainName: "ethereum",
    chainId: 1,
    identifier: await signer.getAddress(),
    name: "Alice's hot wallet",
    description: "Primary personal wallet",
    issuerName: "Alice",
    issuerEntityType: "individual",
  })
  .validate()
  .sign(signer);

const wire = signed.serialize();
console.log(wire);
```

Run it:

```bash theme={"system"}
PRIVATE_KEY=0x... npx tsx alice.ts > alice.nota
```

You now have a file `alice.nota` on disk. Open it; it's a JSON document with a `resource` block describing the wallet, an `issuer` block identifying Alice, and a `signature` block holding the ECDSA signature and signer address.

## Step 3: Share the file

The JSON string is safe to send over any channel:

* Paste it into an email, a Signal/Telegram/WhatsApp message, or a chat DM.
* Encode it as a QR code with any standard library.
* Attach the file to a Git commit, a GitHub issue, an IPFS upload.
* Serve it from an HTTPS endpoint on your site.

```mermaid theme={"system"}
sequenceDiagram
    participant Alice
    participant Bob
    Alice->>Alice: create().validate().sign()
    Alice->>Alice: serialize()
    Alice->>Bob: send alice.nota (email, QR, IPFS, HTTP)
    Bob->>Bob: parse(content)
    Bob->>Bob: validate(nota)
    Bob->>Bob: trust decision
```

## Step 4: Verify on the recipient side

Create `bob.ts`:

```typescript theme={"system"}
import { Notareum } from "@notareum/sdk";
import { JsonRpcProvider } from "ethers";
import { readFileSync } from "node:fs";

const provider = new JsonRpcProvider("https://rpc.ankr.com/eth");
const ntm = Notareum({ provider, contracts });   // no signer needed

const wire = readFileSync("alice.nota", "utf8");
const nota = ntm.nota.parse(wire);
ntm.nota.validate(nota);     // throws on any mismatch

console.log("Resource:", nota.resource.identifier);
console.log("Signed by:", nota.signature.signer);
console.log("Issuer:", nota.issuer?.name);
```

Run it:

```bash theme={"system"}
npx tsx bob.ts
```

If the signature is valid, Bob sees Alice's wallet address, signer address, and issuer name. If the file was tampered with, `parse()` or `validate()` throws.

## What you learned

* `.nota` files are self-contained JSON documents.
* Signing is purely local: no gas, no RPC, no protocol state.
* Serialization is canonical: every SDK produces byte-identical output.
* Validation detects tampering, missing fields, and signature mismatch.

## Next: go on-chain

To give Alice's file a public, revocable on-chain record (so Bob does not need Alice to hand him the file every time), see [Registering a Resource](registering-a-resource.md).