npm package: @onchainsupply/identity
Description: Modular identity primitives for the Onchain Supply stack. The package ships a Solidity `IdentityRegistry` contract that assigns human-friendly names to onchain subjects (accounts, content digests, shortlinks, workspaces, or any category you define). It en
Latest version: 0.1.0

# @onchainsupply/identity

Modular identity primitives for the Onchain Supply stack. The package ships a Solidity `IdentityRegistry` contract that assigns human-friendly names to onchain subjects (accounts, content digests, shortlinks, workspaces, or any category you define). It enforces category-scoped uniqueness, supports registrar roles, and exposes update and transfer workflows so downstream apps (e.g. OnChainDrive) can keep identity metadata up to date.

## Features

- **Registry-first design** – categories (32-byte identifiers) isolate namespaces such as `content`, `account`, or bespoke verticals. Each subject (`bytes32`) maps to a `NameRecord`.
- **Configurable access** – grant `REGISTRAR_ROLE` to trusted contracts, or enable public registration per category when self-service naming makes sense.
- **Uniqueness guarantees** – case-insensitive hashing prevents duplicate labels inside a category.
- **Lifecycle management** – owners (or registrars) can rename, transfer ownership, or release names.
- **Integration helpers** – companion libraries (`IdentityConstants`, `IdentitySubjects`) simplify deriving category identifiers and subject keys from common data.

## Contracts

| Contract | Description |
| --- | --- |
| `IdentityRegistry.sol` | Core registry storing `NameRecord` structs keyed by category and subject. Emits lifecycle events for registration, updates, transfers, and releases. |
| `libraries/IdentityConstants.sol` | Predefined category identifiers for common use cases (accounts, content, workspaces, shortlinks). |
| `libraries/IdentitySubjects.sol` | Helper functions to convert addresses, multihash digests, or arbitrary bytes into 32-byte subjects. |
| `interfaces/IIdentityRegistry.sol` | Interface consumed by external integrations (e.g. OnChainDrive). |

## Usage

```solidity
import {IdentityRegistry} from "@onchainsupply/identity/contracts/IdentityRegistry.sol";
import {IdentityConstants} from "@onchainsupply/identity/contracts/libraries/IdentityConstants.sol";
import {IdentitySubjects} from "@onchainsupply/identity/contracts/libraries/IdentitySubjects.sol";

contract Example {
    IdentityRegistry public immutable identities;

    constructor(IdentityRegistry registry) {
        identities = registry;
    }

    function registerContent(bytes32 digest, string calldata name) external {
        identities.register(
            IdentityConstants.CATEGORY_CONTENT,
            IdentitySubjects.contentSubject(digest),
            name,
            msg.sender
        );
    }
}
```

### Categories

Pass any `bytes32` identifier to create a namespace. The constructor accepts an initial list and you can call `setCategoryConfig` later to toggle public registration or uniqueness enforcement per category.

```solidity
bytes32[] memory categories = new bytes32[](3);
categories[0] = IdentityConstants.CATEGORY_ACCOUNT;
categories[1] = IdentityConstants.CATEGORY_CONTENT;
categories[2] = IdentityConstants.CATEGORY_SHORTLINK;

IdentityRegistry registry = new IdentityRegistry(msg.sender, categories);
registry.setCategoryConfig(IdentityConstants.CATEGORY_ACCOUNT, true, true); // allow self-service account names
```

### Roles

- `DEFAULT_ADMIN_ROLE` – can configure categories and grant/revoke roles.
- `REGISTRAR_ROLE` – can register/rename/transfer on behalf of users.

Without a registrar role, users can only interact with categories that have `publicRegistration` enabled _and_ must be the name owner.

## Events

- `NameRegistered(bytes32 category, bytes32 subject, string name, address owner)`
- `NameUpdated(bytes32 category, bytes32 subject, string oldName, string newName, address owner)`
- `NameOwnerTransferred(bytes32 category, bytes32 subject, address newOwner)`
- `NameReleased(bytes32 category, bytes32 subject, string name)`
- `CategoryConfigured(bytes32 category, bool publicRegistration, bool enforceUniqueNames)`

## Scripts & Tests

Run the test suite (Solidity via Foundry-compatible harness + node-based viem tests):

```bash
pnpm install
pnpm test
```

Key test: `test/IdentityRegistry.ts` covers registrar gating, uniqueness enforcement, ownership transfers, updates, and release flows.

## Publishing

The package is ready to publish to npm as `@onchainsupply/identity`. A typical release pipeline:

```bash
pnpm build            # hardhat compile
npm publish --access public
```

`package.json` lists the contract sources as publishable files. Consumer projects can then add the dependency and import the contracts directly.