Skip to content

Commit 65e9787

Browse files
chore: updated doc (#734)
Signed-off-by: Luigi Navarro <luigi@io.builders> Signed-off-by: Mario Francia <mariofranciarius@gmail.com> Co-authored-by: Luigi Navarro <luigi@io.builders>
1 parent 365d91a commit 65e9787

File tree

3 files changed

+114
-218
lines changed

3 files changed

+114
-218
lines changed

packages/ats/contracts/README.md

Lines changed: 47 additions & 212 deletions
Original file line numberDiff line numberDiff line change
@@ -9,24 +9,26 @@
99
### Table of Contents
1010

1111
- **[Description](#description)**<br>
12-
- **[Installation](#installation)**<br>
13-
- **[Build](#build)**<br>
14-
- **[Tasks](#tasks)**<br>
12+
- **[Quick Start](#quick-start)**<br>
13+
- **[Deployment & Tasks](#deployment--tasks)**<br>
1514
- **[Test](#test)**<br>
15+
- **[Architecture](#architecture)**<br>
16+
- **[ERC-3643 Compatibility](#erc-3643-compatibility)**<br>
1617

1718
# Description
1819

1920
The contracts module contains the code of all Solidity smart contracts deployed on Hedera. This package is part of the Asset Tokenization Studio monorepo.
2021

21-
The standard used for security tokens is ERC-1400.
22+
**Standards:**
2223

23-
Version 1.15.0 introduces partial compatibility with the ERC-3643 (TREX) standard; full identity and compliance support will be added in future releases.
24+
- ERC-1400 for security tokens
25+
- Partial ERC-3643 (TREX) compatibility (v1.15.0+)
2426

25-
## Workspace Context
27+
**Location:** `packages/ats/contracts` within the monorepo
2628

27-
This package is located at `packages/ats/contracts` within the monorepo. Other packages (like the SDK) depend on the compiled artifacts from this package.
29+
# Quick Start
2830

29-
# Installation
31+
## Installation
3032

3133
From the monorepo root:
3234

@@ -43,18 +45,17 @@ npm install
4345
npm run compile
4446
```
4547

46-
# Build
47-
48-
Build contracts using workspace commands from the root:
48+
## Build
4949

5050
```bash
51+
# From monorepo root
5152
npm run ats:contracts:build
52-
```
53-
54-
Or build all ATS components:
5553

56-
```bash
54+
# Or build all ATS components
5755
npm run ats:build
56+
57+
# Force recompile
58+
npm run compile:force
5859
```
5960

6061
## ERC-3643 compatibility
@@ -90,142 +91,30 @@ npm run ats:build
9091
| batchFreezePartialTokens(address[] calldata \_userAddresses, uint256[] calldata \_amounts) external | Done |
9192
| batchUnfreezePartialTokens(address[] calldata \_userAddresses, uint256[] calldata \_amounts) external | Done |
9293

93-
# Installation
94-
95-
Run the command :
96-
97-
```
98-
npm ci
99-
```
100-
101-
# Build
94+
# Deployment & Tasks
10295

103-
Run the command :
96+
**For complete documentation on deployment, tasks, and Hardhat commands, see [Scripts README](scripts/README.md).**
10497

105-
```
106-
npm run compile:force
107-
```
98+
The Scripts README contains comprehensive information about:
10899

109-
# Tasks
100+
- **🚀 Deployment workflows** - Full system deployment, individual components, network configuration
101+
- **📋 Hardhat tasks** - All available tasks with parameters and examples
102+
- **🏗️ Architecture** - Framework-agnostic design, domain separation, registry system
103+
- **📚 API Reference** - TypeScript APIs for programmatic deployment
104+
- **🔧 Troubleshooting** - Common issues and solutions
105+
- **💡 Developer guides** - Adding facets, creating asset types
110106

111-
### deployAll
112-
113-
Deploys the full infrastructure (factory, resolver, facets, and initialized contracts) in a single execution.
114-
115-
**Parameters**:
116-
117-
- `useDeployed` (optional, default: true): Reuses already deployed contracts.
118-
- `file-name` (optional): The output file name.
119-
- `privateKey` (optional): Private key in raw hexadecimal format.
120-
- `signerAddress` (optional): Signer address from the Hardhat signers array.
121-
- `signerPosition` (optional): Index of the signer in the Hardhat signers array.
122-
- `network` (optional): The network to run the command on (e.g., localhost, mainnet, testnet).
107+
**Quick deployment commands:**
123108

124109
```bash
125-
npx hardhat deployAll --useDeployed false
126-
```
110+
# Deploy full system to Hardhat network (in-memory, fast)
111+
npm run deploy:hardhat -- --network hardhat
127112

128-
### deploy
113+
# Deploy to Hedera Testnet (requires .env configuration)
114+
npm run deploy:hardhat -- --network hedera-testnet
129115

130-
Deploys a specific contract.
131-
132-
**Parameters**:
133-
134-
- `contractName` (required): Name of the contract to deploy (e.g., ERC20, Bond).
135-
- `privateKey` (optional): Private key in raw hexadecimal format.
136-
- `signerAddress` (optional): Signer address from the Hardhat signers array.
137-
- `signerPosition` (optional): Index of the signer in the Hardhat signers array.
138-
139-
```bash
140-
npx hardhat deploy --contractName ERC20
141-
```
142-
143-
### keccak256
144-
145-
Calculates and prints the Keccak-256 hash of a given string.
146-
147-
**Parameters:**
148-
149-
- `input` (required): The string to be hashed.
150-
151-
```bash
152-
npx hardhat keccak256 "ADMIN_ROLE"
153-
```
154-
155-
### getConfigurationInfo
156-
157-
Fetches and displays detailed information about all facets (implementations) associated with a specific configuration ID from the BusinessLogicResolver.
158-
159-
**Parameters:**
160-
161-
- `resolver` (required): The resolver proxy admin address.
162-
- `configurationId` (required): The configuration ID.
163-
- `network` (required): The network to use (e.g., local, previewnet, testnet, mainnet).
164-
165-
```bash
166-
npx hardhat getConfigurationInfo <resolverAddress> <configurationId> --network <network-name>
167-
```
168-
169-
### getResolverBusinessLogics
170-
171-
Retrieves and lists all registered business logic keys (contract identifiers) from a BusinessLogicResolver contract.
172-
173-
**Parameters:**
174-
175-
- `resolver` (required): The resolver proxy admin address.
176-
- `network` (required): The network to use (e.g., local, previewnet, testnet, mainnet).
177-
178-
```bash
179-
npx hardhat getResolverBusinessLogics <resolverAddress> --network <network-name>
180-
```
181-
182-
### updateBusinessLogicKeys
183-
184-
Registers or updates the addresses of a list of business logic implementation contracts in a specified `BusinessLogicResolver`.
185-
186-
**Parameters:**
187-
188-
- `resolverAddress` (required): The address of the `BusinessLogicResolver` contract.
189-
- `implementationAddressList` (required): A comma-separated list of contract addresses to be registered or updated in the resolver.At least all facets already registered must be included.
190-
- `privateKey` (optional): The private key in raw hexadecimal format of the account that will sign the transaction.
191-
- `signerAddress` (optional): The address of the signer to select from the Hardhat signers array.
192-
- `signerPosition` (optional): The index of the signer to select from the Hardhat signers array.
193-
- `network` (required): The network to run the command on (e.g., localhost, mainnet, testnet).
194-
195-
```bash
196-
npx hardhat updateBusinessLogicKeys <resolverAddress> <allFacetsAddressList> --network <network-name>
197-
```
198-
199-
### updateProxyImplementation
200-
201-
Upgrades the implementation address for a given transparent proxy contract. This task executes the upgrade by calling the `upgrade` function on the associated `ProxyAdmin` contract. The signer executing this task must be the owner of the `ProxyAdmin` contract.
202-
203-
**Parameters:**
204-
205-
- `proxyAdminAddress` (required): The address of the `ProxyAdmin` contract that owns the proxy.
206-
- `transparentProxyAddress` (required): The address of the transparent proxy contract to be upgraded.
207-
- `newImplementationAddress` (required): The address of the new implementation contract.
208-
- `privateKey` (optional): The private key in raw hexadecimal format of the account that will sign the transaction.
209-
- `signerAddress` (optional): The address of the signer to select from the Hardhat signers array.
210-
- `signerPosition` (optional): The index of the signer to select from the Hardhat signers array.
211-
- `network` (required): The network to run the command on (e.g., localhost, mainnet, testnet).
212-
213-
```bash
214-
npx hardhat updateProxyImplementation <proxyAdminAddress> <transparentProxyAddress> <newImplementationAddress> --network <networkName>
215-
```
216-
217-
### getProxyAdminConfig
218-
219-
Retrieves key configuration details from a `ProxyAdmin` contract. It fetches the owner of the `ProxyAdmin` contract and the current implementation address for a specific proxy contract that it manages.
220-
221-
**Parameters:**
222-
223-
- `proxyAdmin` (required): The address of the `ProxyAdmin` contract.
224-
- `proxy` (required): The address of the proxy contract managed by the `ProxyAdmin`.
225-
- `network` (required): The network to run the command on (e.g., localhost, mainnet, testnet).
226-
227-
```bash
228-
npx hardhat getProxyAdminConfig <proxyAdminAddress> <proxyAddress> --network <networkName>
116+
# Standalone deployment (~3x faster startup)
117+
npm run deploy
229118
```
230119

231120
# Test
@@ -344,75 +233,21 @@ The platform implements a comprehensive role-based access control system:
344233

345234
### Adding a new facet
346235

347-
When introducing a new facet to the project, make sure to follow these steps:
348-
349-
1. **Register the contract name** <br>
350-
Add the name of the new facet to the `CONTRACT_NAMES` array in the `Configuration.ts` file.
351-
352-
2. **Update the deploy task listener** <br>
353-
In the `deployAll` task, include the new facet so its contract address is properly tracked via the mirror node.
354-
355-
3. **Deploy the facet** <br>
356-
In `scripts/deploy.ts`, within the `deployAtsContracts` function, add the logic to deploy the new facet and ensure the script awaits its deployment.
357-
358-
4. **Configure facet selectors** <br>
359-
Ensure the facet's function selectors are properly registered in the diamond cut process.
360-
361-
# Deployed Smart Contracts
362-
363-
| **Contract** | **Address** | **ID** |
364-
| -------------------------------------- | ------------------------------------------ | ----------- |
365-
| Business Logic Resolver Proxy | 0xf44be70B71f412643378bbd731Ad3081282Fb033 | 0.0.6930056 |
366-
| Business Logic Resolver Proxy Admin | 0x80Dcb2A77E56E9520f8B04848D64167bfA378292 | 0.0.6930055 |
367-
| Business Logic Resolver | 0xce4f0e542bcfD0d8f1229baf9adcAC271ae5978c | 0.0.6930054 |
368-
| Factory Proxy | 0x66098aa13268a3f25B37ae532d483DcB08f6f522 | 0.0.6930123 |
369-
| Factory Proxy Admin | 0xE5cdBd8d28c048D7bC4929E0D0d3d33aFE1bc929 | 0.0.6930122 |
370-
| Factory | 0xdEbA1236Ca1dac9547F54fFAF4B297241c1F4467 | 0.0.6930121 |
371-
| Access Control Facet | 0xcD296f27245dD055bb3776a27a48D80da198b202 | 0.0.6930058 |
372-
| Cap Facet | 0x4DADAab326E6ab121f7Ed23d749229127cEe318A | 0.0.6930059 |
373-
| Control List Facet | 0xFb28f952b3f16669589DA8D769B07C7718e7f1D0 | 0.0.6930060 |
374-
| Kyc Facet | 0x4b8068C39ea5Ee9cf1Ba27fd6DA2b7D6c562Ca4f | 0.0.6930062 |
375-
| SsiManagement Facet | 0x8A81DC398fC597Df28E172823b1A8f87479dC0E5 | 0.0.6930063 |
376-
| Pause Facet | 0xD2677f8E9aa3A202a15d77191c02C55E1879A2E9 | 0.0.6930064 |
377-
| ERC20 Facet | 0x629bf025B6FDDB0D44643c55686571aa73289ef0 | 0.0.6930069 |
378-
| ERC1410 Read Facet | 0x1C0b482D81E623d206F2d3A52eE40bD42a64c8Fa | 0.0.6930070 |
379-
| ERC1410 Management Facet | 0xFB61834d2091eD4006cF1A346f34e5323aC30E40 | 0.0.6930071 |
380-
| ERC1410 Issuer Facet | 0x8718CDC4fD66C76eb64606035C8Ded127623A649 | 0.0.6930072 |
381-
| ERC1410 TokenHolder Facet | 0x6aB85765836A5E43692fFD2579C04254501b5E28 | 0.0.6930074 |
382-
| ERC1594 Facet | 0xE7cAB8Eb1E264584C85E9f0a1D66e50502e9b83e | 0.0.6930076 |
383-
| ERC1643 Facet | 0xE30Fde8b8F31d637D835088824b3B13E0E5B2352 | 0.0.6930077 |
384-
| ERC1644 Facet | 0x97FFcd4F0b1E52e0C0Ce9565d534Bae5531B9c9b | 0.0.6930079 |
385-
| Snapshots Facet | 0xa15Ff9CC404Ea6B4a4F0790A220d8CB3cAE06572 | 0.0.6930080 |
386-
| Diamond Facet | 0x22C93F496C438C7e63E4B56092969BA03b1417AE | 0.0.6930083 |
387-
| Equity Facet | 0xB24932c4d4FE51E906921a8897a5c0C10cFb11ff | 0.0.6930085 |
388-
| Bond Facet | 0x3F83d296eAd06d74672EEFEBE993C3D707A4f6C2 | 0.0.6930086 |
389-
| BondRead | 0x1d562F43FBDD1Cfe0E75683475B9CbDe203cDced | 0.0.6930084 |
390-
| Scheduled Snapshots Facet | 0xBC15Df6e164e90a8eBAfeFC848fA0605fFD22d04 | 0.0.6930087 |
391-
| Scheduled Balance Adjustments Facet | 0x66eaac9f0c142D39643ACb5D283eE7cAd6778d85 | 0.0.6930088 |
392-
| Scheduled Cross Ordered Tasks Facet | 0xA18e09C0AeC82c70f372fcE182F71aa7da9523c6 | 0.0.6930089 |
393-
| Corporate Actions Facet | 0x2B9464e2D13278b681ad08e9741BFADc58268438 | 0.0.6930090 |
394-
| Lock Facet | 0xe7932c9aC6198Fcb4Ff3fB571dF7f05Ed1b0196b | 0.0.6930065 |
395-
| Hold Read Facet | 0x7923909D008dc07F835ECCef7B333A4EaDf08432 | 0.0.6930066 |
396-
| Hold Management Facet | 0xff99e2ec8fb9565b9A04d7c8e4EE9223CaD8B27D | 0.0.6930067 |
397-
| Hold TokenHolder Facet | 0xd8CA90867F9D9434C3cc644dc2A1856543a27D30 | 0.0.6930068 |
398-
| Transfer and Lock Facet | 0xCAdCC836ffE50Aabd68137F17b914B5Bff22504e | 0.0.6930091 |
399-
| Adjust Balances Facet | 0xE4F1e2530afCd535FdAFe8CdEBFfC96ae8a5Cc70 | 0.0.6930092 |
400-
| Clearing Action Facet | 0x2F0BB35125407DFdB3BCFBcC3e947e69a0dc253e | 0.0.6930103 |
401-
| Clearing Transfer Facet | 0xce70D4F37b976bee2Aa961A0d89719314312def1 | 0.0.6930095 |
402-
| Clearing Redeem Facet | 0x322bfdfB61Efa214dc3ACD61362258233A4eD240 | 0.0.6930099 |
403-
| Clearing Hold Creation Facet | 0x9F72d0fD1992C10889D8B865736Ab0aFA8d6A9ac | 0.0.6930100 |
404-
| Clearing Read Facet | 0xd9c933C85b9B81C800Cd1F78c42469A6F681bAa7 | 0.0.6930101 |
405-
| Proceed Recipients Facet | 0xC07A6aE17660Df4E3a93FaBb288635BaeD218F99 | 0.0.6930104 |
406-
| External Pause Management Facet | 0x30FB9962a38a76Fe5A37f5B1d01A4F2d7074b5D8 | 0.0.6930105 |
407-
| External Control List Management Facet | 0x265dd9126e189Aa7AdF530468b0d2e97e139eBcB | 0.0.6930106 |
408-
| External Kyc List Management Facet | 0xbB6f8E0BDFaF5bE2AC551cc661C881c31d647155 | 0.0.6930109 |
409-
| Protected Partitions Facet | 0x903103Fb92eBBE331af410874bcad6218843518E | 0.0.6930093 |
410-
| ERC3643 Management Facet | 0x72a41aC5Df74381e3ed4812a10Dbc08c26dED5c6 | 0.0.6930111 |
411-
| ERC3643 Operations Facet | 0xc24bAc42E3FB05f76B47Da66791A74eFd4DeAf3c | 0.0.6930113 |
412-
| ERC3643 Read Facet | 0xB70962B5C7C670A0491fbd088e1375Eb09b54386 | 0.0.6930116 |
413-
| ERC3643 Batch Facet | 0x1dE35551d78B53B537Ba033d75D7b55D7dF5b5Ed | 0.0.6930118 |
414-
| Freeze Facet | 0xfd3C8ff63CD7648516702df850DF5B9c6dF7f17c | 0.0.6930119 |
415-
| ERC20Permit Facet | 0x4Ceb1b2df658C00a42E526bF546AEeE4E0eb6b6F | 0.0.6930075 |
236+
For detailed instructions on adding or removing facets, see the **[Developer Guide](scripts/DEVELOPER_GUIDE.md)** in the Scripts documentation.
237+
238+
# Reference Deployment (Hedera Testnet)
239+
240+
> **Note**: These contracts were deployed for reference purposes and may not reflect the latest version. For up-to-date deployments, use the deployment scripts with the current codebase version (v1.17.0+). See [Scripts README](scripts/README.md) for deployment instructions.
241+
242+
- **Network:** Hedera Testnet
243+
- **Status:** Reference deployment (may be outdated)
244+
- **Last Known Update:** Prior to v1.17.0
245+
246+
#### Contract Addresses
247+
248+
- ProxyAdmin: 0xE5ebB0990c841857fe43D6e0A8375F2991b265c0
249+
- BLR Proxy: 0xE13eFc5f5d8252958cA787a1F6665C63Fbd02A48
250+
- Factory Proxy: 0x0BC59c70933DA04C8556259BB8E78AbF7db4dC22
416251

417252
# 🔐 Role Definitions by Layer
418253

packages/ats/contracts/scripts/DEVELOPER_GUIDE.md

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
11
# Developer Guide: ATS Contracts Scripts
22

3-
**Last Updated**: 2025-01-19
4-
53
This guide provides practical, step-by-step instructions for the most common development tasks when working with ATS contract deployment scripts.
64

75
## Table of Contents
@@ -44,7 +42,7 @@ import { deployFacets } from "@scripts/infrastructure";
4442

4543
const [signer] = await ethers.getSigners(); // From Hardhat
4644
// or
47-
const signer = new ethers.Wallet(privateKey, provider); // Standalone
45+
const signer = new ethers.Walet(privateKey, provider); // Standalone
4846

4947
const result = await deployFacets(signer, {
5048
facetNames: ["AccessControlFacet"],

0 commit comments

Comments
 (0)