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

# Resource registry

# Resource Registry

The Notareum Resource Registry is the on-chain system for registering, identifying, and aliasing blockchain resources. It provides a deterministic resource ID scheme, six built-in resource types, and a human-readable alias system. The registry is implemented as the `NotareumNotaRegistry` contract and serves as the authoritative source of truth for resource identity and verification status.

## The role of the registry

The registry is a trust anchor. Once a resource is registered, any party can independently compute its canonical `resourceId` and look up its on-chain record. Verification status, attesting validators, and metadata are all queryable. Aliases provide ENS-like usability within the Notareum namespace, so users see `treasury.nota` instead of a raw hex string.

## Resource ID computation

Every resource is identified by a deterministic `bytes32` ID computed from three inputs:

```mermaid theme={"system"}
flowchart LR
    A[uint8 resourceType] --> D[abi.encodePacked]
    B[uint256 chainId] --> D
    C[bytes identifier] --> D
    D --> E[keccak256]
    E --> F[bytes32 resourceId]
```

```
resourceId = keccak256(abi.encodePacked(
    uint8(resourceType),
    uint256(chainId),
    bytes(identifier)
));
```

Identifiers MUST be encoded as UTF-8 bytes. The same computation runs in SDKs and on-chain. TypeScript reference:

```typescript theme={"system"}
import { keccak256, solidityPacked } from "ethers";

function computeResourceId(
  resourceType: number,
  chainId: bigint,
  identifier: string,
): string {
  return keccak256(
    solidityPacked(
      ["uint8", "uint256", "bytes"],
      [resourceType, chainId, Buffer.from(identifier, "utf8")],
    ),
  );
}
```

Two resources with the same identifier but different chain IDs produce different resource IDs and are treated as distinct.

## Well-known resource types

The registry ships with six built-in types, defined as `uint8 public constant` values in the contract.

| Constant           | Value | .nota type string |
| ------------------ | ----- | ----------------- |
| `TYPE_ADDRESS`     | 0     | `"address"`       |
| `TYPE_TRANSACTION` | 1     | `"transaction"`   |
| `TYPE_CONTRACT`    | 2     | `"contract"`      |
| `TYPE_IPFS`        | 3     | `"ipfs"`          |
| `TYPE_NFT`         | 4     | `"nft"`           |
| `TYPE_METADATA`    | 5     | `"metadata"`      |

Governance can add types through `addResourceType(uint8 typeId, string name)` (gated by `ROLE_PROTOCOL_ADMIN`). This lets the protocol support new asset categories like DIDs, domains, or real-world assets without redeploying contracts.

## Registration

```solidity theme={"system"}
function register(
    uint8 resourceType,
    uint256 chainId,
    bytes calldata identifier,
    bytes32 proofHash,
    string calldata alias_
) external returns (bytes32 resourceId);
```

Registration rules:

* `identifier` MUST NOT be empty.
* Each `(resourceType, chainId, identifier)` triple MUST be unique; duplicates revert with `ResourceAlreadyExists`.
* The caller becomes the `owner` of the resource.
* `proofHash` is a `bytes32` commitment that MAY be `bytes32(0)` at registration.
* If `alias_` is non-empty, alias registration runs atomically.
* New resources start at `verificationStatus = UNVERIFIED`, `verificationLevel = BASIC`.

TypeScript SDK call:

```typescript theme={"system"}
await ntm.registry.registerResource(
  0,                                 // resourceType: ADDRESS
  1n,                                // chainId
  "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "0x" + "00".repeat(32),            // proofHash
  "alice.nota",
);
```

## Verification status

Resources transition through five states:

| Status       | Value | Description                                     |
| ------------ | ----- | ----------------------------------------------- |
| `UNVERIFIED` | 0     | Registered but not verified                     |
| `PENDING`    | 1     | Verification request submitted; awaiting quorum |
| `VERIFIED`   | 2     | Consensus reached                               |
| `DISPUTED`   | 3     | Under governance review                         |
| `REVOKED`    | 4     | Revoked by owner or governance                  |

Only the `NotareumVerificationEngine` may change status as part of the verification workflow (via `ROLE_OPERATOR`). Owners may directly revoke their own resources.

## Verification levels

| Level           | Value | Description         |
| --------------- | ----- | ------------------- |
| `BASIC`         | 0     | 3-validator quorum  |
| `ENHANCED`      | 1     | 7-validator quorum  |
| `INSTITUTIONAL` | 2     | 15-validator quorum |

See [Verification Engine](verification-engine.md) for complete quorum rules.

## Alias system

Aliases are human-readable strings mapped to resource IDs. Rules:

* Globally unique across all resources.
* Each resource may have at most one alias.
* Registration costs `aliasFee` NOTA, transferred to the fee collector.
* Permanent: cannot be transferred or deleted.
* Convention is `<name>.nota`, but no suffix is enforced.

```typescript theme={"system"}
const resourceId = await ntm.registry.resolveAlias("alice.nota");
const info = await ntm.registry.getResource(resourceId);
console.log(info.identifier, info.owner, info.verificationStatus);
```

## NotaResource struct

```solidity theme={"system"}
struct NotaResource {
    uint8 resourceType;
    uint256 chainId;
    bytes identifier;
    bytes32 proofHash;
    address owner;
    VerificationStatus verificationStatus;
    VerificationLevel verificationLevel;
    string alias_;
    uint256 registeredAt;
    uint256 updatedAt;
}
```

`registeredAt` is set once at registration. `updatedAt` advances on status changes and proof hash updates.

## Lifecycle summary

```mermaid theme={"system"}
stateDiagram-v2
    [*] --> UNVERIFIED: register()
    UNVERIFIED --> PENDING: requestVerification()
    PENDING --> VERIFIED: quorum approved
    PENDING --> UNVERIFIED: quorum rejected
    VERIFIED --> DISPUTED: reportValidator()
    DISPUTED --> VERIFIED: innocent verdict
    DISPUTED --> REVOKED: guilty verdict
    UNVERIFIED --> REVOKED: revokeResource()
    VERIFIED --> REVOKED: revokeResource()
```

## Security considerations

**Identifier uniqueness.** Two resources with the same identifier but different chain IDs are distinct. Callers MUST supply the correct chain ID.

**Alias squatting.** Aliases are first-come, first-served. The protocol does not adjudicate trademark disputes. UIs MUST NOT present an alias as authoritative identity without also checking verification status.

**Ownership transfer.** Resource ownership is not transferable in v1.0. The `owner` field is permanent. This prevents hostile takeover of verified resources.

## Related pages

* [.nota File Format](nota-file-format.md)
* [Verification Engine](verification-engine.md)
* [NotaRegistry contract](../smart-contracts/nota-registry.md)
* [Registering a Resource guide](../guides/registering-a-resource.md)