Skip to content

docs: add did:near spec #2617

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 11, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
169 changes: 169 additions & 0 deletions docs/primitives/didnear
Original file line number Diff line number Diff line change
@@ -0,0 +1,169 @@
# NEAR Decentralized Identifiers (DIDs)

This document details how to use the `did:near` method for decentralized identifiers on the NEAR blockchain, how it complies with [W3C DID Core](https://www.w3.org/TR/did-core/), and how it integrates with verifiable credentials (VCs), proof registries, and resolution tooling.

---

## What is a DID?

A **Decentralized Identifier (DID)** is a persistent, unique identifier that does not require a centralized registry. On NEAR, DIDs are created based on either account names or raw public keys, and they are fully compatible with the W3C DID standard.

---

## The `did:near` Method

This method supports two types of DIDs:

| Type | Example | Description |
|--------------------|----------------------------------------|--------------------------------------|
| Named Account | `did:near:alice.testnet` | Derived from an on-chain NEAR account |
| Base58 Public Key | `did:near:7YzVXb8vKw3...` | Directly represents an Ed25519 key |

---

## DID Document Format

Example output from resolving a `did:near`:

```json
{
"@context": "https://w3id.org/did/v1",
"id": "did:near:alice.testnet",
"verificationMethod": [
{
"id": "did:near:alice.testnet#owner",
"type": "Ed25519VerificationKey2018",
"controller": "did:near:alice.testnet",
"publicKeyBase58": "3gfD2z7q..."
}
],
"authentication": ["did:near:alice.testnet#owner"],
"assertionMethod": ["did:near:alice.testnet#owner"]
}
```

This structure follows the [W3C DID Core Spec](https://www.w3.org/TR/did-core/), including:

- A DID identifier (`id`)
- Key references (`verificationMethod`)
- Authentication and assertion capabilities
- Base58-encoded Ed25519 public keys

---

## ⚙️ Repositories

| Component | Repository URL |
|----------------|----------------|
| DID Registry (contract) | https://github.com/DTI-web3/did-near |
| ProofType Contract | https://github.com/DTI-web3/did-near-prooftype |
| ProofType SDK | https://www.npmjs.com/package/@kaytrust/prooftypes |
| DID Resolver SDK | https://github.com/DTI-web3/did-near-resolver |

---

## How Resolution Works

1. Extract `identifier` from the DID.
2. If `identifier` is a NEAR account ID, resolve via RPC `account.state()`.
3. If it's a base58 public key, resolve via the registry smart contract using `identity_owner`.
4. Construct the DID document with the correct public key.

---

## How to Use

### Create a DID

If using a NEAR wallet account:
```ts
const did = "did:near:yourname.testnet";
```

If using a raw Ed25519 key (base58 encoded):
```ts
const did = "did:near:7YzVXb8vKw3...";
```

---

## Issuing and Verifying Credentials

### Step 1 – Hash the Credential

```ts
const cid = SHA256(JSON.stringify(credential)).toString(CryptoJS.enc.Base64);
```

### Step 2 – Issue on NEAR

```ts
await proofType.generateProof(credential, {
wallet,
cid
});
```

This records the hash (`cid`) on-chain with the `subject_did`.

### Step 3 – Verify On-chain

```ts
const isValid = await proofType.verifyProof("did:near:subject|bafy..."); // returns true or false
```

---

## SDK Usage

### Resolver SDK

```ts
import { NearDidResolver } from '@your-org/did-near-resolver';

const resolver = new NearDidResolver();
const doc = await resolver.resolveDID("did:near:alice.testnet");
console.log(doc.id); // "did:near:alice.testnet"
```

### ProofType SDK

```ts
import { ProofTypeNear } from '@kaytrust/prooftypes';

const proofType = new ProofTypeNear();
const proof = await proofType.generateProof(vcPayload, { wallet, cid });
const isValid = await proofType.verifyProof(proof);
```

---

## Security & Compliance

- Each `(did, cid)` pair can only be registered once.
- Issuer is linked to the signer account via NEAR transaction.
- DID resolution and structure is fully W3C-compliant.
- `cid` is always a Base64-encoded SHA-256 hash of the VC content.
- Public keys are handled securely via NEAR native accounts or custom registries.

---

## Testnet Deployment

- Registry Contract: `neardidregistry.testnet`
- ProofType Contract: `neardtiprooftype.testnet`
- Network: `testnet`
- Language: Rust (`near-sdk`)

---

## Conclusion

The `did:near` method enables full-stack decentralized identity flows on NEAR, including:

- Account- and key-based identifiers
- W3C-compliant DID documents
- Smart contract-backed credential proofs
- SDKs for resolution and attestation

Use this stack to build portable, verifiable, and secure Web3 identity solutions on NEAR.
Loading