@beclab/olaresid 0.1.13 → 0.2.1

package/README.md

@@ -2,7 +2,7 @@
 
 ## Introduction
 
-`olaresid` is an SDK library and CLI tool for interacting with Olares ID contracts.
+`olaresid` is an SDK library and CLI tool focused on Olares ID domain metadata and tags. It helps you read core metadata (such as domain, DID, owner, and subdomain settings), and manage typed tag data on-chain for structured profile, auth, and application-specific information.
 
 ## Quick Start
 
@@ -12,16 +12,17 @@
 npm install -g @beclab/olaresid
 
 # Query Olares ID information on mainnet (default)
-did-cli info example.olares.com
+did-cli fetch olares.com
 
 # Query Olares ID information on sepolia testnet
-did-cli info example.olares.com --network sepolia
+did-cli fetch olares.com --network sepolia
 
 # Support Olares ID Format
-did-cli info alice@example.com
+did-cli fetch tw7613781@olares.com
 ```
 
-For detailed CLI usage, see [CLI.md](./CLI.md).
+-   Scenario-based usage guide: [CLI.md](./CLI.md)
+-   Full command reference: [CLI-TREE.md](./CLI-TREE.md)
 
 ### As an SDK
 
@@ -29,11 +30,23 @@ For detailed CLI usage, see [CLI.md](./CLI.md).
 npm install @beclab/olaresid
 ```
 
-Refer to the [examples](./examples) directory.
+In your TypeScript or JavaScript code, import the package:
 
-For Tag System usage, see [TAG.md](./TAG.md).
+```typescript
+import OlaresID from '@beclab/olaresid';
+```
+
+-   Full SDK API reference: [SDK-TREE.md](./SDK-TREE.md)
+-   Usage examples: [examples](./examples) directory
+
+### Tag System
+
+Tag-related usage is documented separately:
+
+-   SDK and concepts: [TAG.md](./TAG.md)
+-   CLI command usage: [TAG.md#cli-usage](./TAG.md#cli-usage)
 
-#### Frontend Usage (Browser Environment)
+### Frontend Usage (Browser Environment)
 
 When using `@beclab/olaresid` in frontend applications (React, Vue, etc.), you need to configure polyfills and bundler settings due to:
 
@@ -85,8 +98,9 @@ npm run build
 # Run examples
 npx ts-node ./examples/index.ts
 
-# Or run other examples
-npx ts-node ./examples/legacy.ts
+# Or run domain fetching examples
+npx ts-node ./examples/fetch-domain-demo.ts
+npx ts-node ./examples/fetch-all-flat-demo.ts
 ```
 
 After testing, feel free to submit a Pull Request!
@@ -99,14 +113,18 @@ After testing, feel free to submit a Pull Request!
 
 -   **RPC:** https://optimism-rpc.publicnode.com
 -   **DID Contract:** 0x5DA4Fa8E567d86e52Ef8Da860de1be8f54cae97D
--   **Root Resolver:** 0x0223be5559961f9D393b28EFD1dBEdcB2dD67523
+-   **Root Resolver:** 0x9bA3D0D3d2046aeD57e9897F7F79C58DfAa5325A
 -   **Root Resolver2:** 0x7e7961aB771cA942CE4DB6e79579e016a33Dc95B
 -   **ABI Type:** 0x9ae3F16bD99294Af1784beB1a0A5C84bf2636365
+-   **Query Contract:** 0x8305411EEa5C3F99f9426845Cf2977E77D5a1711
+-   **Support Service:** https://api.olares.com/did/support
 
 #### Sepolia Testnet
 
 -   **RPC:** https://sepolia.optimism.io
 -   **DID Contract:** 0xe2D7c3a9013960E04d4E9F5F9B63fff37eEd97A8
--   **Root Resolver:** 0xcB045D9133A4F5ffCe2C98b2C47e951e8c9A0655
+-   **Root Resolver:** 0xbEE79099eD3eD33c8ce57df9fb79370aAc79f261
 -   **Root Resolver2:** 0xcbC02aa08c77a374eC0D5A0403E108b7573d96e8
 -   **ABI Type:** 0x7386fCBae6Ad4CCE1499d9153D99bc950B589718
+-   **Query Contract:** 0xAf0430AB9f2450c52E7401846C7CA702D53eCFC2
+-   **Support Service:** https://api-test.olares.com/did/support

package/SDK-TREE.md

@@ -0,0 +1,151 @@
+# OlaresID SDK Reference
+
+Package: `@beclab/olaresid`  
+Install: `npm install @beclab/olaresid`
+
+```
+@beclab/olaresid
+│
+├── OlaresID  [Entry factory]
+│   ├── createMainnet()                         connect to Optimism mainnet
+│   ├── createTestnet()                         connect to Sepolia testnet
+│   ├── createWithRpc(url, network?)            custom RPC, bundled contract addresses
+│   └── createConsole(rpc, did, resolver, abi, resolver2?, svcUrl?, query?)
+│                                               fully manual configuration
+│
+├── DIDConsole
+│   ├── Signer
+│   │   ├── setSigner(signerOrPrivateKeyOrMnemonic)  accepts Signer / hex key / mnemonic
+│   │   ├── getSigner()
+│   │   └── clearSigner()
+│   │
+│   ├── Query                                   [🌐 Public]
+│   │   ├── fetchDomain(nameOrTokenId)
+│   │   ├── fetchDomains(offset, limit)
+│   │   ├── fetchDomainsByIndices(indices[])
+│   │   └── fetchAllFlat({ batchSize?, onProgress? })
+│   │
+│   ├── Contract read-only                      [🌐 Public]
+│   │   ├── getOwner()
+│   │   ├── getTotalSupply()
+│   │   └── getOperator()
+│   │
+│   ├── Contract ownership                      [👑 Contract Owner]
+│   │   ├── transferOwnership(newOwner)         2-step: initiates transfer
+│   │   └── acceptOwnership()                   2-step: new owner confirms
+│   │
+│   ├── Operator management                     [👑 Contract Owner]
+│   │   └── setOperator(address)
+│   │
+│   └── domain(name)  →  DomainContext ↓
+│
+├── DomainContext
+│   ├── Info read-only                          [🌐 Public]
+│   │   ├── getMetaInfo()                       id / name / DID / note / allowSubdomain
+│   │   ├── getOwner()                          NFT owner address
+│   │   └── isOwner()                           checks connected signer
+│   │
+│   ├── RSA key read-only                       [🌐 Public]
+│   │   └── getRSAPublicKey()                   PEM PKCS#8, or null
+│   │
+│   ├── IP read-only                            [🌐 Public]
+│   │   └── getIP()                             IPv4 string, or null
+│   │
+│   ├── Wallet read-only                        [🌐 Public]
+│   │   ├── getEVMWallets()
+│   │   └── getSolanaWallets()
+│   │
+│   ├── RSA key write                           [🔑 Domain Owner]
+│   │   ├── setRSAPublicKey(pem)                accepts PEM or DER hex
+│   │   └── removeRSAPublicKey()
+│   │
+│   ├── IP write                                [🔑 Domain Owner]
+│   │   ├── setIP(ip)                           e.g. "192.168.1.1"
+│   │   └── removeIP()
+│   │
+│   ├── Wallet write                            [🔑 Domain Owner]
+│   │   ├── addEVMWallet(privateKey)            dual EIP-712 signature
+│   │   ├── removeEVMWallet(privateKey)
+│   │   ├── addSolanaWallet(privateKey)
+│   │   └── removeSolanaWallet(privateKey)
+│   │
+│   ├── Subdomain registration                  [🔑 Domain Owner]
+│   │   └── registerSubdomain(label, mnemonic)  derives owner + DID from mnemonic
+│   │
+│   ├── Domain transfer                         [🔑 Domain Owner]
+│   │   └── transfer(newOwnerMnemonic)          atomically updates NFT owner + DID
+│   │
+│   └── tag(fromDomain?)  →  TagContext ↓
+│       (fromDomain defaults to current domain)
+│
+├── TagContext
+│   ├── Read-only                               [🌐 Public]
+│   │   ├── getTag(toDomain, tagName)
+│   │   ├── getAllTags(toDomain)
+│   │   ├── getDefinedTagNames()                tag types defined by fromDomain
+│   │   └── getTagger(tagName)
+│   │
+│   ├── Tag type management                     [🔑 Domain Owner]
+│   │   ├── defineTag(tagName, TagTypeBuilder)
+│   │   └── setTagger(tagName, address)         authorize a tagger
+│   │
+│   └── Tag value write                         [✏️ Tagger]
+│       ├── setTag(toDomain, tagName, value)
+│       └── removeTag(toDomain, tagName)
+│
+└── Utilities  [🌐 No permission required — pure local computation]
+    ├── Crypto
+    │   ├── generateMnemonic(wordCount?)        BIP39, 12–24 words
+    │   ├── deriveDIDFromMnemonic(mnemonic)     → { owner, did }
+    │   ├── generateDIDKeyData()                generate mnemonic + derive keys
+    │   ├── getEVMPrivateKeyFromMnemonic(mnemonic)
+    │   ├── getEthereumAddressFromMnemonic(mnemonic)
+    │   └── createRsaKeyPair(bits?)             → { rsaPublicKey, rsaPrivateKey } PEM
+    │
+    ├── Format
+    │   ├── pemToDer(pem)                       PEM → DER hex
+    │   ├── derToPem(hex)                       DER hex → PEM
+    │   ├── ipv4ToBytes4(ip)                    "1.2.3.4" → bytes4 hex
+    │   ├── bytes4ToIpv4(hex)                   bytes4 hex → "1.2.3.4"
+    │   ├── normalizeToDomain(input)            alice@olares.com → alice.olares.com
+    │   └── normalizeToOlaresId(domain)         alice.olares.com → alice@olares.com
+    │
+    ├── Tag
+    │   ├── TagTypeBuilder                      build ABI-encoded type descriptors
+    │   │   ├── TagTypeBuilder.string()
+    │   │   ├── TagTypeBuilder.uint8() / uint256() / int8() / int256()
+    │   │   ├── TagTypeBuilder.bool()
+    │   │   ├── TagTypeBuilder.address()
+    │   │   ├── TagTypeBuilder.bytes() / bytes32()
+    │   │   └── TagTypeBuilder.array(innerType)
+    │   └── TagTypeParser                       decode raw ABI type bytes
+    │
+    └── Events
+        ├── parseEvents(rawLogs)                parse eth_getLogs into typed events
+        └── type guards
+            ├── isTransferEvent(e)
+            ├── isMintEvent(e)                  Transfer from zero address
+            ├── isTagAddedEvent(e)
+            ├── isTagRemovedEvent(e)
+            ├── isTagElemUpdatedEvent(e)
+            ├── isTagElemPushedEvent(e)
+            ├── isTagElemPoppedEvent(e)
+            └── isNewTagTypeEvent(e)
+```
+
+---
+
+```
+Permission legend
+  🌐 Public        no signing required — read-only on-chain data or local computation
+  ✏️ Tagger        address authorized by Domain Owner via setTagger()
+  🔑 Domain Owner  holder of the domain NFT
+  👑 Contract Owner  Ownable2Step super-admin
+
+⚠️  Operator role: exists at the contract level for registering root domains;
+    not exposed as a method in the SDK.
+```
+
+---
+
+For tag type definitions and examples, see [TAG.md](./TAG.md).

package/TAG.md

@@ -28,6 +28,22 @@ Tags are key-value pairs associated with a domain. Each tag has:
 
 ## Core Concepts
 
+### 0. Get `tagCtx` First
+
+Before using any tag APIs in this document, initialize OlaresID, get a domain context, and then get the tag context:
+
+```typescript
+import OlaresID from '@beclab/olaresid';
+
+const olaresId = OlaresID.createMainnet(); // or createTestnet()
+await olaresId.setSigner(privateKeyOrMnemonic);
+
+const domainCtx = olaresId.domain('example.com');
+const tagCtx = domainCtx.tag();
+```
+
+`tagCtx` is used for tag operations like `defineTag`, `setTag`, `getTag`, and `removeTag`.
+
 ### 1. Tag Definition
 
 Before you can use a tag, you must **define** its type:
@@ -54,7 +70,7 @@ Each tag has a **tagger** - an Ethereum address authorized to set its value:
 
 ```typescript
 // Set yourself as the tagger
-const signerAddress = await signer.getAddress();
+const signerAddress = await olaresId.signer.getAddress();
 await domainCtx.setTagger('email', signerAddress);
 ```
 
@@ -185,8 +201,8 @@ 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();
+const domainCtx = olaresId.domain('example.com');
+const tagCtx = domainCtx.tag();
 ```
 
 ### Complete Workflow
@@ -198,7 +214,7 @@ await tagCtx.defineTag('bio', bioType);
 
 // 2. Set tagger (authorize yourself)
 const signerAddress = await olaresId.signer.getAddress();
-await domain.setTagger('bio', signerAddress);
+await domainCtx.setTagger('bio', signerAddress);
 
 // 3. Set tag value
 await tagCtx.setTag('example.com', 'bio', 'Web3 developer');
@@ -208,11 +224,11 @@ const bio = await tagCtx.getTag('example.com', 'bio');
 console.log(bio); // "Web3 developer"
 
 // 5. List all tags
-const allTags = await domain.getAllTags();
+const allTags = await domainCtx.getAllTags();
 console.log(allTags); // [{ name: 'bio', value: 'Web3 developer' }, ...]
 
 // 6. List defined tag types
-const definedTags = await domain.getDefinedTags();
+const definedTags = await domainCtx.getDefinedTags();
 console.log(definedTags); // ['bio', 'email', 'age', ...]
 ```
 
@@ -221,17 +237,17 @@ console.log(definedTags); // ['bio', 'email', 'age', ...]
 For common operations, use the high-level API:
 
 ```typescript
-const domain = olaresId.domain('example.com');
+const domainCtx = 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');
+await domainCtx.defineSimpleTag('email', 'string');
+await domainCtx.setTag('email', 'user@example.com');
 
 // Get value
-const email = await domain.getTag('email');
+const email = await domainCtx.getTag('email');
 
 // Remove value
-await domain.removeTag('email');
+await domainCtx.removeTag('email');
 ```
 
 ### Array Operations
@@ -240,7 +256,7 @@ await domain.removeTag('email');
 // Define array type
 const linksType = TagTypeBuilder.array(TagTypeBuilder.string());
 await tagCtx.defineTag('socialLinks', linksType);
-await domain.setTagger('socialLinks', signerAddress);
+await domainCtx.setTagger('socialLinks', signerAddress);
 
 // Set array value
 await tagCtx.setTag('example.com', 'socialLinks', [
@@ -277,60 +293,92 @@ The CLI provides simple commands for basic tag operations. For advanced usage (c
 
 ```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
+did-cli tag define example.com email string
+did-cli tag define example.com age uint8
+did-cli 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[]"
+did-cli tag define example.com wallets "address[]"
+did-cli 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
+did-cli tag set-tagger example.com email 0xYOUR_ADDRESS
 ```
 
 ### Set Tag Value
 
+`tag set` supports separating tag definition domain (`from`) and target object domain (`to`):
+
+-   `to`: the first `<domain>` argument
+-   `from`: optional `--from <domain|root>` (defaults to `to` if omitted)
+
 ```bash
 # String value
-npx ts-node src/cli.ts tag set example.com email "user@example.com"
+did-cli tag set example.com email "user@example.com"
 
 # Number value
-npx ts-node src/cli.ts tag set example.com age 30
+did-cli tag set example.com age 30
 
 # Boolean value
-npx ts-node src/cli.ts tag set example.com verified true
+did-cli 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"]'
+did-cli tag set example.com links '["https://twitter.com","https://github.com"]'
+
+# Cross-domain: tag defined on parent.com, value written to child.parent.com
+did-cli tag set child.parent.com profile "builder" --from parent.com
+
+# Root-defined tag
+did-cli tag set child.parent.com latestDID "did:key:..." --from root
 ```
 
 ### Get Tag Value
 
+`tag get` uses the same `to` + optional `--from` rule as `tag set`.
+
 ```bash
 # Read-only, no authentication required
-npx ts-node src/cli.ts tag get example.com email
+did-cli tag get example.com email
+
+# Cross-domain read
+did-cli tag get child.parent.com profile --from parent.com
+
+# Root-defined tag read
+did-cli tag get child.parent.com latestDID --from root
 ```
 
 ### List Tags
 
+`tag list` uses the same `to` + optional `--from` rule as `tag set`/`tag get`.
+
 ```bash
 # List all tags with values
-npx ts-node src/cli.ts tag list example.com
+did-cli tag list example.com
+
+# Cross-domain list (tag definitions on parent.com)
+did-cli tag list child.parent.com --from parent.com
+
+# Root-defined tag list
+did-cli tag list child.parent.com --from root
 
 # List all defined tag types
-npx ts-node src/cli.ts tag list-defined example.com
+did-cli tag list-defined example.com
 ```
 
 ### Remove Tag Value
 
+`tag remove` also supports optional `--from <domain|root>` for cross-domain tag definitions.
+
 ```bash
 # Remove value (definition remains)
-npx ts-node src/cli.ts tag remove example.com email
+did-cli tag remove example.com email
+
+# Cross-domain remove
+did-cli tag remove child.parent.com profile --from parent.com
 ```
 
 ### Environment Variables
@@ -343,6 +391,12 @@ export PRIVATE_KEY_OR_MNEMONIC="0xYOUR_PRIVATE_KEY"
 export PRIVATE_KEY_OR_MNEMONIC="your twelve word mnemonic phrase here"
 ```
 
+### Root and Cross-Domain Notes
+
+-   If `--from` is omitted, CLI uses `from = to` (backward compatible behavior).
+-   Use `--from root` when tag type is defined on root domain (`""`).
+-   `tag define` and `tag set-tagger` are still executed on their explicit `<domain>` argument.
+
 ---
 
 ## Permission Management
@@ -353,7 +407,7 @@ The **tagger** is the only address authorized to set/modify a tag's value. The d
 
 ```typescript
 // Set tagger (only domain owner can do this)
-await domain.setTagger('email', '0xTAGGER_ADDRESS');
+await domainCtx.setTagger('email', '0xTAGGER_ADDRESS');
 
 // Get current tagger
 const tagger = await tagCtx.getTagger('email');
@@ -372,8 +426,8 @@ console.log(tagger); // "0xTAGGER_ADDRESS"
 **Pattern 1: Owner manages their own tags**
 
 ```typescript
-const ownerAddress = await signer.getAddress();
-await domain.setTagger('bio', ownerAddress);
+const ownerAddress = await olaresId.signer.getAddress();
+await domainCtx.setTagger('bio', ownerAddress);
 await tagCtx.setTag('example.com', 'bio', 'My biography');
 ```
 
@@ -383,7 +437,7 @@ Delegating tagger permissions to a smart contract allows for more complex logic
 
 ```typescript
 const CONTRACT_ADDRESS = '0x1234...'; // Your smart contract address
-await domain.setTagger('reputation', CONTRACT_ADDRESS);
+await domainCtx.setTagger('reputation', CONTRACT_ADDRESS);
 // Now the contract can update the reputation tag with custom logic
 ```
 
@@ -423,7 +477,7 @@ try {
 ```typescript
 // ✅ Good
 await tagCtx.defineTag('email', emailType);
-await domain.setTagger('email', signerAddress);
+await domainCtx.setTagger('email', signerAddress);
 await tagCtx.setTag('example.com', 'email', 'user@example.com');
 
 // ❌ Bad - will fail with "Unauthorized"
@@ -471,10 +525,10 @@ await tagCtx.defineTag(
 
 // 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);
+await domainCtx.setTagger('bio', signer);
+await domainCtx.setTagger('followers', signer);
+await domainCtx.setTagger('verified', signer);
+await domainCtx.setTagger('socialLinks', signer);
 
 // Set values
 await tagCtx.setTag('alice.com', 'bio', 'Web3 enthusiast');
@@ -486,7 +540,7 @@ await tagCtx.setTag('alice.com', 'socialLinks', [
 ]);
 
 // Read all tags
-const tags = await domain.getAllTags();
+const tags = await domainCtx.getAllTags();
 console.log(tags);
 ```
 
@@ -503,7 +557,7 @@ const nftType = TagTypeBuilder.tuple([
 ]);
 
 await tagCtx.defineTag('nftMetadata', nftType);
-await domain.setTagger('nftMetadata', signerAddress);
+await domainCtx.setTagger('nftMetadata', signerAddress);
 
 // Set NFT metadata
 await tagCtx.setTag('nft.com', 'nftMetadata', {
@@ -529,10 +583,10 @@ 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);
+await domainCtx.setTagger('apiEndpoint', SERVICE_ADMIN);
+await domainCtx.setTagger('rpcNodes', SERVICE_ADMIN);
+await domainCtx.setTagger('maxRetries', SERVICE_ADMIN);
+await domainCtx.setTagger('enabled', SERVICE_ADMIN);
 
 // Service admin sets config
 await tagCtx.setTag('service.com', 'apiEndpoint', 'https://api.example.com');

package/config.json

@@ -3,18 +3,20 @@
         "sepolia": {
             "rpc": "https://sepolia.optimism.io",
             "contractDid": "0xe2D7c3a9013960E04d4E9F5F9B63fff37eEd97A8",
-            "contractRootResolver": "0xcB045D9133A4F5ffCe2C98b2C47e951e8c9A0655",
+            "contractRootResolver": "0xbEE79099eD3eD33c8ce57df9fb79370aAc79f261",
             "contractAbiType": "0x7386fCBae6Ad4CCE1499d9153D99bc950B589718",
             "contractRootResolver2": "0xcbC02aa08c77a374eC0D5A0403E108b7573d96e8",
-            "supportSvcUrl": "https://api-test.olares.com/did/support"
+            "supportSvcUrl": "https://api-test.olares.com/did/support",
+            "queryContract": "0xAf0430AB9f2450c52E7401846C7CA702D53eCFC2"
         },
         "mainnet": {
             "rpc": "https://optimism-rpc.publicnode.com",
             "contractDid": "0x5DA4Fa8E567d86e52Ef8Da860de1be8f54cae97D",
-            "contractRootResolver": "0x0223be5559961f9D393b28EFD1dBEdcB2dD67523",
+            "contractRootResolver": "0x9bA3D0D3d2046aeD57e9897F7F79C58DfAa5325A",
             "contractAbiType": "0x9ae3F16bD99294Af1784beB1a0A5C84bf2636365",
             "contractRootResolver2": "0x7e7961aB771cA942CE4DB6e79579e016a33Dc95B",
-            "supportSvcUrl": "https://api.olares.com/did/support"
+            "supportSvcUrl": "https://api.olares.com/did/support",
+            "queryContract": "0x8305411EEa5C3F99f9426845Cf2977E77D5a1711"
         }
     }
 }