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

# Getting started

# Rust: Getting Started

`notareum` is the official Rust SDK for the Notareum Protocol, published on crates.io as a single crate. It targets Rust edition 2021 (stable toolchain) and builds on `ethers` v2 for Ethereum RPC and signing, `tokio` for the async runtime, and `serde` for typed serialization. This page adds the crate, wires up a provider and signer, and produces your first signed `.nota` file.

## Install

```bash theme={"system"}
cargo add notareum
cargo add tokio --features full
cargo add ethers --features legacy
```

`ethers` is a direct dependency of the SDK. Pinning it in your downstream crate keeps provider, signer, and middleware versions aligned with the SDK.

```toml theme={"system"}
[dependencies]
notareum = "0.1"
tokio    = { version = "1", features = ["full"] }
ethers   = { version = "2", features = ["legacy"] }
```

## Requirements

* Rust edition 2021, stable toolchain.
* A Tokio multi-threaded runtime for the async entry points.
* An Ethereum JSON-RPC endpoint.
* Optional: a `LocalWallet` (or any `ethers::signers::Signer`) for write operations. Omit the signer to operate in read-only mode.

## Create a Notareum instance

```rust theme={"system"}
use std::sync::Arc;

use notareum::{ClientConfig, ContractAddresses, Notareum};
use ethers::providers::{Http, Provider};
use ethers::signers::LocalWallet;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let rpc = std::env::var("RPC_URL")?;
    let key = std::env::var("PRIVATE_KEY")?;

    let provider = Arc::new(Provider::<Http>::try_from(rpc)?);
    let signer: LocalWallet = key.parse()?;

    let contracts = ContractAddresses {
        access_manager:      std::env::var("ACCESS_MANAGER")?,
        nota_token:          std::env::var("NOTA_TOKEN")?,
        ve_nota:             std::env::var("VE_NOTA")?,
        validator_staking:   std::env::var("VALIDATOR_STAKING")?,
        nota_registry:       std::env::var("NOTA_REGISTRY")?,
        verification_engine: std::env::var("VERIFICATION_ENGINE")?,
        slashing_manager:    std::env::var("SLASHING_MANAGER")?,
        fee_manager:         std::env::var("FEE_MANAGER")?,
    };

    let ntm = Notareum::new(ClientConfig {
        provider,
        signer: Some(signer),
        contracts,
    })?;
    // ...
    Ok(())
}
```

Deployed addresses live in [Contract Addresses](../../reference/contract-addresses.md).

## Read-only mode

Pass `signer: None` to operate without a wallet. Read methods work as usual; any write method returns \[`SdkError::SignerRequired`].

## Your first .nota file

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

let private_key_hex = std::env::var("PRIVATE_KEY")?;

let signed = ntm.nota.create(CreateNotaOptions {
    type_: "address".into(),
    chain_name: "ethereum".into(),
    chain_id: 1,
    network: None,
    identifier: "0xabc...".into(),
    name: Some("My wallet".into()),
    alias: Some("alice.eth".into()),
    description: None,
    resource_metadata: None,
    issuer_name: Some("Alice".into()),
    issuer_entity_type: Some("individual".into()),
})?
.validate()?
.sign(&private_key_hex)?;

let wire: String = signed.serialize()?;
println!("{wire}");
```

`.nota` file signing is fully local, produces byte-identical output to the TypeScript and Python SDKs, and never touches the network. The off-chain primitives backing this flow live under \[`notareum::core`].

> The `CreateNotaOptions` field is named `type_` (trailing underscore) because `type` is a reserved keyword in Rust. A convenience constructor `CreateNotaOptions::new(type_, chain_name, chain_id, identifier)` is available when you only need the required fields.

## Read a contract

Sub-clients are exposed as public fields on `Notareum`, not method calls.

```rust theme={"system"}
let info = ntm.registry
    .get_resource("0x1234...resourceIdHex...")
    .await?;
println!("{} level={}", info.owner, info.verification_level);
```

## Write a contract

```rust theme={"system"}
let tx_hash = ntm.registry
    .register_resource(
        0u8,                            // ResourceType::Address
        1u64,                           // chain_id
        "0xabc...",                     // identifier
        "0x0000000000000000000000000000000000000000000000000000000000000000",
        Some("alice.eth"),
    )
    .await?;
println!("Registered: {tx_hash}");
```

Write methods submit the transaction with the configured signer and return the transaction hash as a `String`. Use the underlying provider to wait for a receipt if your workflow requires it.

## Next steps

* [Working with .nota files](nota-files.md)
* [Registry client](registry.md)
* [Full API reference](api-reference.md)