@the_library/web3-registry-addresses 1.1.0 → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +56 -45
- package/dist/index.d.ts +28 -46
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,10 +1,6 @@
|
|
|
1
1
|
# @the_library/web3-registry-addresses
|
|
2
2
|
|
|
3
|
-
This package
|
|
4
|
-
|
|
5
|
-
## Overview
|
|
6
|
-
|
|
7
|
-
The `web3-registry-addresses` module acts as the canonical bridge to our immutable blockchain infrastructure. It is responsible for translating decentralized records and managing Web3 sessions, ensuring that clients always connect to the accurate, certified ledgers endorsed by [dsafe.us](https://dsafe.us).
|
|
3
|
+
Welcome to the D-Library Web3 ecosystem! This package is the crucial "bridge" that connects your frontend application to the exact, certified Smart Contracts endorsed by [dsafe.us](https://dsafe.us) for the decentralized **D-Library** project.
|
|
8
4
|
|
|
9
5
|
## Legal Notice & D-CODE OPEN SOVEREIGN LICENCE
|
|
10
6
|
|
|
@@ -21,68 +17,83 @@ As defined in **Section 3: Technical Anchors & Hard-Fork Resilience** of the lic
|
|
|
21
17
|
|
|
22
18
|
This restriction prevents forking intended to restrict public access or bypass the D-SAFE Specification requirements.
|
|
23
19
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
```bash
|
|
27
|
-
npm install @the_library/web3-registry-addresses
|
|
28
|
-
```
|
|
20
|
+
---
|
|
29
21
|
|
|
30
|
-
##
|
|
22
|
+
## 🚀 Getting Started for Junior Developers
|
|
31
23
|
|
|
32
|
-
|
|
24
|
+
In the world of Web3, contract addresses can change if the developers upgrade the system.
|
|
25
|
+
Instead of hardcoding those addresses into your Vue.js or React application, you use this package to dynamically fetch the most up-to-date, official addresses directly from the blockchain!
|
|
33
26
|
|
|
34
|
-
|
|
35
|
-
import { registryAddressLoader } from '@the_library/web3-registry-addresses';
|
|
36
|
-
import { AddressRegistryReadAPI, Tech } from '@the_library/web3-core';
|
|
37
|
-
```
|
|
27
|
+
Because querying the blockchain is slow, this package automatically intercepts those addresses and caches them instantly inside the user's **Browser `localStorage`** for 24 hours.
|
|
38
28
|
|
|
39
|
-
###
|
|
29
|
+
### Installation
|
|
40
30
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
- Returns a normalized dictionary of contract addresses.
|
|
31
|
+
```bash
|
|
32
|
+
npm install @the_library/web3-registry-addresses
|
|
33
|
+
```
|
|
45
34
|
|
|
46
|
-
|
|
47
|
-
A synchronous, zero-latency lookup that retrieves the certified smart contract address from the active loader cache.
|
|
35
|
+
*(Note: Depending on which blockchains you want to support, you will also need the corresponding reader packages, like `@the_library/web3-evm` or `@the_library/web3-tron`).*
|
|
48
36
|
|
|
49
|
-
|
|
50
|
-
Synchronously retrieves the parsed Arweave ABI JSON structure from the local cache.
|
|
37
|
+
### 1. Bootstrapping the Cache (Initialization)
|
|
51
38
|
|
|
52
|
-
|
|
53
|
-
This package also actively re-exports the canonical baseline `config` from `@the_library/web3-contracts`. This allows developers to easily loop over every endorsed network and instantiate the Web3 architecture programmatically:
|
|
39
|
+
When your application first loads, you need to "Boot" the D-CODE registry. This reads the official configuration loop and instructs this package to go out, fetch the addresses, and save them to the browser.
|
|
54
40
|
|
|
55
41
|
```typescript
|
|
56
42
|
import { config, registryAddressLoader } from '@the_library/web3-registry-addresses';
|
|
57
|
-
import {
|
|
43
|
+
import { EvmRegistryReadAPI } from '@the_library/web3-evm';
|
|
44
|
+
import { TronRegistryReadAPI } from '@the_library/web3-tron';
|
|
58
45
|
|
|
59
46
|
const loadDCODEContracts = async () => {
|
|
60
|
-
// Iterate over all endorsed technologies (
|
|
47
|
+
// Iterate over all endorsed technologies (EVM, Tron, etc.)
|
|
61
48
|
for (const tech of Object.keys(config)) {
|
|
49
|
+
|
|
62
50
|
// Iterate over all official network configurations for that tech
|
|
63
|
-
for (const network of Object.keys(config[tech as
|
|
64
|
-
const networkConfig = config[tech as
|
|
65
|
-
|
|
51
|
+
for (const network of Object.keys(config[tech as keyof typeof config])) {
|
|
52
|
+
const networkConfig = config[tech as keyof typeof config][network];
|
|
66
53
|
console.log(`Loading ${tech} network ${network}...`);
|
|
67
54
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
55
|
+
try {
|
|
56
|
+
// 1. Instantiate the active Read API based on the technology
|
|
57
|
+
const registryApi = tech === 'evm'
|
|
58
|
+
? new EvmRegistryReadAPI(networkConfig)
|
|
59
|
+
: new TronRegistryReadAPI(networkConfig);
|
|
60
|
+
|
|
61
|
+
// 2. Fetch and resolve the canonical smart contracts!
|
|
62
|
+
// This checks localStorage. If there is no cache, it asks the blockchain.
|
|
63
|
+
const addresses = await registryAddressLoader.Initialize(
|
|
64
|
+
tech as any,
|
|
65
|
+
network,
|
|
66
|
+
registryApi
|
|
67
|
+
);
|
|
68
|
+
|
|
69
|
+
console.log(`Resolved Contracts for ${tech}:${network}:`, addresses);
|
|
70
|
+
} catch (e) {
|
|
71
|
+
console.error(`Failed to load registry for ${network}`, e);
|
|
72
|
+
}
|
|
81
73
|
}
|
|
82
74
|
}
|
|
83
75
|
}
|
|
84
76
|
```
|
|
85
77
|
|
|
78
|
+
### 2. Using the Cached Addresses Instantly
|
|
79
|
+
|
|
80
|
+
Once `Initialize` has finished anywhere in your app, you never have to `await` or fetch from the blockchain again for that session! You can instantly grab the certified address in any Vue component:
|
|
81
|
+
|
|
82
|
+
```typescript
|
|
83
|
+
import { registryAddressLoader } from '@the_library/web3-registry-addresses';
|
|
84
|
+
|
|
85
|
+
// Example: Get the CORE Testnet address for the "Factory" contract
|
|
86
|
+
const getFactoryAddress = () => {
|
|
87
|
+
// This is synchronous and zero-latency! It reads directly from RAM/localStorage.
|
|
88
|
+
const address = registryAddressLoader.getAddress('evm', 1114, 'Factory');
|
|
89
|
+
|
|
90
|
+
if (!address) throw new Error("Registry Cache is not initialized!");
|
|
91
|
+
return address;
|
|
92
|
+
}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
By using this flow, your frontend is blazing fast, perfectly synced with the blockchain, and fully compliant with the D-SAFE architectural requirements!
|
|
96
|
+
|
|
86
97
|
---
|
|
87
98
|
**COPYRIGHT:** © 2026 DATAPOND PUBLIC LIBRARY TRUST - Australia
|
|
88
99
|
**TECHNICAL GUARDIAN:** POND ENTERPRISE PTY LTD - Australia
|
package/dist/index.d.ts
CHANGED
|
@@ -1,14 +1,16 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
1
|
+
import { Tech, AddressRegistryReadAPI } from '@the_library/web3-core';
|
|
2
|
+
export * from '@the_library/web3-contracts';
|
|
3
|
+
|
|
4
|
+
interface ContractLoadingStatus {
|
|
5
|
+
name: string;
|
|
6
|
+
status: 'pending' | 'loading' | 'loaded' | 'error';
|
|
7
|
+
address?: string;
|
|
5
8
|
}
|
|
6
|
-
interface
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
9
|
+
interface LoadingStatus {
|
|
10
|
+
total: number;
|
|
11
|
+
loaded: number;
|
|
12
|
+
contracts: ContractLoadingStatus[];
|
|
10
13
|
}
|
|
11
|
-
|
|
12
14
|
interface CacheEntry {
|
|
13
15
|
address: string;
|
|
14
16
|
abi: any;
|
|
@@ -20,52 +22,32 @@ interface RegistryCache {
|
|
|
20
22
|
entries: {
|
|
21
23
|
[contractName: string]: CacheEntry;
|
|
22
24
|
};
|
|
25
|
+
dataEntries?: {
|
|
26
|
+
[dataKey: string]: string;
|
|
27
|
+
};
|
|
23
28
|
}
|
|
24
29
|
declare class RegistryAddressLoader {
|
|
30
|
+
private defered;
|
|
25
31
|
private memoryCache;
|
|
32
|
+
private listeners;
|
|
33
|
+
private loadingStatuses;
|
|
26
34
|
private getCacheKey;
|
|
27
35
|
private getFromLocalStorage;
|
|
28
36
|
private saveToLocalStorage;
|
|
37
|
+
subscribe(listener: (tech: Tech, chainId: string | number, status: LoadingStatus) => void): () => void;
|
|
38
|
+
private notify;
|
|
39
|
+
getLoadingStatus(tech: Tech, chainId: string | number): LoadingStatus | undefined;
|
|
29
40
|
private fetchAbiFromArweave;
|
|
30
|
-
|
|
41
|
+
loadAllKeys(tech: Tech, chainId: number | string): Promise<Record<string, string>>;
|
|
42
|
+
Initialize(tech: Tech, chainId: number | string, registry: AddressRegistryReadAPI, registryAddress?: string): Promise<Record<string, string>>;
|
|
31
43
|
getAddress(tech: string, chainId: string | number, name: string): string | undefined;
|
|
32
44
|
getAbi(tech: string, chainId: string | number, name: string): any;
|
|
45
|
+
getData(tech: string, chainId: string | number, key: string): string | undefined;
|
|
33
46
|
}
|
|
34
47
|
declare const registryAddressLoader: RegistryAddressLoader;
|
|
48
|
+
/**
|
|
49
|
+
* Proxy to registryAddressLoader for backward compatibility
|
|
50
|
+
*/
|
|
51
|
+
declare function getContractAbi(ecosystem: string, networkId: string | number, contractName: string): any;
|
|
35
52
|
|
|
36
|
-
|
|
37
|
-
"chainId": number | string;
|
|
38
|
-
"main": boolean;
|
|
39
|
-
"symbol": string;
|
|
40
|
-
"website": string;
|
|
41
|
-
"rpc": string;
|
|
42
|
-
"explorer": string;
|
|
43
|
-
"name": string;
|
|
44
|
-
"original": string;
|
|
45
|
-
"shortName": string;
|
|
46
|
-
"deployed": boolean;
|
|
47
|
-
"addresses"?: {
|
|
48
|
-
"addressRegistry"?: string;
|
|
49
|
-
"factory"?: string;
|
|
50
|
-
"bouncerStorage"?: string;
|
|
51
|
-
"scientistStorage"?: string;
|
|
52
|
-
"backupStorage"?: string;
|
|
53
|
-
"projectManagerStorage"?: string;
|
|
54
|
-
};
|
|
55
|
-
brand: 'CORE' | 'TRON';
|
|
56
|
-
"decimals": number;
|
|
57
|
-
faucet?: string;
|
|
58
|
-
faucetAmount?: number;
|
|
59
|
-
}
|
|
60
|
-
interface ContractConfigs {
|
|
61
|
-
evm: {
|
|
62
|
-
[chainId: string]: ProviderConfig;
|
|
63
|
-
};
|
|
64
|
-
tron: {
|
|
65
|
-
[chainId: string]: ProviderConfig;
|
|
66
|
-
};
|
|
67
|
-
}
|
|
68
|
-
|
|
69
|
-
declare const _default: ContractConfigs;
|
|
70
|
-
|
|
71
|
-
export { type CacheEntry, RegistryAddressLoader, type RegistryCache, _default as config, registryAddressLoader };
|
|
53
|
+
export { type CacheEntry, type ContractLoadingStatus, type LoadingStatus, RegistryAddressLoader, type RegistryCache, getContractAbi, registryAddressLoader };
|
package/dist/index.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
var
|
|
1
|
+
var E="dcode_registry_cache_v2_",x=1440*60*1e3,p=class{constructor(){this.defered={};this.memoryCache=new Map;this.listeners=new Set;this.loadingStatuses=new Map}getCacheKey(e,t){return`${E}${e}_${t}`}getFromLocalStorage(e){let t=localStorage.getItem(e);if(!t)return null;try{return JSON.parse(t)}catch(s){return console.error(`[RegistryLoader] Failed to parse cache for ${e}`,s),null}}saveToLocalStorage(e,t){localStorage.setItem(e,JSON.stringify(t))}subscribe(e){return this.listeners.add(e),()=>this.listeners.delete(e)}notify(e,t,s){let a=`${e}:${t}`;this.loadingStatuses.set(a,s),this.listeners.forEach(o=>o(e,t,s))}getLoadingStatus(e,t){return this.loadingStatuses.get(`${e}:${t}`)}async fetchAbiFromArweave(e){if(!e)return null;try{let t=await fetch(`https://arweave.net/${e}`);if(t.ok){let s=await t.json();return console.log(`[RegistryLoader] Successfully fetched ABI for ${e}`),s}console.error(`[RegistryLoader] Arweave fetch failed for ${e}: ${t.status} ${t.statusText}`)}catch(t){console.warn(`[RegistryLoader] Failed to fetch ABI from Arweave (${e}):`,t)}return null}async loadAllKeys(e,t){let s={},a=this.getCacheKey(e,t),o=`${e}-${t}`;typeof this.defered[o]<"u"&&await this.defered[o];let d=this.memoryCache.get(a)||this.getFromLocalStorage(a);if(d)return this.memoryCache.set(a,d),Object.values(d.entries).forEach(u=>{let y=u.originalName.charAt(0).toLowerCase()+u.originalName.slice(1);s[y]=u.address}),s;throw new Error(`No cache found for ${e}:${t}`)}async Initialize(e,t,s,a){console.log(`[RegistryLoader] Starting Initialization for ${e}:${t} using AddressRegistry at ${a||"unknown"}`);let o=this.getCacheKey(e,t),d=Date.now(),u=`${e}-${t}`;if(typeof this.defered[u]<"u")return this.loadAllKeys(e,t);let y,v;this.defered[u]=new Promise((r,n)=>{y=r,v=n});let g=this.memoryCache.get(o)||this.getFromLocalStorage(o);if(g&&d-g.timestamp<x){console.log(`[RegistryLoader] Cache valid for ${e}:${t}`);let r=this.loadAllKeys(e,t);return y(!0),r}console.log(`[RegistryLoader] Cache expired or missing for ${e}:${t}. Performing Full Sync...`);let m=await s.getAllContractNames(),h=[];try{h=await s.getAllDataKeys()}catch{console.warn(`[RegistryLoader] Failed to fetch data keys (method may not exist yet on this network for ${e}:${t})`)}console.log(`[RegistryLoader] Retrieved ${m.length} contract names and ${h.length} data keys for ${e}:${t} (Registry at ${a}):`,m,h);let i={total:m.length+h.length,loaded:0,contracts:m.map(r=>({name:r,status:"pending"}))};this.notify(e,t,i);let w={},L={},R={},A=m.map(async r=>{let n=i.contracts.find(c=>c.name===r);n.status="loading",this.notify(e,t,{...i});try{let[c,l]=await s.getLatestContract(r);console.log(`[RegistryLoader] Found ${r} at ${c} (ABI: ${l}) for ${e}:${t}`);let f=r.toLowerCase(),K=r.charAt(0).toLowerCase()+r.slice(1),$=null;g&&g.entries[f]&&g.entries[f].txId===l?$=g.entries[f].abi:l?(console.log(`[RegistryLoader] Fetching new ABI for ${r} (${l})...`),$=await this.fetchAbiFromArweave(l)):console.warn(`[RegistryLoader] No ABI URL found for ${r} on ${e}:${t}`),w[f]={address:c,abi:$,txId:l,originalName:r},R[K]=c,n.status=$||!l?"loaded":"error",n.address=c}catch(c){console.warn(`[RegistryLoader] Failed to load contract ${r} for ${e}:${t}:`,c),n.status="error"}finally{i.loaded++,this.notify(e,t,{...i})}}),S=h.map(async r=>{try{let n=await s.getLatestData(r);L[r]=n,console.log(`[RegistryLoader] Found data ${r} = ${n} for ${e}:${t}`)}catch(n){console.warn(`[RegistryLoader] Failed to load data ${r} for ${e}:${t}:`,n)}finally{i.loaded++,this.notify(e,t,{...i})}});await Promise.all([...A,...S]);let b={timestamp:i.contracts.some(r=>r.status==="error")?g?.timestamp||0:d,entries:w,dataEntries:L};return this.memoryCache.set(o,b),this.saveToLocalStorage(o,b),y(!0),R}getAddress(e,t,s){let a=this.getCacheKey(e,t);return this.memoryCache.get(a)?.entries[s.toLowerCase()]?.address}getAbi(e,t,s){let a=this.getCacheKey(e,t);return this.memoryCache.get(a)?.entries[s.toLowerCase()]?.abi}getData(e,t,s){let a=this.getCacheKey(e,t);return this.memoryCache.get(a)?.dataEntries?.[s]}},F=new p;function P(C,e,t){return F.getAbi(C,e,t)}export*from"@the_library/web3-contracts";export{p as RegistryAddressLoader,P as getContractAbi,F as registryAddressLoader};
|
|
2
2
|
//# sourceMappingURL=index.js.map
|