@beclab/olaresid 0.1.1 → 0.1.3

package/TAG.md

@@ -0,0 +1,589 @@
+# Tag System Documentation
+
+The Tag system is a powerful key-value storage mechanism for Olares domains. Each domain can have multiple tags with defined types, allowing structured metadata storage on the blockchain.
+
+## Table of Contents
+
+-   [Overview](#overview)
+-   [Core Concepts](#core-concepts)
+-   [Supported Tag Types](#supported-tag-types)
+-   [SDK Usage](#sdk-usage)
+-   [CLI Usage](#cli-usage)
+-   [Permission Management](#permission-management)
+-   [Best Practices](#best-practices)
+-   [Examples](#examples)
+
+---
+
+## Overview
+
+Tags are key-value pairs associated with a domain. Each tag has:
+
+-   **Name**: A unique identifier (string)
+-   **Type**: Defined using ABI types (e.g., `string`, `uint8`, `address[]`)
+-   **Value**: The actual data, encoded according to the type
+-   **Tagger**: An authorized address that can set/modify the tag value
+
+---
+
+## Core Concepts
+
+### 1. Tag Definition
+
+Before you can use a tag, you must **define** its type:
+
+```typescript
+import { TagTypeBuilder } from '@beclab/olaresid';
+
+// Define a simple string tag
+const emailType = TagTypeBuilder.string();
+await tagCtx.defineTag('email', emailType);
+
+// Define a uint8 tag
+const ageType = TagTypeBuilder.uint(8);
+await tagCtx.defineTag('age', ageType);
+
+// Define an array tag
+const linksType = TagTypeBuilder.array(TagTypeBuilder.string());
+await tagCtx.defineTag('socialLinks', linksType);
+```
+
+### 2. Tagger Authorization
+
+Each tag has a **tagger** - an Ethereum address authorized to set its value:
+
+```typescript
+// Set yourself as the tagger
+const signerAddress = await signer.getAddress();
+await domainCtx.setTagger('email', signerAddress);
+```
+
+**Important:** You must set a tagger before you can set a tag's value. Only the tagger can modify the tag.
+
+### 3. Tag Value Operations
+
+Once defined and authorized, you can:
+
+-   **Set** a tag value
+-   **Get** a tag value (anyone can read)
+-   **Remove** a tag value (keeps the definition)
+
+```typescript
+// Set value
+await tagCtx.setTag('example.com', 'email', 'user@example.com');
+
+// Get value
+const email = await tagCtx.getTag('example.com', 'email');
+
+// Remove value (definition remains)
+await tagCtx.removeTag('example.com', 'email');
+```
+
+---
+
+## Supported Tag Types
+
+### Simple Types
+
+| Type                | Description       | Example           |
+| ------------------- | ----------------- | ----------------- |
+| `string`            | UTF-8 text        | `"Hello World"`   |
+| `uint8` - `uint256` | Unsigned integers | `42`, `255`       |
+| `int8` - `int256`   | Signed integers   | `-10`, `100`      |
+| `bool`              | Boolean           | `true`, `false`   |
+| `address`           | Ethereum address  | `"0x1234..."`     |
+| `bytes`             | Dynamic bytes     | `"0xabcd..."`     |
+| `bytes32`           | Fixed 32 bytes    | `"0x1234...abcd"` |
+
+### Array Types
+
+Any simple type can be made into a dynamic array:
+
+```typescript
+// String array
+TagTypeBuilder.array(TagTypeBuilder.string());
+
+// Address array
+TagTypeBuilder.array(TagTypeBuilder.address());
+
+// Uint8 array
+TagTypeBuilder.array(TagTypeBuilder.uint(8));
+```
+
+### Complex Tuple Types
+
+For structured data, use tuples:
+
+```typescript
+const userInfoType = TagTypeBuilder.tuple([
+    ['name', TagTypeBuilder.string()],
+    ['age', TagTypeBuilder.uint(8)],
+    ['wallets', TagTypeBuilder.array(TagTypeBuilder.address())],
+    ['verified', TagTypeBuilder.bool()]
+]);
+
+await tagCtx.defineTag('userInfo', userInfoType);
+
+// Set tuple value (automatic conversion!)
+await tagCtx.setTag('example.com', 'userInfo', {
+    name: 'Alice',
+    age: 30,
+    wallets: ['0x1111...', '0x2222...'],
+    verified: true
+});
+```
+
+#### Nested Tuples
+
+```typescript
+// Define nested tuple
+const profileType = TagTypeBuilder.tuple({
+    name: TagTypeBuilder.string(),
+    details: TagTypeBuilder.tuple({
+        age: TagTypeBuilder.uint8(),
+        verified: TagTypeBuilder.bool()
+    }),
+    contact: TagTypeBuilder.tuple({
+        email: TagTypeBuilder.string(),
+        phone: TagTypeBuilder.string()
+    })
+});
+
+await tagCtx.defineTag('profile', profileType);
+
+// Set nested tuple (automatic conversion!)
+await tagCtx.setTag('example.com', 'profile', {
+    name: 'Alice',
+    details: {
+        age: 30,
+        verified: true
+    },
+    contact: {
+        email: 'alice@example.com',
+        phone: '+1-555-0123'
+    }
+});
+```
+
+---
+
+## SDK Usage
+
+### Installation
+
+```bash
+npm install @beclab/olaresid
+```
+
+### Basic Setup
+
+```typescript
+import OlaresID, { TagTypeBuilder } from '@beclab/olaresid';
+
+// Initialize
+const olaresId = OlaresID.createTestnet(); // or createMainnet()
+await olaresId.setSigner(privateKeyOrMnemonic);
+
+// Get domain and tag contexts
+const domain = olaresId.domain('example.com');
+const tagCtx = domain.tag();
+```
+
+### Complete Workflow
+
+```typescript
+// 1. Define tag type
+const bioType = TagTypeBuilder.string();
+await tagCtx.defineTag('bio', bioType);
+
+// 2. Set tagger (authorize yourself)
+const signerAddress = await olaresId.signer.getAddress();
+await domain.setTagger('bio', signerAddress);
+
+// 3. Set tag value
+await tagCtx.setTag('example.com', 'bio', 'Web3 developer');
+
+// 4. Read tag value (anyone can read)
+const bio = await tagCtx.getTag('example.com', 'bio');
+console.log(bio); // "Web3 developer"
+
+// 5. List all tags
+const allTags = await domain.getAllTags();
+console.log(allTags); // [{ name: 'bio', value: 'Web3 developer' }, ...]
+
+// 6. List defined tag types
+const definedTags = await domain.getDefinedTags();
+console.log(definedTags); // ['bio', 'email', 'age', ...]
+```
+
+### High-Level API (Simplified)
+
+For common operations, use the high-level API:
+
+```typescript
+const domain = olaresId.domain('example.com');
+
+// Define and set in one step (using simplified API)
+await domain.defineSimpleTag('email', 'string');
+await domain.setTag('email', 'user@example.com');
+
+// Get value
+const email = await domain.getTag('email');
+
+// Remove value
+await domain.removeTag('email');
+```
+
+### Array Operations
+
+```typescript
+// Define array type
+const linksType = TagTypeBuilder.array(TagTypeBuilder.string());
+await tagCtx.defineTag('socialLinks', linksType);
+await domain.setTagger('socialLinks', signerAddress);
+
+// Set array value
+await tagCtx.setTag('example.com', 'socialLinks', [
+    'https://twitter.com/user',
+    'https://github.com/user'
+]);
+
+// Get array value
+const links = await tagCtx.getTag('example.com', 'socialLinks');
+console.log(links); // ['https://twitter.com/user', 'https://github.com/user']
+```
+
+### Error Handling
+
+```typescript
+try {
+    await tagCtx.defineTag('email', emailType);
+} catch (error) {
+    if (error.message.includes('already been defined')) {
+        console.log('Tag already exists, skipping definition');
+    } else {
+        throw error;
+    }
+}
+```
+
+---
+
+## CLI Usage
+
+The CLI provides simple commands for basic tag operations. For advanced usage (complex types, tuple operations), use the SDK.
+
+### Define Tag Type
+
+```bash
+# Simple types
+npx ts-node src/cli.ts tag define example.com email string
+npx ts-node src/cli.ts tag define example.com age uint8
+npx ts-node src/cli.ts tag define example.com verified bool
+
+# Array types (must be quoted!)
+npx ts-node src/cli.ts tag define example.com wallets "address[]"
+npx ts-node src/cli.ts tag define example.com links "string[]"
+```
+
+### Set Tagger
+
+```bash
+# Set tagger address
+npx ts-node src/cli.ts tag set-tagger example.com email 0xYOUR_ADDRESS
+```
+
+### Set Tag Value
+
+```bash
+# String value
+npx ts-node src/cli.ts tag set example.com email "user@example.com"
+
+# Number value
+npx ts-node src/cli.ts tag set example.com age 30
+
+# Boolean value
+npx ts-node src/cli.ts tag set example.com verified true
+
+# Array value (use JSON, must be quoted!)
+npx ts-node src/cli.ts tag set example.com links '["https://twitter.com","https://github.com"]'
+```
+
+### Get Tag Value
+
+```bash
+# Read-only, no authentication required
+npx ts-node src/cli.ts tag get example.com email
+```
+
+### List Tags
+
+```bash
+# List all tags with values
+npx ts-node src/cli.ts tag list example.com
+
+# List all defined tag types
+npx ts-node src/cli.ts tag list-defined example.com
+```
+
+### Remove Tag Value
+
+```bash
+# Remove value (definition remains)
+npx ts-node src/cli.ts tag remove example.com email
+```
+
+### Environment Variables
+
+Write operations require authentication:
+
+```bash
+export PRIVATE_KEY_OR_MNEMONIC="0xYOUR_PRIVATE_KEY"
+# OR
+export PRIVATE_KEY_OR_MNEMONIC="your twelve word mnemonic phrase here"
+```
+
+---
+
+## Permission Management
+
+### Tagger Role
+
+The **tagger** is the only address authorized to set/modify a tag's value. The domain owner can set or change the tagger at any time.
+
+```typescript
+// Set tagger (only domain owner can do this)
+await domain.setTagger('email', '0xTAGGER_ADDRESS');
+
+// Get current tagger
+const tagger = await tagCtx.getTagger('email');
+console.log(tagger); // "0xTAGGER_ADDRESS"
+```
+
+### Authorization Flow
+
+1. **Domain Owner** defines tag type → calls `defineTag()`
+2. **Domain Owner** sets tagger → calls `setTagger(tagName, taggerAddress)`
+3. **Tagger** can now set/modify values → calls `setTag()`, `removeTag()`
+4. **Anyone** can read values → calls `getTag()`
+
+### Common Patterns
+
+**Pattern 1: Owner manages their own tags**
+
+```typescript
+const ownerAddress = await signer.getAddress();
+await domain.setTagger('bio', ownerAddress);
+await tagCtx.setTag('example.com', 'bio', 'My biography');
+```
+
+**Pattern 2: Delegate to a contract**
+
+Delegating tagger permissions to a smart contract allows for more complex logic and automation:
+
+```typescript
+const CONTRACT_ADDRESS = '0x1234...'; // Your smart contract address
+await domain.setTagger('reputation', CONTRACT_ADDRESS);
+// Now the contract can update the reputation tag with custom logic
+```
+
+**Benefits of using contracts as taggers:**
+
+-   Implement complex authorization logic (multi-sig, time-locks, etc.)
+-   Enable automated tag updates based on on-chain events
+-   Create composable tag management systems
+-   Enforce business rules programmatically
+
+**Reference Implementations:**
+
+For real-world examples, see the [did-contracts/src/taggers](../../did-contracts/src/taggers/) directory, which contains production tagger contracts currently in use.
+
+---
+
+## Best Practices
+
+### 1. Handle RedefinedTag Errors
+
+Tags can only be defined once. Always check if a tag exists:
+
+```typescript
+try {
+    await tagCtx.defineTag('email', emailType);
+} catch (error) {
+    if (error.message.includes('already been defined')) {
+        console.log('Tag already exists, skipping');
+    } else {
+        throw error;
+    }
+}
+```
+
+### 2. Always Set Tagger After Defining
+
+```typescript
+// ✅ Good
+await tagCtx.defineTag('email', emailType);
+await domain.setTagger('email', signerAddress);
+await tagCtx.setTag('example.com', 'email', 'user@example.com');
+
+// ❌ Bad - will fail with "Unauthorized"
+await tagCtx.defineTag('email', emailType);
+await tagCtx.setTag('example.com', 'email', 'user@example.com'); // No tagger set!
+```
+
+### 3. Wait for Blockchain Indexing
+
+After write operations, allow time for nodes to index:
+
+```typescript
+await tagCtx.setTag('example.com', 'email', 'user@example.com');
+await new Promise(resolve => setTimeout(resolve, 3000)); // Wait 3 seconds
+const email = await tagCtx.getTag('example.com', 'email');
+```
+
+### 4. Validate Input Types
+
+The blockchain will reject invalid types:
+
+```typescript
+// ❌ Wrong type
+await tagCtx.setTag('example.com', 'age', 'thirty'); // Expected number
+
+// ✅ Correct type
+await tagCtx.setTag('example.com', 'age', 30);
+```
+
+---
+
+## Examples
+
+### Example 1: User Profile
+
+```typescript
+// Define tags
+await tagCtx.defineTag('bio', TagTypeBuilder.string());
+await tagCtx.defineTag('followers', TagTypeBuilder.uint(256));
+await tagCtx.defineTag('verified', TagTypeBuilder.bool());
+await tagCtx.defineTag(
+    'socialLinks',
+    TagTypeBuilder.array(TagTypeBuilder.string())
+);
+
+// Set tagger
+const signer = await olaresId.signer.getAddress();
+await domain.setTagger('bio', signer);
+await domain.setTagger('followers', signer);
+await domain.setTagger('verified', signer);
+await domain.setTagger('socialLinks', signer);
+
+// Set values
+await tagCtx.setTag('alice.com', 'bio', 'Web3 enthusiast');
+await tagCtx.setTag('alice.com', 'followers', 1350);
+await tagCtx.setTag('alice.com', 'verified', true);
+await tagCtx.setTag('alice.com', 'socialLinks', [
+    'https://twitter.com/alice',
+    'https://github.com/alice'
+]);
+
+// Read all tags
+const tags = await domain.getAllTags();
+console.log(tags);
+```
+
+### Example 2: NFT Metadata
+
+```typescript
+// Define NFT metadata tags
+const nftType = TagTypeBuilder.tuple([
+    ['tokenId', TagTypeBuilder.uint(256)],
+    ['name', TagTypeBuilder.string()],
+    ['description', TagTypeBuilder.string()],
+    ['image', TagTypeBuilder.string()],
+    ['attributes', TagTypeBuilder.array(TagTypeBuilder.string())]
+]);
+
+await tagCtx.defineTag('nftMetadata', nftType);
+await domain.setTagger('nftMetadata', signerAddress);
+
+// Set NFT metadata
+await tagCtx.setTag('nft.com', 'nftMetadata', {
+    tokenId: 1,
+    name: 'Cool NFT #1',
+    description: 'A very cool NFT',
+    image: 'ipfs://QmXxx...',
+    attributes: ['rare', 'animated', 'special']
+});
+```
+
+### Example 3: Service Configuration
+
+```typescript
+// Define service config tags
+await tagCtx.defineTag('apiEndpoint', TagTypeBuilder.string());
+await tagCtx.defineTag(
+    'rpcNodes',
+    TagTypeBuilder.array(TagTypeBuilder.string())
+);
+await tagCtx.defineTag('maxRetries', TagTypeBuilder.uint(8));
+await tagCtx.defineTag('enabled', TagTypeBuilder.bool());
+
+// Delegate tagger to service admin
+const SERVICE_ADMIN = '0x1234...';
+await domain.setTagger('apiEndpoint', SERVICE_ADMIN);
+await domain.setTagger('rpcNodes', SERVICE_ADMIN);
+await domain.setTagger('maxRetries', SERVICE_ADMIN);
+await domain.setTagger('enabled', SERVICE_ADMIN);
+
+// Service admin sets config
+await tagCtx.setTag('service.com', 'apiEndpoint', 'https://api.example.com');
+await tagCtx.setTag('service.com', 'rpcNodes', [
+    'https://rpc1.example.com',
+    'https://rpc2.example.com'
+]);
+await tagCtx.setTag('service.com', 'maxRetries', 3);
+await tagCtx.setTag('service.com', 'enabled', true);
+```
+
+---
+
+## See Also
+
+-   **[SDK Examples](./examples/)** - Complete code examples
+-   **[CLI Documentation](./CLI.md#tag-management-commands)** - Full CLI reference
+-   **[Main README](./README.md)** - General documentation
+
+---
+
+## Troubleshooting
+
+### Error: "Tag already exists"
+
+**Solution:** Tag definitions are immutable. You cannot redefine a tag. Check if it exists first.
+
+### Error: "Unauthorized"
+
+**Solution:** You haven't set a tagger, or you're not the tagger. Call `setTagger()` first.
+
+### Error: "Invalid tag operation"
+
+**Solution:** You're trying to remove a tag that has no value, or performing an unsupported operation.
+
+### Error: "Tuple field count mismatch"
+
+**Solution:** Ensure object keys match the tuple field definition order and count. Objects are automatically converted to arrays based on the ABI type structure.
+
+### Shell Error: "no matches found: address[]"
+
+**Solution:** Quote array types in the shell: `"address[]"` instead of `address[]`.
+
+---
+
+## Contract Reference
+
+Tag operations interact with the following contracts:
+
+-   **TerminusDID**: Tag definition, tagger management
+-   **TagRegistry**: Core tag storage and operations
+-   **RootResolver**: Legacy tag operations (compatibility)
+
+For contract details, see the [did-contracts](../../did-contracts/) repository.

package/dist/abi/RootResolver2ABI.d.ts

@@ -0,0 +1,54 @@
+declare const _default: {
+    abi: ({
+        inputs: {
+            internalType: string;
+            name: string;
+            type: string;
+        }[];
+        name: string;
+        type: string;
+        outputs?: undefined;
+        stateMutability?: undefined;
+    } | {
+        inputs: ({
+            components: {
+                internalType: string;
+                name: string;
+                type: string;
+            }[];
+            internalType: string;
+            name: string;
+            type: string;
+        } | {
+            internalType: string;
+            name: string;
+            type: string;
+            components?: undefined;
+        })[];
+        name: string;
+        outputs: never[];
+        stateMutability: string;
+        type: string;
+    } | {
+        inputs: {
+            internalType: string;
+            name: string;
+            type: string;
+        }[];
+        name: string;
+        outputs: {
+            components: {
+                internalType: string;
+                name: string;
+                type: string;
+            }[];
+            internalType: string;
+            name: string;
+            type: string;
+        }[];
+        stateMutability: string;
+        type: string;
+    })[];
+};
+export default _default;
+//# sourceMappingURL=RootResolver2ABI.d.ts.map

package/dist/abi/RootResolver2ABI.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RootResolver2ABI.d.ts","sourceRoot":"","sources":["../../src/abi/RootResolver2ABI.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,wBA4OE"}