> For the complete documentation index, see [llms.txt](https://docs.rome.builders/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rome.builders/vi/ung-dung-tren-rome/bloom/building.md).

# Xây dựng trên Bloom

Hướng dẫn này trả lời một câu hỏi: **một builder tự làm điều này như thế nào?** Lấy một hợp đồng tài sản thực tế viết bằng Solidity, triển khai nó trên một chuỗi Rome dưới dạng token có cấp phép, mở nó cho cả ví Solana lẫn ví EVM mà không cần token thứ hai, và cắm quyết định KYC/tuân thủ của riêng bạn vào.

Đối tượng là một nhà phát triển đang đánh giá hoặc áp dụng cách tiếp cận này. Bloom là ví dụ xuyên suốt — tài sản đang hoạt động của nó **ARCV ("Mineral Vault I")** trên Hadrian (`200010`) là một trường hợp thực tế của mọi bước bên dưới, và biên nhận triển khai của nó (`deployments/200010.tokens/ARCV.json`) ghi lại chính xác ba hợp đồng và tám giao dịch mà phương pháp này tạo ra.

Không có gì ở đây sửa đổi các hợp đồng tài sản. Bloom chạy framework Arc của Plume **không sửa đổi** (cây mã được vendored trong `contracts/`, giống byte hoàn toàn với `plumenetwork/contracts` ở commit được ghim trong `NOTICE`); hợp đồng duy nhất phía Rome là `ArcTokenFactoryV2`, bổ sung thêm một hàm. Công việc nằm ở chỗ *cách* bạn triển khai và *cách* bạn điều khiển các hợp đồng — chứ không phải sửa đổi chúng.

> **Phương pháp, nhìn lướt qua.** Một token có cấp phép là **ba** hợp đồng đã triển khai. Nó được triển khai **từng phần** — một hợp đồng cho mỗi giao dịch — vì một lệnh factory trong một giao dịch vượt quá giới hạn account mỗi giao dịch của Rome. Các proxy của nó phải đến từ **các artifact được khóa nguồn gốc** nếu không việc đăng ký on-chain sẽ thất bại an toàn. Tuân thủ là một **boolean cho mỗi địa chỉ**, do bất kỳ ai mà quy trình KYC của bạn cho phép ghi vào. Và cùng một lần triển khai đó cũng có thể được truy cập từ ví Solana thông qua một **sender tổng hợp** được suy ra on-chain — không token thứ hai, không allowlist thứ hai.

## Điều kiện tiên quyết

> **Trước khi bắt đầu.** Bộ công cụ cho issuer mà hướng dẫn này dùng vẫn chưa được công bố. Bao gồm các script (`deploy-infra.ts`, `create-token.ts` và phần còn lại), các cây mã `contracts/` và `rome-contracts/` và các biên nhận triển khai mà nó đặt tên. Issuer nhận bộ công cụ này bằng cách onboard với Rome. Trước đó, hãy đọc hướng dẫn như một mô tả về phương pháp và về việc từng script làm gì.

Bộ công cụ tham chiếu nằm trong một thư mục `scripts/` (được cung cấp lúc onboarding; cài các phụ thuộc bằng `npm install`). Mọi lệnh đều lấy thông tin chain từ registry thay vì hardcode, nên việc chuyển sang một chuỗi Rome khác là thay đổi môi trường, không phải thay đổi mã:

```bash
export PRIVATE_KEY=…       # khóa deployer/issuer được nạp vốn trên chuỗi mục tiêu
export CHAIN_ID=200010     # chọn chuỗi
export REGISTRY_ROOT=…     # một checkout của registry chuỗi Rome
# Các luồng trên Solana lane cũng cần:
export SOLANA_KEYPAIR=…    # đường dẫn tới JSON keypair Solana đã được nạp vốn (fee payer)
```

Gas trên các chuỗi Rome được định giá bằng USDC; toàn bộ trình tự deploy tốn khoảng 10–15 đơn vị native trên devnet. Keys chỉ đến từ môi trường — không bao giờ từ repo. Hãy build các hợp đồng một lần trước khi deploy, vì các artifact **phải** đến từ `rome-contracts/out` (xem bước 3):

```bash
cd contracts       && forge build --via-ir     # bộ Arc được vendored
cd rome-contracts  && forge build --via-ir     # ArcTokenFactoryV2 + proxy chuẩn
```

***

## Bước 1 — Hiểu một token có cấp phép *là* ở đây

Một token Bloom có cấp phép không phải là một hợp đồng. Nó là **ba hợp đồng đã triển khai**, cộng thêm bốn hợp đồng dùng chung mà ops triển khai một lần cho mỗi chuỗi và mọi issuer đều tái sử dụng.

**Ba hợp đồng riêng theo từng token** — một tài sản sở hữu đúng các hợp đồng này:

| Hợp đồng                     | Nguồn                                                       | Nó là gì                                                                                                             |
| ---------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `ArcTokenProxy`              | `contracts/src/proxy/ArcTokenProxy.sol`                     | Bản thân token — một proxy UUPS trỏ tới phần triển khai dùng chung `ArcToken` . Số dư, holder và role đều nằm ở đây. |
| `WhitelistRestrictions`      | `contracts/src/restrictions/WhitelistRestrictions.sol`      | Module allowlist. Một boolean cho mỗi địa chỉ; được thực thi ở mọi lần chuyển khi tài sản đang bị gate.              |
| `YieldBlacklistRestrictions` | `contracts/src/restrictions/YieldBlacklistRestrictions.sol` | Module yield. Loại trừ các địa chỉ khỏi phân phối yield mà không đụng tới số lượng nắm giữ của họ.                   |

**Bốn hợp đồng dùng chung, một trên mỗi chuỗi** (được deploy bởi `deploy-infra.ts`):

| Hợp đồng                     | Vai trò                                                                  |
| ---------------------------- | ------------------------------------------------------------------------ |
| `RestrictionsRouter`         | Registry kiểu module — dây nối chain, được ops thiết lập một lần.        |
| `ArcTokenFactoryV2`          | Đăng ký + codehash proxy chuẩn (các bước 2–3).                           |
| `ArcToken` (phần triển khai) | Logic tài sản dùng chung, có thể tái sử dụng mà mọi token đều proxy tới. |
| `ArcTokenPurchase`           | Một storefront duy nhất, được mọi token và issuer dùng chung (bước 4).   |
| wUSDC                        | Nhánh tiền mặt — tiền tệ yield và tiền tệ mua bán.                       |

Hạn chế chuyển và hạn chế yield **là các module tách biệt có chủ đích**: một holder có thể bị cấm nhận thu nhập nhưng vẫn giữ tài sản, và đó là cách lệnh trừng phạt và lệnh tòa thực sự vận hành.

Sự thật "ba hợp đồng" này là điểm then chốt cho việc xác minh. `verify-deployments.ts` và `register-asset.ts` cả hai đều kỳ vọng một token quy về ba hợp đồng đã triển khai — việc xác minh thủ công một token từng bỏ sót bảy trong số đó trên một chuỗi (mọi yield module và ba whitelist module).

Vòng đời có ba pha và một cánh cửa một chiều:

```
draft     proxy đang live, chưa liên kết module nào — không có gì gate một lần chuyển
  ↓
ungated   module đã liên kết, transfersAllowed = true   (WhitelistRestrictions.initialize đặt giá trị này)
  ↓  mint supply, xây allowlist               [có thể đảo ngược]
gated     setTransfersAllowed(false)                [CÁNH CỬA MỘT CHIỀU — supply trở thành cuối cùng]
```

Việc gate là một chiều đối với supply vì mint và burn đi qua `address(0)` làm đối tác giao dịch, và `address(0)` không bao giờ có thể được đưa vào allowlist — nên một khi đã gated thì sẽ không bao giờ có thể mint supply mới nữa. Đó là đảm bảo mà một tài sản có cấp phép đưa ra cho holder của nó.

***

## Bước 2 — Triển khai từng phần, tuyệt đối không làm trong một giao dịch

Arc có một lệnh `createToken` kiểu một phát triển khai proxy và cả hai module rồi wire chúng trong một lần gọi duy nhất. **Trên Rome bạn không thể dùng nó.** Giao dịch đó cần **77 lock account Solana**, còn giới hạn mỗi giao dịch của Rome là **62 lock**. Nó không bao giờ nhét vừa — không phải bằng tinh chỉnh, cũng không phải bằng một bước tối ưu hóa.

Vì vậy việc deploy là **từng phần**: mỗi hợp đồng trong một giao dịch riêng, và token đạt trạng thái tương đương factory thông qua `ArcTokenFactoryV2.registerToken` thay vì qua `createToken`. Đây là wizard tạo, và đó là thứ mà console của issuer thực hiện từng bước:

![wizard tạo](https://4233397286-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F671PKS8ZQSNqtoC8PGvz%2Fuploads%2Fgit-blob-94683a3a49ac2418aed8cc66dbf47fad940814f7%2Fcreate-wizard.png?alt=media\&token=38b47568-d343-483d-8ce1-f437164bdeae)

Bản triển khai tham chiếu là `arc/plan/create.ts` (`createSequence()`), mà ứng dụng hiển thị thành sáu thẻ (`bloom/lib/createCards.ts`) trên **tám giao dịch**, theo đúng thứ tự mà các hợp đồng yêu cầu:

| # | Giao dịch                            | Lời gọi hợp đồng                                                                   |
| - | ------------------------------------ | ---------------------------------------------------------------------------------- |
| 1 | Triển khai tài sản                   | `new ArcTokenProxy(impl, initData)` trong đó `initData = ArcToken.initialize(...)` |
| 2 | Triển khai mô-đun danh sách cho phép | `new WhitelistRestrictions()`                                                      |
| 3 | Đặt bạn làm quản trị viên của nó     | `whitelist.initialize(issuer)`                                                     |
| 4 | Áp dụng nó cho việc chuyển nhượng    | `token.setRestrictionModule(TRANSFER, whitelist)`                                  |
| 5 | Triển khai mô-đun lợi suất           | `new YieldBlacklistRestrictions()`                                                 |
| 6 | Đặt bạn làm quản trị viên của nó     | `yieldBlacklist.initialize(issuer)`                                                |
| 7 | Áp dụng nó cho lợi suất              | `token.setRestrictionModule(YIELD, yieldBlacklist)`                                |
| 8 | Đăng ký với factory                  | `factoryV2.registerToken(token, impl)`                                             |

Dạng script chỉ là một lệnh:

```bash
# một lần cho mỗi chuỗi (ops, không phải mỗi token) — triển khai bốn hợp đồng dùng chung
npx tsx deploy-infra.ts

# cho mỗi token — wizard, được phát lại dưới dạng script
NAME="Mineral Vault I" SYMBOL=ARCV SUPPLY=1000000 DECIMALS=6 npx tsx create-token.ts
```

Issuer (`PRIVATE_KEY`) ký mọi giao dịch và cuối cùng nắm giữ các role của token (`ArcToken.initialize` cấp cho `msg.sender` — xem bước 7). Việc đăng ký (tx 8) là thứ mở khóa `enableToken` của storefront và mọi lần nâng cấp qua factory.

> **Đừng "tối ưu" nó trở lại thành một khối monolith.** Gom các lệnh này thành một giao dịch để tiết kiệm round-trip sẽ đưa trở lại đúng lỗi tràn 62 lock mà đường đi từng phần tồn tại để tránh. Cùng giới hạn đó cũng là lý do việc phân phối yield đi từng holder một trên mỗi giao dịch (bước 8). Nếu một lệnh lỗi với `Too many accounts: N > 62`, thì một giao dịch đang chạm vào quá nhiều account — hãy tách nó ra, đừng tinh chỉnh nó.

***

## Bước 3 — Chỉ triển khai proxy từ các artifact đã khóa nguồn gốc

`registerToken` là ranh giới an ninh cho phép các triển khai từng phần vẫn an toàn. Nó sẽ chỉ chấp nhận một token mà **runtime codehash khớp với code chuẩn `ArcTokenProxy`** được nhúng sẵn vào factory tại thời điểm deploy:

```solidity
// rome-contracts/src/ArcTokenFactoryV2.sol
bytes32 private immutable CANONICAL_PROXY_CODEHASH =
    keccak256(type(ArcTokenProxy).runtimeCode);

function registerToken(address token, address implementation) external {
    if (token.codehash != CANONICAL_PROXY_CODEHASH) revert ProxyCodehashUnknown();
    // …implementation phải được factory cho phép, và msg.sender phải giữ
    //    ADMIN_ROLE của token, và token chưa từng được đăng ký trước đó.
}
```

Vì codehash đó là một **bất biến**, một proxy được tạo từ bất kỳ artifact nào khác sẽ thất bại an toàn với `ProxyCodehashUnknown`. Từ đó có hai quy tắc, và cả hai đều được CI và các quy tắc cứng trong `CLAUDE.md`:

1. **Proxy token MUST được triển khai từ `rome-contracts/out`** — không bao giờ từ `contracts/out`, không bao giờ từ một bản build khác. Đó là bản biên dịch mà codehash chuẩn của factory khóa chặt.
2. **`bytecode_hash = "none"` và `cbor_metadata = false`** trên `rome-contracts/foundry.toml` là những điểm then chốt. Khi metadata được bật, `ArcTokenProxy` runtime *được nhúng* trong factory (`type().runtimeCode`) mang một phần đuôi CBOR/IPFS khác với artifact standalone ở `out/` mà wizard deploy — nên trên-chain `registerToken` sẽ revert trong khi **mọi test Foundry trong source đều pass** (Foundry nhúng cả hai bản sao, nên nó không thấy được sự lệch nhau đó). `rome-contracts/test/ArtifactProvenance.t.sol` ghim thuộc tính này; chính lần chạy có funding đã phát hiện ra nó ban đầu.

> **Một suite trong source màu xanh không chứng minh được nguồn gốc.** Trước khi ship một image, và sau BẤT KỲ thay đổi nào về cài đặt compiler, hãy chứng minh thuộc tính này với factory *đã triển khai* (chỉ đọc, không dùng key):
>
> ```bash
> cd scripts && CHAIN_ID=<id> npx tsx verify-artifact-provenance.ts
> ```
>
> Nó hash artifact cục bộ của bạn `ArcTokenProxy` và khẳng định rằng hash đó xuất hiện nguyên văn bên trong bytecode của factory đã triển khai.

Nếu phải thay đổi cài đặt compiler, **hãy xoay factory** — triển khai một factory mới có immutable ghim codehash mới, rồi nối lại — thay vì vá thủ công kiểm tra:

```bash
cd scripts && CHAIN_ID=<id> npx tsx rotate-factory.ts
```

Việc xoay giữ lại địa chỉ cũ trong biên nhận; các token đã đăng ký theo factory cũ phải đăng ký lại theo factory mới.

***

## Bước 4 — Mở một đợt bán qua storefront dùng chung

Bán là một hành động riêng biệt với việc tạo, và nó chạy trên một `ArcTokenPurchase` storefront dùng chung duy nhất. Có ba điều phải đúng trước khi mở bán, và `ArcTokenPurchase.enableToken` kiểm tra từng điều on-chain:

```solidity
// contracts/src/ArcTokenPurchase.sol
function enableToken(address _tokenContract, uint256 _numberOfTokens, uint256 _tokenPrice)
    external onlyTokenAdmin(_tokenContract)                       // (a) bạn giữ ADMIN_ROLE của token
{
    // (b) token phải được factory biết đến — đây là thứ mà registerToken (bước 2) đã mua:
    if (ArcTokenFactory(ps.tokenFactory).getTokenImplementation(_tokenContract) == address(0))
        revert TokenNotCreatedByFactory();
    // (c) storefront phải đã nắm giữ hàng tồn để bán:
    if (ArcToken(_tokenContract).balanceOf(address(this)) < _numberOfTokens)
        revert ContractMissingRequiredTokens();
    // …giá và số lượng phải dương.
}
```

Có một yêu cầu ngầm thứ tư mà một tài sản đã gated buộc phải có: vì **mọi lần chuyển đều đi qua gate allowlist**, việc chuyển hàng tồn sang storefront chỉ thành công nếu địa chỉ storefront tự nó cũng đã nằm trong whitelist của token. Vì vậy toàn bộ trình tự mở bán là:

1. **Đưa storefront vào whitelist** trên module whitelist của token bạn (`batchAddToWhitelist([storefront])` — xem bước 5). Nếu không có điều này, lần chuyển hàng tồn ở (2) sẽ revert `TransferRestricted()` một khi đã gated.
2. **Chuyển hàng tồn** tới địa chỉ storefront (từ biên nhận infra ở `arcTokenPurchase`).
3. **`enableToken(token, amount, price)`** — người mua giờ trả bằng wUSDC và nhận RWA.

Phân chia quyền rút tiền đáng để biết trên một *storefront* dùng chung, và nó không đối xứng (`arc/roles.ts` là thẩm quyền):

| Hành động                                                  | Thẩm quyền                                | Do ai nắm giữ                      |
| ---------------------------------------------------------- | ----------------------------------------- | ---------------------------------- |
| `enableToken` / `disableToken` / `withdrawUnsoldArcTokens` | của token `ADMIN_ROLE` (`onlyTokenAdmin`) | bạn, issuer                        |
| `withdrawPurchaseTokens` (số tiền thu wUSDC)               | của storefront `DEFAULT_ADMIN_ROLE`       | bất kỳ ai đã triển khai storefront |

Trên một chuỗi tự lưu trữ, bạn là cả hai. Trên storefront dùng chung, quỹ tiền thu được là tiền của mọi issuer, nên việc rút tiền là ở cấp nền tảng — hãy thiết kế việc thanh toán của bạn xoay quanh điều đó thay vì giả định quyền kiểm soát đơn phương.

***

## Bước 5 — Cắm KYC / tuân thủ của riêng bạn vào

Đây là phần mà khách hàng đọc trước khi đồng ý, nên nó là code chứ không phải văn xuôi. **Tuân thủ được cưỡng chế bởi chính hợp đồng token** — không phải bởi một màn hình off-chain, bộ lọc sequencer, hay chính sách của sàn. Các quy tắc đi cùng token tới bất kỳ đường thực thi nào, trên cả hai lane ví. Điều chuỗi ghi lại là **kết quả** kết quả quyết định KYC của bạn, dưới dạng một boolean duy nhất:

```solidity
// contracts/src/restrictions/WhitelistRestrictions.sol — trạng thái on-chain, đầy đủ
struct WhitelistStorage {
    mapping(address => bool) isWhitelisted;   // ← một boolean cho mỗi địa chỉ. Không có PII, tuyệt đối.
    bool transfersAllowed;                    // false = gated; chỉ các địa chỉ trong whitelist mới chuyển được
    EnumerableSet.AddressSet whitelistedAddresses;
}
```

### Giao diện mà quy trình của bạn ghi vào

Quyết định approve/deny của nhà cung cấp KYC sẽ trở thành đúng một trong các lời gọi này:

```solidity
interface IWhitelistRestrictions {
    function addToWhitelist(address account) external;                  // onlyRole(MANAGER_ROLE)
    function batchAddToWhitelist(address[] calldata accounts) external; // onlyRole(MANAGER_ROLE)
    function removeFromWhitelist(address account) external;             // onlyRole(MANAGER_ROLE)
    function isWhitelisted(address account) external view returns (bool);
    function setTransfersAllowed(bool allowed) external;                // onlyRole(ADMIN_ROLE)
}
```

### Ai được phép ghi

> **Thẩm quyền mà một lần approve cần nằm `MANAGER_ROLE` trên&#x20;*****module*****&#x20;— không phải `ADMIN_ROLE` trên token.** `addToWhitelist` / `batchAddToWhitelist` / `removeFromWhitelist` đều là `onlyRole(MANAGER_ROLE)`, và role đó nằm trên `WhitelistRestrictions` instance. Xác thực `ADMIN_ROLE` trên token rồi ghi vào module là một lỗi có thật mà codebase này đã phải trả giá. Đừng đưa `WHITELIST_ADMIN_ROLE` làm bản sửa cho một lần từ chối — nó được cấp lúc initialize và **không được kiểm tra ở đâu trong suite** (`arc/roles.ts` khẳng định nó là role duy nhất không gate gì cả).

`WhitelistRestrictions.initialize(issuer)` (tx 3 của wizard) cấp cho issuer `DEFAULT_ADMIN_ROLE`, `ADMIN_ROLE`, `MANAGER_ROLE`, `WHITELIST_ADMIN_ROLE`, và `UPGRADER_ROLE` trên module đó. Vì vậy issuer tự có `MANAGER_ROLE` ngay từ đầu và cũng có thể ủy quyền nó: vì issuer nắm `DEFAULT_ADMIN_ROLE`, một `grantRole(MANAGER_ROLE, serviceAccount)` trao quyền ghi cho một backend signer.

### Một quyết định trở thành một lần ghi on-chain

Trỏ webhook của nhà cung cấp tới một signer giữ `MANAGER_ROLE`, và khi approve thì batch các địa chỉ:

```typescript
import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';

// `signer` phải giữ MANAGER_ROLE trên module whitelist của token NÀY.
const wallet = createWalletClient({ account, transport: http(chain.rpcUrl) });

// nhà cung cấp nói "approved" cho các địa chỉ này:
await wallet.writeContract({
  address: whitelistModule,                 // được resolve TỪ token qua getRestrictionModule
  abi: whitelistAbi,
  functionName: 'batchAddToWhitelist',
  args: [approvedAddresses],
});
```

Giải quyết `whitelistModule` từ chính token đó (`ArcToken.getRestrictionModule(TRANSFER_RESTRICTION_TYPE)`), không bao giờ từ một bản chiếu đã được lưu cache — việc hướng một phép ghi vào sai mô-đun là cách mà "approve on any asset" từng ghi vào allowlist của một token.

### Biến thể được ví ký (bản demo tự phục vụ)

Với một triển khai thử nghiệm không cần cấp quyền, nơi khách tự vào, hãy cấp `MANAGER_ROLE` cho một `TestApprover` (`rome-contracts/src/TestApprover.sol`) mà `module` là **bất biến**. Sau đó `approve(address)` có thể được gọi bởi bất kỳ ai, từ ví của chính họ, tự trả gas — nó gọi `addToWhitelist` chỉ khi địa chỉ đó chưa có trong danh sách:

```solidity
function approve(address account) external {
    IWhitelistRestrictions target = IWhitelistRestrictions(module);   // bất biến — một mô-đun, mãi mãi
    if (!target.isWhitelisted(account)) target.addToWhitelist(account);
    emit Approved(account, msg.sender);
}
```

Đây là "cổng đăng nhập" — nó cho khách thấy cơ chế thực sự (một phê duyệt trở thành mục allowlist trên chuỗi mà token sau đó thực thi) mà không lưu ký bất cứ thứ gì. **Không bao giờ cấp `MANAGER_ROLE` cho một `TestApprover` trên token production** — điều đó khiến allowlist của token đó trở nên không cần cấp quyền.

### Khi cổng siết lại, và chuyển nhà cung cấp

Cổng chỉ hạn chế khi tài sản đã được **được chặn cổng** (`setTransfersAllowed(false)`, `ADMIN_ROLE` trên mô-đun). Khi chưa bị chặn cổng, việc chuyển là mở — hãy xây allowlist trước, rồi mới chặn cổng. Khi đã chặn cổng, một giao dịch chuyển mà một trong hai bên không có trong danh sách sẽ hoàn tác với lỗi kiểu `TransferRestricted()` (`0xe827105e`).

> **Sau này đổi nhà cung cấp KYC không cần thay đổi gì trên chuỗi.** Mô-đun allowlist, giao diện của nó, và giá trị boolean nó lưu đều không phụ thuộc nhà cung cấp. Để đổi vendor, hãy trỏ một nguồn quyết định khác vào cùng `MANAGER_ROLE` signer — không cần triển khai lại, không cần di chuyển, không đổi trạng thái. Chuỗi không bao giờ biết vendor nào đã thực hiện lời gọi, chỉ biết kết quả.

***

## Bước 6 — Mở cùng tài sản cho ví Solana

Ba hợp đồng đó có thể truy cập từ một ví Solana **mà không cần token thứ hai**. Một người dùng thuần Solana không có key EVM ở đâu cả; thay vào đó danh tính EVM của họ là *tổng hợp*, được suy ra trên chuỗi từ signer Solana thực sự của giao dịch:

```
địa chỉ EVM tổng hợp = keccak256(solana_pubkey)[12..32]
```

Chương trình Rome EVM suy ra điều này từ chính signer (`do_tx_unsigned::derive_sender`), nên không thể bị mạo danh và không tồn tại private key secp256k1 cho nó — **chữ ký Solana là thứ duy nhất có thể điều khiển địa chỉ này**. Cách suy ra tham chiếu là `arc/materialise/solana/identity.ts` (`syntheticAddress`), tương thích từng byte với quy tắc trên chuỗi:

```typescript
export function syntheticAddress(pubkey: SolanaPubkeyInput): `0x${string}` {
  return `0x${keccak256(pubkeyBytes(pubkey)).slice(-40)}`;
}
```

**Việc một builder làm để hỗ trợ lane này** — lưu ý rằng *không có gì trong đó là thay đổi hợp đồng*:

1. **Hãy đưa người dùng Solana vào allowlist theo địa chỉ tổng hợp của họ.** Đối với lớp tuân thủ, một địa chỉ tổng hợp chỉ là một địa chỉ thông thường: dán pubkey Solana của người dùng, suy ra địa chỉ tổng hợp, và `batchAddToWhitelist([synthetic])`. Một allowlist bao trùm cả hai thế giới ví.
2. **Thiết lập PDA ký một lần, trước lời gọi đầu tiên di chuyển giá trị của họ.** PDA có thẩm quyền bên ngoài ký cho một địa chỉ tổng hợp phải tồn tại trước, và tạo nó chỉ là một `create_pda` lời gọi. Bên nào cũng có thể gửi nó: ví Solana của chính người dùng qua lane (của SDK `buildCreatePdaCall`, sau khi `isSyntheticProvisioned` trả về false), hoặc nhà phát hành từ một khóa EVM. Công cụ của issuer của Bloom hiện gửi nó như một phần của quy trình onboarding người nắm giữ; ứng dụng vẫn chưa làm việc đó trong hành động đầu tiên của người dùng, vì vậy hãy thiết lập trước lượt mua đầu tiên của người nắm giữ. Cách làm, với các lời gọi SDK, nằm trong [Ứng dụng hai lane](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/dual-lane-app.md#one-time-activate-provision-the-synthetic).
3. **Gửi qua thư viện lane, không làm thủ công.** `submitDoTxUnsigned` (`arc/materialise/solana/submit.ts`) yêu cầu proxy của chuỗi tạo giao dịch, và nó xử lý những gì một giao dịch tự dựng hay sai. Mỗi lời gọi hợp đồng trên lane là một **giao dịch Solana v1 do proxy tạo** (`rome_composeUnsignedAtomicV1`) không có bảng tra cứu địa chỉ, và thư viện lane sẽ fail closed thay vì quay về định dạng cũ hơn. Động tác nạp tiền ở bước 5 là một giao dịch Solana riêng do ứng dụng tự dựng, không phải lời gọi hợp đồng do proxy tạo.
   * **Việc khám phá account và ngân sách compute là việc của proxy.** Nó mô phỏng lời gọi, quyết định quyền ghi của từng account (của lời gọi `value` là một phần của những gì nó mô phỏng, vì vậy hãy truyền nó), và đặt ngân sách compute và heap trên giao dịch nó trả về. Không có gì trong code của bạn tự tạo chỉ thị compute-budget hay thêm fee-pool account.
   * **Hai chữ ký cho mỗi lời gọi, đều từ key Solana.** Ví trước tiên ký một thông điệp ủy quyền có thể đọc được (*Rome authorization* cộng với hash của payload EIP-1559 chưa ký; Wallet Standard `solana:signMessage`), mà proxy xác minh trước khi nó tạo lời gọi. Sau đó nó ký giao dịch v1 mà proxy trả về (`solana:signTransaction` trên wire thô). Thư viện lane nhận chúng dưới dạng `signAuthHash` và `signV1Wire`, không bao giờ gộp thành một phương thức. Hãy kiểm tra ví của bạn có ký giao dịch v1 trước khi xây dựng trên đó: Solflare hiện làm trên devnet và Phantom thì chưa.
   * **Ứng dụng tự gửi giao dịch đã ký tới một Solana RPC.** Proxy tạo giao dịch; nó không broadcast một lời gọi atomic.
   * **Xác thực trước khi yêu cầu chữ ký.** Thư viện lane phân tích thông điệp đã tạo và từ chối một thông điệp lỗi trước khi hiện lời nhắc giao dịch.
4. **Hãy thực hiện cấp quyền wrapper một lần trước khi chi wUSDC lần đầu.** wUSDC di chuyển token của người dùng với tư cách là SPL delegate của chính người đó, nên một địa chỉ tổng hợp chưa từng được cấp sẽ nhận lỗi SPL `0x4` trong lần chuyển wUSDC đầu tiên. Đọc `isEnabled(user)` trên wrapper và, khi nó là false, thêm trước `approve_spl(wrapper, 2^64-1, mint)` trên Helper precompile như chặng đầu của quy trình. Đó là một lời gọi thông thường trên cả hai lane, mỗi ví một lần. Xem [cần mỗi người dùng đã thực hiện việc này. Xem](https://docs.rome.builders/vi/cac-khai-niem-cot-loi/token-interop.md#one-time-grant-per-wallet).
5. **Nạp tiền vào trước một lời gọi sẽ tiêu nó.** Địa chỉ tổng hợp không giữ gì khi ở trạng thái nghỉ. Khi nó giữ ít wUSDC hơn số sẽ bị chi trong lời gọi, hãy chuyển phần thiếu từ tài khoản token USDC của chính ví trước (tạo idempotent tài khoản token của địa chỉ tổng hợp, rồi đến chỉ thị activate-token-account của chương trình Rome, lệnh này chuyển token mà không chạy EVM). Đó là một giao dịch Solana được ký bằng một lần nhắc, và sẽ bị bỏ qua khi địa chỉ tổng hợp đã có đủ.
6. **Chỉ relay những gì bộ tạo atomic từ chối.** Một lời gọi không vừa trong một giao dịch Solana (khoảng 1,4 triệu compute unit, 64 account, 4 KB) sẽ bị bộ tạo từ chối với *external atomic plan requires iterative composition*. Chính khi bị từ chối như vậy, và không bao giờ trước đó, hãy gọi `rome_relayUnsignedV1` với cùng chữ ký ủy quyền: proxy tạo và gửi nó, trả phí Solana, và phản hồi bằng một hash giao dịch EVM (không phải chữ ký Solana). Địa chỉ tổng hợp trả gas native của chuỗi bằng wei, nên khi số dư của nó thiếu `gasLimit x maxFeePerGas`, hãy nạp thêm trước bằng `rome_composeExternalDepositV1` (một giao dịch v1 do ví ký; số tiền phải là bội số của 10^12 wei), trên thực tế mỗi ví một lần. Bất kỳ lỗi nào khác, như revert, lỗi mạng hoặc bị từ chối chữ ký, sẽ được ném lại, không relay. Chi tiết nằm trong [Các lệnh được chuyển tiếp và các lệnh dài](https://docs.rome.builders/vi/huong-dan-cho-nha-phat-trien/call-evm-from-solana.md#relayed-calls-and-long-calls).

Người dùng là **người trả phí** và trả lamport (SOL) từ ví Solana của họ cho một lời gọi trực tiếp; địa chỉ tổng hợp họ kiểm soát giữ tài sản và không bao giờ giữ SOL. Sau mỗi lần gửi trên lane, hãy kiểm tra nonce EVM trước lần tiếp theo — bộ indexer trễ xác nhận Solana một chút, nếu không lời gọi tiếp theo sẽ được dựng trên một nonce mà chuỗi đã dùng rồi.

> **Atomic trước, relay khi bị từ chối.** Mặc định cho mọi lời gọi là một giao dịch EVM được thực thi bên trong một giao dịch Solana, do ví của người dùng ký. Relay là ngoại lệ cho lời gọi không vừa, không phải một đường đi thứ hai để chọn theo sở thích: một lời gọi trực tiếp là hai lần nhắc, một lời gọi relay là một, và lời gọi relay được trả bằng gas Rome thay vì lamport. Một hành trình nhiều bước (approve, rồi buy) là nhiều lời gọi trọn vẹn, mỗi lời gọi là giao dịch riêng của nó, không phải một lần thực thi bị tách qua nhiều giao dịch.

**Vì sao RWA không thể rò rỉ ra ngoài chu vi.** Tài sản là cư trú trong trạng thái EVM — số dư của nó là dữ liệu lưu trữ bên trong các account của chương trình Rome EVM. Không có **SPL mint nào** của nó và không có gì thuần Solana để di chuyển; các primitive di chuyển tài sản của lane hoạt động trên các SPL token account, mà số dư lưu trữ EVM thì không có. Mọi chuyển động mà chữ ký Solana có thể thể hiện đều là một lời gọi vào hợp đồng token, hợp đồng này chạy cổng allowlist — bộ kiểm thử có cấp vốn khẳng định rằng một lần chuyển tới địa chỉ không nằm trong whitelist sẽ hoàn tác giống hệt nhau dù được ký bởi key EVM hay key Solana. Phần tiền mặt (wUSDC) là ngoại lệ có chủ ý: nó được SPL hậu thuẫn và *không* được quét ra tài khoản token của chính người dùng.

***

## Bước 7 — Biết ai nắm quyền sau khi triển khai

`ArcToken.initialize` chạy từ constructor của proxy (tx 1) và cấp vai trò cho `msg.sender` — người điều khiển wizard, tức là issuer. Nó cấp **năm** vai trò một cách rõ ràng:

```solidity
_grantRole(DEFAULT_ADMIN_ROLE, msg.sender);
_grantRole(ADMIN_ROLE, msg.sender);
_grantRole(MANAGER_ROLE, msg.sender);
_grantRole(YIELD_MANAGER_ROLE, msg.sender);
_grantRole(YIELD_DISTRIBUTOR_ROLE, msg.sender);
```

Hai hệ quả mà builder không được bỏ sót:

* **`MINTER_ROLE`, `BURNER_ROLE`, và `UPGRADER_ROLE` KHÔNG được cấp tại initialize.** Nguồn cung ban đầu được mint bên trong `khởi tạo` (một `_mint`, không cần vai trò), nhưng một *sau này* `mint` hoặc `burn` đòi hỏi issuer trước hết phải tự cấp cho mình vai trò đó. Họ có thể làm vậy, vì họ nắm giữ `DEFAULT_ADMIN_ROLE` (admin của mọi vai trò — không có gì gọi `_setRoleAdmin`, nên `DEFAULT_ADMIN_ROLE` quản trị tất cả chúng). Nhưng đó là một bước bổ sung có chủ ý, không phải một quyền lực mặc định.
* **`UPGRADER_ROLE` không bao giờ được cấp cho factory.** Nâng cấp qua trung gian factory (`ArcTokenFactoryV2.upgradeToken`) yêu cầu **chính factory** nắm giữ `UPGRADER_ROLE` trên token — tự cấp cho chính bạn thì không có tác dụng. Việc cấp đó là cánh cửa một chiều mà factory không thể đảo ngược, nên là tùy chọn: nếu bạn muốn nâng cấp qua factory, `grantRole(UPGRADER_ROLE, factory)` một cách rõ ràng; nếu không, issuer sẽ nâng cấp token trực tiếp.

Mô hình đầy đủ 21 thẩm quyền (11 tên vai trò trải rộng trên sáu hợp đồng — cùng một tên là một thẩm quyền khác nhau trên mỗi hợp đồng) được mã hóa trong `arc/roles.ts`. Hỏi `rolesRequiredFor(contract, functionName)` thay vì đọc hợp đồng của chính một vai trò, vì bốn hàm storefront và cả hai hàm factory đều bị chặn bởi một thẩm quyền nằm trên một *khác* .

***

## Bước 8 — Phân phối lợi tức

Token trả lợi tức bằng wUSDC (cố định ở mức `khởi tạo`, có thể thay đổi qua `setYieldToken` dưới `YIELD_MANAGER_ROLE`). Việc phân phối đi qua tập người nắm giữ:

```solidity
function distributeYieldWithLimit(uint256 totalAmount, uint256 startIndex, uint256 maxHolders)
    external onlyRole(YIELD_DISTRIBUTOR_ROLE) nonReentrant
    returns (uint256 nextIndex, uint256 totalHolders, uint256 amountDistributed);
```

Những cơ chế quan trọng để vận hành đúng:

* **Toàn bộ `totalAmount` chỉ được rút từ người gọi ở `startIndex == 0` cửa sổ** (`safeTransferFrom(msg.sender, this, totalAmount)`). Hãy approve tổng số đó cho token trước cửa sổ đầu tiên; các cửa sổ sau sẽ chi trả từ số dư đã có sẵn.
* **`nextIndex` quay vòng về `0` khi lượt duyệt hoàn tất.** Lặp `distributeYieldWithLimit(total, nextIndex, …)` cho đến khi `nextIndex` quay lại `0`.
* **Phần của những holder bị hạn chế nhận yield vẫn ở lại trong hợp đồng token** — họ bị bỏ qua, không được phân phối lại.

> **Trên Rome, mức trần thực tế là `maxHolders = 1` mỗi giao dịch** — cùng giới hạn 62 account từ bước 2 — nên yield được duyệt một holder mỗi giao dịch (đo khoảng 318 K gas cho mỗi holder). Mỗi holder trong whitelist, dù EVM hay thuần Solana, đều nhận theo tỷ lệ; script tham chiếu là `measure-yield-batch.ts` và bước yield của smoke có cấp vốn sẽ kiểm tra nó từ đầu đến cuối.

```bash
# Dạng tham chiếu trong USAGE.md: duyệt một holder mỗi tx cho đến khi nextIndex quay về 0
distributeYieldWithLimit(total, offset, 1)
```

***

## Bước 9 — Xác minh những gì bạn đã triển khai

Không có gì tự động nộp source ở bất kỳ đâu trong Rome, nên việc xác minh là một bước bạn phải tự chạy. Sau bất kỳ lần triển khai nào — hạ tầng hay token mới — hãy chạy trình xác minh chỉ đọc, không cần key, idempotent (các hợp đồng đã được xác minh sẽ bị bỏ qua, nên chạy lại sau khi phát hành token chỉ xác minh những hợp đồng mới):

```bash
cd scripts && CHAIN_ID=<id> npx tsx verify-deployments.ts
```

Nó mong đợi **ba** các hợp đồng cho mỗi token (proxy + cả hai module) cộng với hạ tầng, và báo cáo những gì nó không thể xác minh thay vì làm thất bại việc triển khai. Làm thủ công một lần như vậy đã bỏ sót bảy hợp đồng.

Đăng ký tài sản vào registry của Rome coi việc xác minh là một **cổng**, không phải trang trí (`register-asset.ts`): một token có được bản ghi `apps/arc/<chain>.json` — mang theo `standard: arc-permissioned-erc20` và một `transferRestriction` đặt tên cho cổng allowlist của nó — chỉ khi cả ba hợp đồng của nó đã được xác minh trên Sourcify. Bản ghi đó đọc dữ kiện từ chuỗi (một token triển khai bằng wizard không có biên nhận đã commit) và chỉ ghi một checkout registry cục bộ; việc chốt PR là việc của con người.

```bash
CHAIN_ID=200010 npx tsx register-asset.ts <tokenAddress>        # xác minh + chuẩn bị bản ghi registry
CHAIN_ID=200010 DRY=1 npx tsx register-asset.ts <tokenAddress>  # xem trước chỉ đọc
```

Để có bằng chứng end-to-end cho toàn bộ vòng lặp — tạo, whitelist, chặn cổng, bán trên cả hai lane, phân phối yield — hãy chạy smoke có cấp vốn trên bất kỳ chain nào:

```bash
PRIVATE_KEY=… CHAIN_ID=… SOLANA_KEYPAIR=… npx tsx smoke.ts
```

***

## Bước 10 — Biết điều gì ở ngoài chuỗi

Mô hình tin cậy được cố ý làm cho minh bạch, và builder nên trình bày nó theo cách tương tự với chính người dùng của họ:

* **Cờ allowlist là quyết định ngoài chuỗi của bạn.** KYC/AML diễn ra trong quy trình của bạn — vendor của bạn, quy tắc của bạn. Chuỗi chỉ ghi nhận và thực thi *kết quả*, `isWhitelisted(addr)`.
* **Trạng thái duy nhất trên chuỗi là một boolean cho mỗi địa chỉ.** Không có PII, không có tài liệu, không có tuyên bố danh tính, không có xác nhận trên chuỗi, không có bằng chứng mật mã về việc một địa chỉ thuộc về ai. Đây là mô hình của Arc như được dùng trên Plume; nó đánh đổi những cơ chế chuyển nặng nề hơn của một chuẩn danh tính on-chain (ví dụ ERC-3643) để lấy cơ chế nhẹ hơn và niềm tin do issuer nắm giữ.
* **Khôi phục là quyền của issuer, không phải cửa thoát.** Một ví bị mất — EVM hay Solana — được khôi phục bằng cách đưa một địa chỉ thay thế vào whitelist và, nếu cần, dùng mint/burn/upgrade theo quy trình pháp lý của bạn (Arc không có primitive forced-transfer tích hợp sẵn). Vì vậy việc lưu giữ key của issuer là một phần của tư thế tuân thủ.
* **Không có relayer riêng của Bloom, không có bề mặt lưu ký.** Người dùng tự giữ gas của họ trên cả hai lane. Một dịch vụ fee-payer do ứng dụng vận hành sẽ đồng nghĩa với việc giữ key — một bề mặt mà sản phẩm RWA không nên thêm vào. Relay duy nhất trên lane Solana là của proxy chuỗi, dành cho một lời gọi quá lớn cho một giao dịch, và người dùng vẫn ủy quyền nó bằng chữ ký của chính họ và trả bằng gas Rome của chính họ.

***

## Tham chiếu: bộ công cụ

Mọi script chạy từ `scripts/` thư mục của bộ công cụ, với `PRIVATE_KEY`, `CHAIN_ID`, và `REGISTRY_ROOT` được export.

| Script                          | Nó làm gì                                                                         |
| ------------------------------- | --------------------------------------------------------------------------------- |
| `deploy-infra.ts`               | Mỗi chain một lần: bốn hợp đồng dùng chung, cấu hình cho wUSDC.                   |
| `create-token.ts`               | Wizard theo từng phần — tám giao dịch, một token.                                 |
| `rotate-factory.ts`             | Triển khai một factory mới sau khi thay đổi compiler/artifact; đấu nối lại.       |
| `verify-artifact-provenance.ts` | Chứng minh artifact proxy của bạn được factory đã triển khai chấp nhận (chỉ đọc). |
| `verify-deployments.ts`         | Xác minh cả ba hợp đồng cho mỗi token + hạ tầng trên Sourcify (chỉ đọc).          |
| `register-asset.ts`             | Xác minh qua cổng, rồi chuẩn bị bản ghi tuân thủ của registry.                    |
| `measure-yield-batch.ts`        | Đo lại trần yield mỗi tx trên một chain.                                          |
| `smoke.ts`                      | Bộ kiểm thử end-to-end có cấp vốn trên cả hai lane.                               |
| `sweep-synthetic-native.ts`     | Thu hồi gas native từ một tài khoản tổng hợp (vệ sinh test).                      |

Bối cảnh sâu hơn nằm cùng với hướng dẫn này: `docs/ARCHITECTURE.md` (mô hình ứng dụng phân lớp), `docs/LANES.md` (hai lane và lưu ký), `docs/COMPLIANCE.md` (mô hình tin cậy), và `docs/USAGE.md` (sổ tay vận hành).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.rome.builders/vi/ung-dung-tren-rome/bloom/building.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
