> 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/id/aplikasi-di-rome/bloom/building.md).

# Membangun di Bloom

Panduan ini menjawab satu pertanyaan: **bagaimana seorang builder melakukannya sendiri?** Ambil kontrak aset dunia nyata Solidity, jalankan di chain Rome sebagai token berizin, bukalah untuk dompet Solana maupun dompet EVM tanpa token kedua, dan sambungkan keputusan KYC/kepatuhan Anda sendiri.

Pembacanya adalah developer yang mengevaluasi atau mengadopsi pendekatan ini. Bloom adalah contoh kerja yang digunakan sepanjang panduan ini — aset live-nya **ARCV ("Mineral Vault I")** di Hadrian (`200010`) adalah contoh nyata dari setiap langkah di bawah, dan bukti deploy-nya (`deployments/200010.tokens/ARCV.json`) mencatat tiga kontrak dan delapan transaksi persis yang dihasilkan metode ini.

Tidak ada di sini yang memodifikasi kontrak aset. Bloom menjalankan framework Arc dari Plume **tanpa modifikasi** (pohon vendored di `contracts/`, identik byte dengan `plumenetwork/contracts` pada pin di `NOTICE`); satu-satunya kontrak di sisi Rome adalah `ArcTokenFactoryV2`, yang menambahkan satu fungsi. Pekerjaannya ada di *bagaimana* Anda yang melakukan deploy dan *bagaimana* Anda yang mengendalikan kontrak — bukan mengubahnya.

> **Metodenya, sekilas.** Token berizin adalah **tiga** kontrak yang dideploy. Ia dideploy **secara bertahap** — satu kontrak per transaksi — karena pemanggilan factory dalam satu transaksi melebihi batas akun per transaksi di Rome. Proksinya harus berasal dari **artefak yang dikunci asal-usulnya** atau pendaftaran on-chain gagal tertutup. Kepatuhan adalah satu **boolean per alamat**, ditulis oleh siapa pun yang diotorisasi proses KYC Anda. Dan deployment yang sama dapat diakses dari dompet Solana melalui **pengirim sintetis** yang diturunkan on-chain — tanpa token kedua, tanpa allowlist kedua.

## Prasyarat

> **Sebelum Anda mulai.** Tooling penerbit yang digunakan panduan ini belum dipublikasikan. Itu mencakup skrip (`deploy-infra.ts`, `create-token.ts` dan lainnya), `contracts/` dan `rome-contracts/` pohon, dan bukti deploy yang disebutkannya. Penerbit mendapatkan tooling ini dengan onboarding ke Rome. Sampai saat itu, bacalah panduan ini sebagai deskripsi metode dan apa yang dilakukan setiap skrip.

Tooling referensi berada di sebuah `scripts/` direktori (disediakan saat onboarding; instal dependensinya dengan `npm install`). Setiap perintah mengambil fakta chain dari registry, bukan meng-hardcode-nya, jadi mengalihkan target ke chain Rome lain adalah perubahan environment, bukan perubahan kode:

```bash
export PRIVATE_KEY=…       # kunci deployer/penerbit yang didanai di chain target
export CHAIN_ID=200010     # memilih chain
export REGISTRY_ROOT=…     # checkout dari registry chain Rome
# Alur jalur Solana juga membutuhkan:
export SOLANA_KEYPAIR=…    # path ke JSON keypair Solana yang didanai (pembayar biaya)
```

Gas di chain Rome didenominasikan dalam USDC; seluruh urutan deploy biayanya sekitar 10–15 unit native di devnet. Kunci hanya berasal dari environment — jangan pernah dari repo. Build kontrak sekali sebelum deploy, karena artefak **harus** berasal dari `rome-contracts/out` (lihat langkah 3):

```bash
cd contracts       && forge build --via-ir     # rangkaian Arc yang di-vendor
cd rome-contracts  && forge build --via-ir     # ArcTokenFactoryV2 + proksi kanonik
```

***

## Langkah 1 — Pahami apa itu token berizin *adalah* di sini

Token Bloom berizin bukan satu kontrak. Ia adalah **tiga kontrak yang dideploy**, ditambah empat kontrak bersama yang dideploy ops satu kali per chain dan digunakan ulang oleh setiap penerbit.

**Tiga kontrak per token** — satu aset memiliki tepat ini:

| Kontrak                      | Sumber                                                      | Apa itu                                                                                                                      |
| ---------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `ArcTokenProxy`              | `contracts/src/proxy/ArcTokenProxy.sol`                     | Token itu sendiri — proksi UUPS yang mengarah ke `ArcToken` implementasi bersama. Saldo, pemegang, dan peran berada di sini. |
| `WhitelistRestrictions`      | `contracts/src/restrictions/WhitelistRestrictions.sol`      | Modul allowlist. Satu boolean per alamat; ditegakkan pada setiap transfer saat aset digate.                                  |
| `YieldBlacklistRestrictions` | `contracts/src/restrictions/YieldBlacklistRestrictions.sol` | Modul yield. Mengecualikan alamat dari distribusi yield tanpa menyentuh kepemilikannya.                                      |

**Empat kontrak bersama, satu per chain** (dideploy oleh `deploy-infra.ts`):

| Kontrak                   | Peran                                                                                   |
| ------------------------- | --------------------------------------------------------------------------------------- |
| `RestrictionsRouter`      | Registry jenis modul — pengkabelan chain, disetel sekali oleh ops.                      |
| `ArcTokenFactoryV2`       | Registrasi + codehash proksi kanonik (langkah 2–3).                                     |
| `ArcToken` (implementasi) | Logika aset bersama yang dapat digunakan ulang yang menjadi target proksi setiap token. |
| `ArcTokenPurchase`        | Satu storefront, dibagi bersama oleh setiap token dan penerbit (langkah 4).             |
| wUSDC                     | Bagian kas — mata uang yield dan mata uang jual-beli.                                   |

Pembatasan transfer dan pembatasan yield adalah **modul yang sengaja dipisahkan**: seorang pemegang dapat dilarang menerima pendapatan sambil tetap menyimpan aset, dan begitulah sanksi serta perintah pengadilan sebenarnya bekerja.

Fakta "tiga kontrak" ini sangat penting untuk verifikasi. `verify-deployments.ts` dan `register-asset.ts` keduanya mengharapkan token terpetakan ke tiga kontrak yang dideploy — verifikasi manual satu token sekali pernah melewatkan tujuh di antaranya di satu chain (semua modul yield dan tiga modul whitelist).

Siklus hidupnya memiliki tiga fase dan satu pintu satu arah:

```
draft     proksi aktif, belum ada modul terhubung — tidak ada yang menggate transfer
  ↓
ungated   modul terhubung, transfersAllowed = true   (WhitelistRestrictions.initialize menetapkan ini)
  ↓  cetak supply, bangun allowlist               [dapat dibalik]
gated     setTransfersAllowed(false)                [PINTU SATU ARAH — supply menjadi final]
```

Penggatingan bersifat satu arah untuk supply karena mint dan burn melewati `address(0)` sebagai counterparty, dan `address(0)` tidak pernah bisa dimasukkan ke allowlist — jadi setelah digate, tidak ada supply baru yang dapat dicetak. Itulah jaminan yang diberikan aset berizin kepada para pemegangnya.

***

## Langkah 2 — Deploy secara bertahap, jangan pernah sebagai satu transaksi

Arc menyediakan proses sekali jalan `createToken` yang mendeploy proksi dan kedua modul sekaligus serta menghubungkannya dalam satu panggilan. **Di Rome Anda tidak bisa menggunakannya.** Transaksi itu membutuhkan **77 lock akun Solana**, dan batas per-transaksi Rome adalah **62 lock**. Itu tidak akan pernah muat — tidak dengan tuning, tidak dengan pass optimizer.

Jadi deploy-nya adalah **secara bertahap**: setiap kontrak dalam transaksi terpisah, dan token memperoleh status setara factory melalui `ArcTokenFactoryV2.registerToken` sebagai ganti yang monolitik `createToken`. Inilah wizard pembuatan, dan inilah yang dilakukan konsol penerbit langkah demi langkah:

![wizard pembuatan](https://320084446-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)

Implementasi referensinya adalah `arc/plan/create.ts` (`createSequence()`), yang dirender aplikasi sebagai enam kartu (`bloom/lib/createCards.ts`) di atas **delapan transaksi**, dalam urutan persis yang dipaksakan kontrak:

| # | Transaksi                              | Panggilan kontrak                                                                 |
| - | -------------------------------------- | --------------------------------------------------------------------------------- |
| 1 | Deploy aset                            | `new ArcTokenProxy(impl, initData)` di mana `initData = ArcToken.initialize(...)` |
| 2 | Sebarkan modul daftar izin             | `new WhitelistRestrictions()`                                                     |
| 3 | Tetapkan Anda sebagai administratornya | `whitelist.initialize(issuer)`                                                    |
| 4 | Terapkan pada transfer                 | `token.setRestrictionModule(TRANSFER, whitelist)`                                 |
| 5 | Sebarkan modul hasil                   | `new YieldBlacklistRestrictions()`                                                |
| 6 | Tetapkan Anda sebagai administratornya | `yieldBlacklist.initialize(issuer)`                                               |
| 7 | Terapkan pada hasil                    | `token.setRestrictionModule(YIELD, yieldBlacklist)`                               |
| 8 | Daftarkan ke pabrik                    | `factoryV2.registerToken(token, impl)`                                            |

Bentuk skripnya adalah satu perintah:

```bash
# satu kali per chain (ops, bukan per token) — mendeploy empat kontrak bersama
npx tsx deploy-infra.ts

# per token — wizard yang diputar ulang sebagai skrip
NAME="Mineral Vault I" SYMBOL=ARCV SUPPLY=1000000 DECIMALS=6 npx tsx create-token.ts
```

Penerbit (`PRIVATE_KEY`) menandatangani setiap transaksi dan akhirnya memegang peran token (`ArcToken.initialize` pemberian kepada `msg.sender` — lihat langkah 7). Registrasi (tx 8) adalah yang membuka `enableToken` dan setiap upgrade yang dimediasi factory.

> **Jangan "optimalkan" ini kembali menjadi monolit.** Menggabungkan panggilan-panggilan ini ke dalam satu transaksi untuk menghemat round-trip justru memunculkan kembali overflow 62 lock yang ingin dihindari oleh jalur bertahap. Batas yang sama juga menjadi alasan distribusi yield berjalan satu pemegang per transaksi (langkah 8). Jika panggilan gagal dengan `Terlalu banyak akun: N > 62`, satu transaksi menyentuh terlalu banyak akun — pecah, jangan tuning.

***

## Langkah 3 — Deploy proksi hanya dari artefak yang dikunci asal-usulnya

`registerToken` adalah batas keamanan yang membuat deploy bertahap menjadi aman. Ia hanya akan menerima token yang **runtime codehash-nya cocok dengan kanonik `ArcTokenProxy`** yang ditanamkan ke factory saat 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();
    // …implementasi harus ada dalam whitelist factory, dan msg.sender harus memegang
    //    ADMIN_ROLE token, dan token belum boleh terdaftar.
}
```

Karena codehash itu bersifat **immutable**, proksi yang dibangun dari artefak lain apa pun akan gagal tertutup dengan `ProxyCodehashUnknown`. Berikut dua aturan, dan keduanya ditegakkan oleh CI serta aturan ketat di `CLAUDE.md`:

1. **Proksi token HARUS dideploy dari `rome-contracts/out`** — jangan pernah dari `contracts/out`, jangan pernah dari build berbeda. Itulah kompilasi yang dipatok oleh codehash kanonik factory.
2. **`bytecode_hash = "none"` dan `cbor_metadata = false`** di `rome-contracts/foundry.toml` sangat penting. Dengan metadata diaktifkan,  `ArcTokenProxy` runtime *yang ditanamkan* di dalam factory (`type().runtimeCode`) membawa ekor CBOR/IPFS yang berbeda dibandingkan `out/` artefak yang digunakan wizard untuk deploy — jadi on-chain `registerToken` akan revert sementara **semua tes Foundry in-source lulus** (Foundry menyematkan kedua salinan, jadi ia tidak bisa melihat ketidakcocokan itu). `rome-contracts/test/ArtifactProvenance.t.sol` mengunci properti ini; run yang didanai itulah yang mula-mula menangkapnya.

> **Satu suite in-source yang hijau tidak membuktikan provenance.** Sebelum mengirim image, dan setelah PERUBAHAN setting compiler apa pun, buktikan properti itu terhadap *yang dideploy* factory (hanya baca, tanpa kunci):
>
> ```bash
> cd scripts && CHAIN_ID=<id> npx tsx verify-artifact-provenance.ts
> ```
>
> Ia menghitung hash artefak lokal Anda `ArcTokenProxy` dan memastikan hash itu muncul persis di dalam bytecode factory yang dideploy.

Jika setelan compiler memang harus berubah, **rotasikan factory** — deploy yang baru dengan immutable yang mematok codehash baru, lalu sambungkan ulang — alih-alih menambal cek secara manual:

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

Rotasi mempertahankan alamat lama di receipt; token yang terdaftar ke factory lama harus mendaftar ulang ke yang baru.

***

## Langkah 4 — Buka penjualan melalui storefront bersama

Menjual adalah tindakan terpisah dari membuat, dan dijalankan pada satu-satunya `ArcTokenPurchase` storefront bersama. Ada tiga hal yang harus benar sebelum penjualan dibuka, dan `ArcTokenPurchase.enableToken` memeriksa masing-masing on-chain:

```solidity
// contracts/src/ArcTokenPurchase.sol
function enableToken(address _tokenContract, uint256 _numberOfTokens, uint256 _tokenPrice)
    external onlyTokenAdmin(_tokenContract)                       // (a) Anda memegang ADMIN_ROLE token
{
    // (b) token harus dikenal oleh factory — inilah yang didapat dari registerToken (langkah 2):
    if (ArcTokenFactory(ps.tokenFactory).getTokenImplementation(_tokenContract) == address(0))
        revert TokenNotCreatedByFactory();
    // (c) storefront harus sudah memegang inventaris penjualan:
    if (ArcToken(_tokenContract).balanceOf(address(this)) < _numberOfTokens)
        revert ContractMissingRequiredTokens();
    // …harga dan jumlah harus positif.
}
```

Ada persyaratan keempat yang implisit dan dipaksakan oleh aset yang digate: karena **setiap transfer melewati gate allowlist**, memindahkan inventaris ke storefront hanya berhasil jika alamat storefront itu sendiri ada di whitelist token Anda. Jadi urutan lengkap membuka penjualan adalah:

1. **Masukkan storefront ke whitelist** pada modul whitelist token Anda (`batchAddToWhitelist([storefront])` — lihat langkah 5). Tanpa ini, transfer inventaris pada (2) akan revert `TransferRestricted()` setelah digate.
2. **Transfer inventaris** ke alamat storefront (dari receipt infra `arcTokenPurchase`).
3. **`enableToken(token, amount, price)`** — pembeli sekarang membayar wUSDC dan menerima RWA.

Pembagian penarikan layak diketahui pada *bersama* storefront, dan ini tidak simetris (`arc/roles.ts` adalah otoritasnya):

| Tindakan                                                   | Otoritas                              | Dipegang oleh                       |
| ---------------------------------------------------------- | ------------------------------------- | ----------------------------------- |
| `enableToken` / `disableToken` / `withdrawUnsoldArcTokens` | milik `ADMIN_ROLE` (`onlyTokenAdmin`) | Anda, penerbitnya                   |
| `withdrawPurchaseTokens` (hasil wUSDC)                     | milik storefront `DEFAULT_ADMIN_ROLE` | siapa pun yang mendeploy storefront |

Pada chain yang di-host sendiri, Anda adalah keduanya. Pada storefront bersama, pool hasil adalah pendapatan semua penerbit, jadi penarikannya berada di level platform — rancang penyelesaiannya berdasarkan itu, bukan dengan mengasumsikan kontrol sepihak.

***

## Langkah 5 — Sambungkan KYC / kepatuhan Anda sendiri

Ini adalah bagian yang dibaca pelanggan sebelum setuju, jadi ini adalah kode, bukan prosa. **Kepatuhan ditegakkan oleh kontrak token itu sendiri** — bukan oleh penyaringan off-chain, filter sequencer, atau kebijakan venue. Aturannya ikut bersama token ke jalur eksekusi apa pun, pada kedua jalur dompet. Yang dicatat chain adalah **hasilnya** dari keputusan KYC Anda, sebagai satu boolean:

```solidity
// contracts/src/restrictions/WhitelistRestrictions.sol — state on-chain, lengkap
struct WhitelistStorage {
    mapping(address => bool) isWhitelisted;   // ← satu boolean per alamat. Tidak ada PII, sama sekali.
    bool transfersAllowed;                    // false = digate; hanya alamat yang ada di whitelist yang dapat transfer
    EnumerableSet.AddressSet whitelistedAddresses;
}
```

### Antarmuka yang ditulis oleh proses Anda

Keputusan approve/deny dari vendor KYC Anda menjadi tepat salah satu dari panggilan ini:

```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)
}
```

### Siapa yang boleh menulis

> **Otoritas yang dibutuhkan sebuah persetujuan adalah `MANAGER_ROLE` pada&#x20;*****modul*****&#x20;— bukan `ADMIN_ROLE` pada token.** `addToWhitelist` / `batchAddToWhitelist` / `removeFromWhitelist` semuanya `onlyRole(MANAGER_ROLE)`, dan peran itu berada pada `WhitelistRestrictions` instance. Mengautentikasi `ADMIN_ROLE` pada token lalu menulis ke modul adalah bug nyata yang sudah pernah dibayar oleh codebase ini. Jangan menawarkan `WHITELIST_ADMIN_ROLE` sebagai perbaikan untuk penolakan — ia diberikan saat initialize dan **tidak dicek di mana pun dalam suite** (`arc/roles.ts` menegaskan bahwa itu adalah satu-satunya peran yang tidak menggate apa pun).

`WhitelistRestrictions.initialize(issuer)` (tx 3 dari wizard) memberikan penerbit `DEFAULT_ADMIN_ROLE`, `ADMIN_ROLE`, `MANAGER_ROLE`, `WHITELIST_ADMIN_ROLE`, dan `UPGRADER_ROLE` pada modul itu. Jadi penerbit memegang `MANAGER_ROLE` secara bawaan dan juga dapat mendelegasikannya: karena penerbit memegang `DEFAULT_ADMIN_ROLE`, sebuah `grantRole(MANAGER_ROLE, serviceAccount)` menyerahkan penulisan ke penandatangan backend.

### Keputusan menjadi penulisan on-chain

Arahkan webhook vendor Anda ke signer yang memegang `MANAGER_ROLE`, dan saat approve, batch alamat-alamatnya:

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

// `signer` harus memegang MANAGER_ROLE pada modul whitelist token INI.
const wallet = createWalletClient({ account, transport: http(chain.rpcUrl) });

// vendor mengatakan "approved" untuk alamat-alamat ini:
await wallet.writeContract({
  address: whitelistModule,                 // diselesaikan DARI token melalui getRestrictionModule
  abi: whitelistAbi,
  functionName: 'batchAddToWhitelist',
  args: [approvedAddresses],
});
```

Selesaikan `whitelistModule` dari token itu sendiri (`ArcToken.getRestrictionModule(TRANSFER_RESTRICTION_TYPE)`), jangan pernah dari proyeksi cache — mengarahkan penulisan ke modul yang salah adalah bagaimana "approve pada aset apa pun" pernah menulis ke allowlist satu token.

### Varian yang ditandatangani dompet (demo swalayanan)

Untuk deployment uji tanpa izin di mana pengunjung mendaftar sendiri, berikan `MANAGER_ROLE` kepada sebuah `TestApprover` (`rome-contracts/src/TestApprover.sol`) yang `modul` adalah **immutable**. Lalu `approve(address)` dapat dipanggil oleh siapa saja, dari dompet mereka sendiri, dengan membayar gas mereka sendiri — ini memanggil `addToWhitelist` hanya jika alamat tersebut belum terdaftar:

```solidity
function approve(address account) external {
    IWhitelistRestrictions target = IWhitelistRestrictions(module);   // tidak dapat diubah — satu modul, selamanya
    if (!target.isWhitelisted(account)) target.addToWhitelist(account);
    emit Approved(account, msg.sender);
}
```

Ini adalah "gerbang masuk" — ini menunjukkan kepada pengunjung mekanisme sebenarnya (sebuah persetujuan menjadi entri allowlist on-chain yang kemudian ditegakkan token) tanpa menguasai apa pun. **Jangan pernah memberikan `MANAGER_ROLE` kepada sebuah `TestApprover` pada token produksi** — ini membuat allowlist token tersebut tanpa izin.

### Saat gerbang aktif, dan mengganti penyedia

Gerbang hanya membatasi setelah aset **digate** (`setTransfersAllowed(false)`, `ADMIN_ROLE` pada modul). Selama belum digate, transfer terbuka — bangun allowlist Anda dulu, lalu gate. Setelah digate, transfer di mana salah satu pihak tidak ada di daftar akan revert dengan error bertipe `TransferRestricted()` (`0xe827105e`).

> **Mengganti penyedia KYC nanti tidak memerlukan perubahan on-chain.** Modul allowlist, antarmukanya, dan boolean yang disimpannya bersifat agnostik terhadap penyedia. Untuk mengganti vendor, arahkan sumber keputusan yang berbeda ke `MANAGER_ROLE` penandatangan yang sama — tanpa redeploy, tanpa migrasi, tanpa perubahan state. Chain tidak pernah tahu vendor mana yang melakukan panggilan, hanya hasilnya.

***

## Langkah 6 — Buka aset yang sama untuk dompet Solana

Tiga kontrak yang sama dapat diakses dari dompet Solana **tanpa token kedua**. Pengguna native Solana tidak memiliki kunci EVM di mana pun; sebagai gantinya identitas EVM mereka adalah *sintetis*, diturunkan on-chain dari penandatangan Solana aktual pada transaksi:

```
synthetic EVM address = keccak256(solana_pubkey)[12..32]
```

Program Rome EVM menurunkan ini dari penandatangan itu sendiri (`do_tx_unsigned::derive_sender`), jadi tidak bisa dipalsukan dan tidak ada kunci privat secp256k1 untuknya — **tanda tangan Solana adalah satu-satunya hal yang dapat menggerakkan alamat ini**. Derivasi referensinya adalah `arc/materialise/solana/identity.ts` (`syntheticAddress`), kompatibel byte dengan aturan on-chain:

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

**Apa yang dilakukan builder untuk mendukung lane** — perhatikan bahwa *tidak satu pun darinya merupakan perubahan kontrak*:

1. **Masukkan pengguna Solana ke allowlist berdasarkan alamat sintetis mereka.** Bagi lapisan kepatuhan, alamat sintetis adalah alamat biasa: tempel pubkey Solana pengguna, turunkan alamat sintetisnya, dan `batchAddToWhitelist([synthetic])`. Satu allowlist mencakup kedua dunia dompet.
2. **Siapkan PDA penandatangan satu kali, sebelum panggilan pertama mereka yang memindahkan nilai.** PDA otoritas eksternal yang menandatangani untuk sebuah sintetis harus ada terlebih dahulu, dan pembuatannya hanya satu `create_pda` panggilan. Salah satu sisi dapat mengirimkannya: dompet Solana milik pengguna sendiri melalui lane ( `buildCreatePdaCall`, setelah `isSyntheticProvisioned` mengembalikan false), atau penerbit dari kunci EVM. Tooling penerbit Bloom saat ini mengirimkannya sebagai bagian dari onboarding pemegang; aplikasi belum melakukannya pada aksi pertama pengguna, jadi siapkan sebelum pembelian pertama pemegang. Cara melakukannya, dengan panggilan SDK, ada di [Aplikasi dua lane](https://docs.rome.builders/id/panduan-pengembang/dual-lane-app.md#one-time-activate-provision-the-synthetic).
3. **Kirim melalui library lane, bukan secara manual.** `submitDoTxUnsigned` (`arc/materialise/solana/submit.ts`) meminta proxy chain untuk menyusun transaksi, dan ia menangani hal-hal yang salah dilakukan oleh transaksi buatan tangan. Setiap panggilan kontrak pada lane adalah sebuah **transaksi Solana v1 yang disusun oleh proxy** (`rome_composeUnsignedAtomicV1`) tanpa address lookup table, dan library lane gagal secara aman alih-alih kembali ke format lama. Langkah cash-in pada langkah 5 adalah transaksi Solana terpisah yang dibangun aplikasi sendiri, bukan panggilan kontrak yang disusun.
   * **Penemuan akun dan compute budget adalah tugas proxy.** Proxy menirukan panggilan, menentukan dapat-tulis setiap akun ( `nilai` merupakan bagian dari yang ditirukannya, jadi teruskan), dan menetapkan compute dan heap budget pada transaksi yang dikembalikannya. Tidak ada dalam kode Anda yang membangun instruksi compute-budget atau menambahkan akun fee-pool.
   * **Dua tanda tangan per panggilan, keduanya dari kunci Solana.** Dompet pertama-tama menandatangani pesan otorisasi yang dapat dibaca (*Otorisasi Rome* ditambah hash dari payload EIP-1559 yang belum ditandatangani; Wallet Standard `solana:signMessage`), yang diverifikasi proxy sebelum ia akan menyusun panggilan. Kemudian ia menandatangani transaksi v1 yang dikembalikan proxy (`solana:signTransaction` pada wire mentah). Library lane memperlakukan ini sebagai `signAuthHash` dan `signV1Wire`, bukan satu metode yang digabung. Pastikan dompet Anda menandatangani transaksi v1 sebelum membangun di atasnya: Solflare melakukannya di devnet saat ini dan Phantom belum.
   * **Aplikasi mengirim transaksi yang sudah ditandatangani ke Solana RPC sendiri.** Proxy menyusun; ia tidak menyiarkan panggilan atomik.
   * **Validasi sebelum meminta tanda tangan.** Library lane mengurai pesan yang disusun dan menolak yang cacat sebelum prompt transaksi.
4. **Tempatkan pemberian wrapper satu kali sebelum pengeluaran wUSDC pertama.** wUSDC memindahkan token pengguna sebagai delegate SPL pengguna tersebut, jadi alamat sintetis yang belum pernah diberi hak akan mendapat error SPL `0x4` pada transfer wUSDC pertamanya. Baca `isEnabled(user)` pada wrapper dan, ketika nilainya false, tambahkan di depan `approve_spl(wrapper, 2^64-1, mint)` pada precompile Helper sebagai langkah pertama eksekusi. Itu adalah panggilan biasa pada kedua lane, satu kali per dompet. Lihat [Pemberian sekali untuk setiap dompet](https://docs.rome.builders/id/konsep-inti/token-interop.md#one-time-grant-per-wallet).
5. **Pindahkan uang masuk sebelum panggilan yang membelanjakannya.** Sintetis tidak menyimpan apa pun saat diam. Ketika ia memegang wUSDC lebih sedikit daripada yang dibelanjakan panggilan, pindahkan kekurangannya dari akun token USDC milik dompet terlebih dahulu (pembuatan akun token sintetis yang idempoten, lalu instruksi activate-token-account dari program Rome, yang memindahkan token tanpa menjalankan EVM). Itu adalah satu transaksi Solana yang ditandatangani dengan satu prompt, dan dilewati ketika sintetis sudah memegang cukup.
6. **Relay hanya apa yang ditolak oleh penyusun atomik.** Panggilan yang tidak muat dalam satu transaksi Solana (sekitar 1,4 juta compute unit, 64 akun, 4 KB) ditolak oleh penyusun dengan *external atomic plan requires iterative composition*. Tepat pada penolakan itu, dan tidak sebelumnya, panggil `rome_relayUnsignedV1` dengan tanda tangan otorisasi yang sama: proxy menyusun dan mengirimkannya, membayar biaya Solana, dan membalas dengan hash transaksi EVM (bukan tanda tangan Solana). Sintetis membayar gas native chain dalam wei, jadi ketika saldonya kurang dari `gasLimit x maxFeePerGas`, top up terlebih dahulu dengan `rome_composeExternalDepositV1` (transaksi v1 yang ditandatangani dompet; jumlahnya harus kelipatan 10^12 wei), secara praktik satu kali per dompet. Kesalahan lain apa pun, seperti revert, kegagalan jaringan, atau tanda tangan yang ditolak, dilempar ulang, bukan di-relay. Detailnya ada di [Panggilan yang direlay dan panggilan panjang](https://docs.rome.builders/id/panduan-pengembang/call-evm-from-solana.md#relayed-calls-and-long-calls).

Pengguna adalah **pembayar biaya** dan membayar lamport (SOL) dari dompet Solana mereka untuk panggilan langsung; sintetis yang mereka kendalikan memegang aset dan tidak pernah memegang SOL. Setelah setiap pengiriman lane, polling nonce EVM sebelum yang berikutnya — indexer sedikit tertinggal dari konfirmasi Solana, dan jika tidak demikian panggilan berikutnya akan dibangun di atas nonce yang sudah dibelanjakan chain.

> **Utamakan atomik, relay saat ditolak.** Default untuk setiap panggilan adalah satu transaksi EVM yang dieksekusi di dalam satu transaksi Solana, ditandatangani oleh dompet pengguna. Relay adalah pengecualian untuk panggilan yang tidak muat, bukan rute kedua yang dipilih karena preferensi: panggilan langsung membutuhkan dua prompt, panggilan yang di-relay satu prompt, dan panggilan yang di-relay dibayar dalam gas Rome, bukan lamport. Perjalanan multi-langkah (approve, lalu beli) adalah beberapa panggilan utuh, masing-masing transaksi sendiri, bukan satu eksekusi yang dibagi melintasi transaksi.

**Mengapa RWA tidak bisa bocor keluar dari perimeter.** Aset berada di state EVM — saldonya adalah penyimpanan di dalam akun program EVM Rome. Tidak ada **mint SPL** darinya dan tidak ada yang native Solana untuk dipindahkan; primitif pemindah aset di lane beroperasi pada akun token SPL, yang tidak dimiliki saldo penyimpanan EVM. Setiap perpindahan yang dapat diekspresikan tanda tangan Solana adalah panggilan ke kontrak token, yang menjalankan gerbang allowlist — suite yang didanai menegaskan bahwa transfer ke alamat yang tidak ada di whitelist akan revert secara identik baik ditandatangani oleh kunci EVM maupun kunci Solana. Kaki cash (wUSDC) adalah pengecualian yang disengaja: ini didukung SPL dan *tidak* disapu keluar ke akun token milik pengguna sendiri.

***

## Langkah 7 — Ketahui siapa yang memegang otoritas setelah deploy

`ArcToken.initialize` berjalan dari konstruktor proxy (tx 1) dan memberikan peran kepada `msg.sender` — penggerak wizard, yaitu penerbit. Ia memberikan **lima** peran secara eksplisit:

```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);
```

Dua konsekuensi yang tidak boleh dilewatkan builder:

* **`MINTER_ROLE`, `BURNER_ROLE`, dan `UPGRADER_ROLE` TIDAK diberikan saat initialize.** Pasokan awal dicetak di dalam `initialize` (sebuah internal `_mint`, tidak perlu peran), tetapi *kemudian* `mint` atau `burn` mengharuskan penerbit terlebih dahulu memberikan peran itu kepada diri mereka sendiri. Mereka bisa, karena mereka memegang `DEFAULT_ADMIN_ROLE` (admin dari setiap peran — tidak ada yang memanggil `_setRoleAdmin`, jadi `DEFAULT_ADMIN_ROLE` mengadministrasi semuanya). Namun itu adalah langkah ekstra yang disengaja, bukan kekuatan yang melekat.
* **`UPGRADER_ROLE` tidak pernah diberikan kepada factory.** Upgrade yang dimediasi factory (`ArcTokenFactoryV2.upgradeToken`) mengharuskan **factory itu sendiri** memegang `UPGRADER_ROLE` pada token — memberikannya kepada diri sendiri tidak akan menghasilkan apa pun. Pemberian itu adalah pintu satu arah yang tidak dapat dibalik oleh factory, jadi sifatnya opt-in: jika Anda ingin upgrade yang dimediasi factory, `grantRole(UPGRADER_ROLE, factory)` secara eksplisit; jika tidak, penerbit meng-upgrade token secara langsung.

Model otoritas penuh 21 (11 nama peran di enam kontrak — nama yang sama adalah otoritas yang berbeda pada tiap kontrak) dikodifikasi dalam `arc/roles.ts`. Minta `rolesRequiredFor(contract, functionName)` daripada membaca kontrak milik peran itu sendiri, karena empat fungsi storefront dan kedua fungsi factory dibatasi oleh otoritas yang berada pada *yang berbeda* .

***

## Langkah 8 — Distribusikan yield

Token membayar yield dalam wUSDC (ditetapkan pada `initialize`, dapat diubah melalui `setYieldToken` di bawah `YIELD_MANAGER_ROLE`). Distribusi menelusuri himpunan pemegang:

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

Mekanisme yang penting untuk menjalankannya dengan benar:

* **Seluruh `totalAmount` diambil dari pemanggil hanya pada `startIndex == 0` jendela** (`safeTransferFrom(msg.sender, this, totalAmount)`). Setujui total itu ke token sebelum jendela pertama; jendela berikutnya membayar dari saldo yang sudah dipegang.
* **`nextIndex` berputar ke `0` saat penelusuran selesai.** Ulangi `distributeYieldWithLimit(total, nextIndex, …)` hingga `nextIndex` kembali `0`.
* **Bagian milik pemegang yang dibatasi yield tetap berada di kontrak token** — mereka dilewati, bukan didistribusikan ulang.

> **Di Rome, batas praktisnya adalah `maxHolders = 1` per transaksi** — batas 62 akun yang sama dari langkah 2 — jadi yield ditelusuri satu pemegang per transaksi (terukur \~318 K gas per pemegang). Setiap pemegang yang ada di whitelist, EVM maupun native Solana, menerima pro-rata; skrip referensinya adalah `measure-yield-batch.ts` dan langkah yield pada smoke funded memverifikasinya end-to-end.

```bash
# Bentuk referensi USAGE.md: telusuri satu pemegang per tx sampai nextIndex berputar ke 0
distributeYieldWithLimit(total, offset, 1)
```

***

## Langkah 9 — Verifikasi apa yang Anda deploy

Tidak ada yang mengirim sumber secara otomatis ke mana pun di Rome, jadi verifikasi adalah langkah yang Anda jalankan. Setelah setiap deploy — infrastruktur atau token baru — jalankan verifier read-only, tanpa kunci, idempoten (kontrak yang sudah terverifikasi dilewati, jadi menjalankannya ulang setelah menerbitkan token hanya memverifikasi yang baru):

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

Itu mengharapkan **tiga** kontrak per token (proxy + kedua modul) ditambah infrastruktur, dan melaporkan apa yang tidak dapat diverifikasi alih-alih membuat deploy gagal. Melakukan ini secara manual sekali melewatkan tujuh kontrak.

Mendaftarkan aset ke registry Rome memperlakukan verifikasi sebagai **gerbang**, bukan dekorasi (`register-asset.ts`): token memperoleh `apps/arc/<chain>.json` catatan — yang memuat `standard: arc-permissioned-erc20` dan sebuah `transferRestriction` yang menamai gerbang allowlist-nya — hanya ketika ketiga kontraknya telah diverifikasi di Sourcify. Catatan itu membaca chain untuk fakta-faktanya (token yang di-deploy wizard tidak memiliki receipt yang dikomit) dan hanya menulis checkout registry lokal; meloloskan PR adalah tugas seseorang.

```bash
CHAIN_ID=200010 npx tsx register-asset.ts <tokenAddress>        # verifikasi + siapkan catatan registry
CHAIN_ID=200010 DRY=1 npx tsx register-asset.ts <tokenAddress>  # pratinjau read-only
```

Untuk bukti end-to-end dari seluruh loop — buat, whitelist, gate, jual di kedua lane, distribusikan yield — jalankan smoke funded pada chain mana pun:

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

***

## Langkah 10 — Ketahui apa yang tetap off-chain

Model kepercayaan sengaja jujur, dan builder harus menyajikannya dengan cara yang sama kepada pengguna mereka sendiri:

* **Flag allowlist adalah keputusan off-chain Anda.** KYC/AML terjadi di proses Anda — vendor Anda, aturan Anda. Chain hanya mencatat dan menegakkan *hasilnya*, `isWhitelisted(addr)`.
* **Satu-satunya state on-chain adalah satu boolean per alamat.** Tidak ada PII, tidak ada dokumen, tidak ada klaim identitas, tidak ada attestation on-chain, tidak ada bukti kriptografis tentang milik siapa sebuah alamat. Inilah model Arc seperti yang digunakan di Plume; model ini menukar transfer yang lebih berat dari standar identitas on-chain (mis. ERC-3643) untuk mekanik yang lebih ringan dan kepercayaan yang dipegang penerbit.
* **Pemulihan adalah kekuatan penerbit, bukan jalan keluar.** Dompet yang hilang — EVM atau Solana — dipulihkan dengan memasukkan alamat pengganti ke whitelist dan, jika perlu, menggunakan mint/burn/upgrade di bawah proses legal Anda sendiri (Arc tidak memiliki primitif forced-transfer bawaan). Dengan demikian kustodi kunci penerbit adalah bagian dari postur kepatuhan.
* **Tidak ada relayer milik Bloom sendiri, tidak ada permukaan kustodian.** Pengguna memegang gas mereka sendiri di kedua lane. Layanan fee-payer yang dijalankan aplikasi berarti memegang kunci — permukaan yang tidak boleh ditambahkan produk RWA. Satu relay di lane Solana adalah milik proxy chain, untuk panggilan yang terlalu besar untuk satu transaksi, dan pengguna tetap mengotorisasinya dengan tanda tangan mereka sendiri dan membayarnya dalam gas Rome mereka sendiri.

***

## Referensi: tooling

Setiap skrip berjalan dari direktori tooling `scripts/` dengan `PRIVATE_KEY`, `CHAIN_ID`, dan `REGISTRY_ROOT` diekspor.

| Skrip                           | Apa yang dilakukannya                                                                |
| ------------------------------- | ------------------------------------------------------------------------------------ |
| `deploy-infra.ts`               | Sekali per chain: empat kontrak bersama, dikonfigurasi untuk wUSDC.                  |
| `create-token.ts`               | Wizard bertahap — delapan transaksi, satu token.                                     |
| `rotate-factory.ts`             | Deploy factory baru setelah perubahan compiler/artifact; sambungkan ulang.           |
| `verify-artifact-provenance.ts` | Buktikan bahwa artifact proxy Anda diterima oleh factory yang di-deploy (read-only). |
| `verify-deployments.ts`         | Verifikasi ketiga kontrak per token + infrastruktur di Sourcify (read-only).         |
| `register-asset.ts`             | Verifikasi gerbang, lalu siapkan catatan kepatuhan registry.                         |
| `measure-yield-batch.ts`        | Ukur ulang batas yield per tx pada sebuah chain.                                     |
| `smoke.ts`                      | Rangkaian end-to-end yang didanai di kedua lane.                                     |
| `sweep-synthetic-native.ts`     | Ambil kembali gas native dari akun sintetis (kebersihan pengujian).                  |

Latar belakang lebih dalam tersedia bersama panduan ini: `docs/ARCHITECTURE.md` (model aplikasi berlapis), `docs/LANES.md` (dua lane dan kustodi), `docs/COMPLIANCE.md` (model kepercayaan), dan `docs/USAGE.md` (buku panduan operator).


---

# 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/id/aplikasi-di-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.
