> 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/ko/rome-1/bloom/building.md).

# Bloom에서 구축하기

이 가이드는 하나의 질문에 답합니다: **빌더는 이것을 어떻게 직접 수행하나요?** Solidity 실물 자산 계약을 가져와 Rome 체인에 허가형 토큰으로 배포하고, 두 번째 토큰 없이 Solana 지갑과 EVM 지갑 모두에서 열어 두며, 자체 KYC/컴플라이언스 결정을 연결합니다.

독자는 이 접근법을 평가하거나 도입하려는 개발자입니다. Bloom은 전체에서 사용되는 실전 예시이며 — 그 실제 운용 자산 **ARCV ("Mineral Vault I")** Hadrian (`200010`)의 실제 인스턴스이며, 아래의 모든 단계를 그대로 따르고, 그 배포 영수증(`deployments/200010.tokens/ARCV.json`)에는 이 방법이 생성하는 정확한 세 개의 계약과 여덟 개의 트랜잭션이 기록되어 있습니다.

여기에는 자산 계약을 수정하는 내용이 없습니다. Bloom은 Plume의 Arc 프레임워크를 **수정 없이** (vendor 처리된 트리인 `contracts/`, 바이트 단위로 동일하게 `plumenetwork/contracts` 의 NOTICE에 있는 고정 지점과 동일합니다); Rome 쪽 계약은 `NOTICE`에 있는 고정 지점만 있습니다. `ArcTokenFactoryV2`이며, 기능 하나를 추가합니다. 작업은 *어떻게* 여러분이 배포하고 *어떻게* 계약을 운용하는 데 있는 것이지 — 계약을 바꾸는 데 있는 것이 아닙니다.

> **방법을 한눈에 보면.** 허가형 토큰은 **세** 개의 배포된 계약입니다. 배포는 **조각별로** — 트랜잭션 하나당 계약 하나 — 진행됩니다. 한 번의 트랜잭션으로 팩토리 호출을 하면 Rome의 트랜잭션당 계정 한도를 초과하기 때문입니다. 그 프록시들은 **출처가 고정된 아티팩트** 에서만 와야 하며, 그렇지 않으면 온체인 등록이 닫힌 상태로 실패합니다. 컴플라이언스는 주소당 **불리언 하나**이며, 여러분의 KYC 프로세스가 승인한 사람이 기록합니다. 그리고 같은 배포는 온체인에서 파생된 **합성 sender** 를 통해 Solana 지갑에서도 접근할 수 있습니다 — 두 번째 토큰도, 두 번째 허용 목록도 없습니다.

## 필수 조건

> **시작하기 전에.** 이 가이드에서 사용하는 발행자 도구는 아직 공개되지 않았습니다. 여기에는 스크립트(`deploy-infra.ts`, `create-token.ts` 및 나머지), `contracts/` 그리고 `rome-contracts/` 트리, 그리고 그 안에서 참조하는 배포 영수증이 포함됩니다. 발행자는 Rome에 온보딩하면 이 도구를 받습니다. 그 전까지는 이 가이드를 방법과 각 스크립트가 하는 일에 대한 설명으로 읽으십시오.

참조용 도구는 `scripts/` 디렉터리에 있습니다(온보딩 시 제공됨; `npm install`로 의존성을 설치하세요). 모든 명령은 체인 정보를 하드코딩하지 않고 레지스트리에서 가져오므로, 다른 Rome 체인으로 재지정하는 것은 코드 변경이 아니라 환경 변경입니다:

```bash
export PRIVATE_KEY=…       # 대상 체인에서 자금이 있는 배포자/발행자 키
export CHAIN_ID=200010     # 체인 선택
export REGISTRY_ROOT=…     # Rome 체인 레지스트리 체크아웃
# Solana 경로 흐름에도 필요합니다:
export SOLANA_KEYPAIR=…    # 자금이 있는 Solana 키페어 JSON 경로(수수료 지불자)
```

Rome 체인의 가스는 USDC 기준으로 표시됩니다. 전체 배포 시퀀스는 devnet에서 대략 10\~15 네이티브 단위가 듭니다. 키는 환경에서만 가져오며 — 저장소에는 절대 두지 마십시오. 배포 전에 계약을 한 번 빌드하세요. 아티팩트는 **반드시** 다음에서 와야 합니다 `rome-contracts/out` (3단계 참조):

```bash
cd contracts       && forge build --via-ir     # vendor 처리된 Arc 제품군
cd rome-contracts  && forge build --via-ir     # ArcTokenFactoryV2 + 표준 프록시
```

***

## 1단계 — 여기서 허가형 토큰이 무엇인지 이해하기 *가* 여기서

허가형 Bloom 토큰은 하나의 계약이 아닙니다. **세 개의 배포된 계약**이며, 여기에 운영팀이 체인당 한 번 배포하고 모든 발행자가 재사용하는 네 개의 공유 계약이 더해집니다.

**토큰별 세 계약** — 하나의 자산이 정확히 다음을 가집니다:

| 계약                           | 소스                                                          | 무엇인지                                                              |
| ---------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------- |
| `ArcTokenProxy`              | `contracts/src/proxy/ArcTokenProxy.sol`                     | 토큰 자체 — 공유 `ArcToken` 구현을 가리키는 UUPS 프록시입니다. 잔액, 보유자, 역할은 여기 있습니다. |
| `WhitelistRestrictions`      | `contracts/src/restrictions/WhitelistRestrictions.sol`      | 허용 목록 모듈입니다. 주소당 불리언 하나이며; 자산이 게이트된 동안 모든 전송에서 강제됩니다.             |
| `YieldBlacklistRestrictions` | `contracts/src/restrictions/YieldBlacklistRestrictions.sol` | 수익 모듈입니다. 보유량은 건드리지 않고 주소를 수익 분배에서 제외합니다.                         |

**체인당 하나씩 배포되는 네 개의 공유 계약** (배포 주체 `deploy-infra.ts`):

| 계약                   | 역할                                     |
| -------------------- | -------------------------------------- |
| `RestrictionsRouter` | 모듈 유형 레지스트리 — 체인 연결 설정은 운영팀이 한 번만 합니다. |
| `ArcTokenFactoryV2`  | 등록 + 표준 프록시 코드해시(2\~3단계).              |
| `ArcToken` (구현체)     | 모든 토큰이 프록시하는 공유 재사용 자산 로직입니다.          |
| `ArcTokenPurchase`   | 모든 토큰과 발행자가 공유하는 단일 스토어프런트(4단계).       |
| wUSDC                | 현금 쪽 — 수익 통화와 매매 통화.                   |

전송 제한과 수익 제한은 **의도적으로 분리된 모듈**입니다: 보유자는 자산을 유지한 채 수익만 차단될 수 있으며, 이것이 실제 제재와 법원 명령의 작동 방식입니다.

이 "세 계약" 사실은 검증에서 핵심 전제입니다. `verify-deployments.ts` 그리고 `register-asset.ts` 둘 다 토큰이 세 개의 배포된 계약으로 해석되기를 기대합니다 — 한 번 수동으로 토큰을 검증하다가 체인 전체에서 그중 일곱 개를 놓친 적이 있습니다(모든 수익 모듈과 세 개의 허용 목록 모듈).

수명주기는 세 단계와 하나의 일방향 문으로 구성됩니다:

```
draft     프록시만 활성화, 모듈 연결 없음 — 전송을 막는 것은 아무것도 없음
  ↓
ungated   모듈 연결됨, transfersAllowed = true   (WhitelistRestrictions.initialize가 이를 설정)
  ↓  공급량 민트, 허용 목록 구축               [되돌릴 수 있음]
gated     setTransfersAllowed(false)                [일방향 문 — 공급량이 최종화됨]
```

민트와 burn이 상대방으로 `address(0)` 를 사용하고, `address(0)` 는 절대 허용 목록에 들어갈 수 없기 때문에 공급량에 대한 게이트는 일방향입니다. 따라서 한 번 게이트되면 새로운 공급은 절대 발행될 수 없습니다. 이것이 허가형 자산이 보유자에게 보장하는 내용입니다.

***

## 2단계 — 한 번의 트랜잭션으로 하지 말고, 조각별로 배포하기

Arc는 원샷 `createToken` 을 제공합니다. 이 원샷은 프록시와 두 모듈을 배포하고 한 번의 호출로 연결합니다. **Rome에서는 이를 사용할 수 없습니다.** 그 트랜잭션에는 **Solana 계정 락 77개**가 필요하지만, Rome의 트랜잭션당 한도는 **62개 락**입니다. 튜닝해도, 최적화 패스를 돌려도 절대 들어맞지 않습니다.

따라서 배포는 **조각별로**조각별입니다: `ArcTokenFactoryV2.registerToken` 단일 거대 호출 대신 `createToken`토큰은 팩토리와 동등한 지위를 얻습니다. 이것이 생성 마법사이며, 발행자 콘솔이 단계별로 수행하는 작업입니다:

![생성 마법사](https://1350471780-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)

참조 구현은 `arc/plan/create.ts` (`createSequence()`이며, 앱은 이를 여섯 개의 카드(`bloom/lib/createCards.ts`에 걸쳐 **여덟 개의 트랜잭션**으로 렌더링합니다. 순서는 계약이 강제하는 정확한 순서입니다:

| # | 트랜잭션        | 계약 호출                                                                        |
| - | ----------- | ---------------------------------------------------------------------------- |
| 1 | 자산 배포       | `new ArcTokenProxy(impl, initData)` 에서 `initData = ArcToken.initialize(...)` |
| 2 | 허용 목록 모듈 배포 | `new WhitelistRestrictions()`                                                |
| 3 | 당신을 관리자로 설정 | `whitelist.initialize(issuer)`                                               |
| 4 | 전송에 적용      | `token.setRestrictionModule(TRANSFER, whitelist)`                            |
| 5 | 수익 모듈 배포    | `new YieldBlacklistRestrictions()`                                           |
| 6 | 당신을 관리자로 설정 | `yieldBlacklist.initialize(issuer)`                                          |
| 7 | 수익에 적용      | `token.setRestrictionModule(YIELD, yieldBlacklist)`                          |
| 8 | 팩토리에 등록     | `factoryV2.registerToken(token, impl)`                                       |

스크립트 형태는 한 줄입니다:

```bash
# 체인당 한 번만(운영용, 토큰별 아님) — 네 개의 공유 계약을 배포합니다
npx tsx deploy-infra.ts

# 토큰별 — 생성 마법사를 스크립트로 재현
NAME="Mineral Vault I" SYMBOL=ARCV SUPPLY=1000000 DECIMALS=6 npx tsx create-token.ts
```

발행자(`PRIVATE_KEY`)는 모든 트랜잭션에 서명하고, 결국 토큰의 역할(`ArcToken.initialize` 부여 대상 `msg.sender` — 7단계 참조)을 보유하게 됩니다. 등록(tx 8)은 스토어프런트의 `enableToken` 과 팩토리 매개 업그레이드를 가능하게 하는 열쇠입니다.

> **이것을 다시 하나의 거대 호출로 "최적화"하지 마십시오.** 이 호출들을 왕복 비용을 줄이려고 하나의 트랜잭션으로 묶으면, 조각별 경로가 피하려던 바로 그 62개 락 초과가 다시 발생합니다. 같은 한도 때문에 수익 분배도 한 트랜잭션당 보유자 한 명씩 처리합니다(8단계). 호출이 `Too many accounts: N > 62`로 실패하면, 한 트랜잭션이 너무 많은 계정을 건드린 것입니다 — 튜닝하지 말고 분할하십시오.

***

## 3단계 — 출처가 고정된 아티팩트에서만 프록시 배포하기

`registerToken` 은 조각별 배포를 안전하게 만드는 보안 경계입니다. 이 함수는 토큰의 **런타임 코드해시가 배포 시 팩토리에 내장된 표준과 일치하는 경우에만 `ArcTokenProxy`** 수락합니다:

```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();
    // …구현체는 팩토리 허용 목록에 있어야 하며, msg.sender는
    //    토큰의 ADMIN_ROLE을 보유해야 하고, 토큰은 아직 등록되지 않았어야 합니다.
}
```

그 코드해시는 **불변**이므로, 다른 아티팩트에서 만든 프록시는 `ProxyCodehashUnknown`으로 닫힌 상태로 실패합니다. 여기서 두 가지 규칙이 나오며, 둘 다 CI와 `CLAUDE.md`:

1. **의 하드 규칙으로 강제됩니다. 토큰 프록시는 반드시 `rome-contracts/out`** — 절대로 `contracts/out`에서 배포하지 말고, 다른 빌드에서도 배포하지 마십시오. 이것이 팩토리의 표준 코드해시가 고정하는 컴파일 결과입니다.
2. **`bytecode_hash = "none"` 그리고 `cbor_metadata = false`** 을 `rome-contracts/foundry.toml` 는 핵심 전제입니다. 메타데이터를 켜면, 팩토리에 내장된 `ArcTokenProxy` 런타임 *에* 포함된`type().runtimeCode`는 생성기 마법사가 배포하는 독립형 `out/` 아티팩트와 다른 CBOR/IPFS 꼬리를 가지게 됩니다 — 그래서 온체인에서는 `registerToken` revert가 발생하지만 **모든 소스 내 Foundry 테스트는 통과합니다** (Foundry는 두 복사본을 모두 포함하므로 불일치를 볼 수 없습니다). `rome-contracts/test/ArtifactProvenance.t.sol` 이 속성을 고정합니다; 자금을 넣은 실행이 원래 이 문제를 찾아냈습니다.

> **소스 내 테스트가 모두 초록이라고 해서 출처가 증명되는 것은 아닙니다.** 이미지를 배포하기 전, 그리고 어떤 컴파일러 설정이든 바꾼 뒤에는, *배포된* 팩토리(읽기 전용, 키 없음)를 대상으로 이 속성을 증명하세요:
>
> ```bash
> cd scripts && CHAIN_ID=<id> npx tsx verify-artifact-provenance.ts
> ```
>
> 이 스크립트는 로컬 `ArcTokenProxy` 아티팩트를 해시하고, 그 해시가 배포된 팩토리의 바이트코드 안에 그대로 존재함을 검증합니다.

컴파일러 설정을 바꿔야 한다면, **팩토리를 교체하세요** — 새 코드해시를 불변으로 고정한 새 팩토리를 배포하고 다시 연결하세요 — 검사를 손으로 패치하지 말고:

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

교체는 영수증에 이전 주소를 남깁니다; 이전 팩토리에 등록된 토큰은 새 팩토리로 다시 등록해야 합니다.

***

## 4단계 — 공유 스토어프런트를 통해 판매 열기

판매는 생성과는 별개의 행위이며, 하나의 공유 `ArcTokenPurchase` 스토어프런트에서 실행됩니다. 판매를 열기 전에 세 가지가 충족되어야 하고, `ArcTokenPurchase.enableToken` 이 온체인에서 각각 확인합니다:

```solidity
// contracts/src/ArcTokenPurchase.sol
function enableToken(address _tokenContract, uint256 _numberOfTokens, uint256 _tokenPrice)
    external onlyTokenAdmin(_tokenContract)                       // (a) 토큰의 ADMIN_ROLE을 보유해야 합니다
{
    // (b) 토큰은 팩토리에서 알려진 것이어야 합니다 — 이것이 2단계의 registerToken이 확보한 내용입니다:
    if (ArcTokenFactory(ps.tokenFactory).getTokenImplementation(_tokenContract) == address(0))
        revert TokenNotCreatedByFactory();
    // (c) 스토어프런트는 이미 판매 재고를 보유하고 있어야 합니다:
    if (ArcToken(_tokenContract).balanceOf(address(this)) < _numberOfTokens)
        revert ContractMissingRequiredTokens();
    // …가격과 수량은 양수여야 합니다.
}
```

게이트된 자산이 강제하는 네 번째 암묵적 요구사항이 있습니다: **모든 전송이 허용 목록 게이트를 통과하기 때문에**재고를 스토어프런트로 옮기려면 스토어프런트 주소 자체가 토큰에서 허용 목록에 있어야만 성공합니다. 따라서 판매 열기 전체 시퀀스는 다음과 같습니다:

1. **스토어프런트 허용 목록에 추가** 토큰의 허용 목록 모듈에서(`batchAddToWhitelist([storefront])` — 5단계 참조). 이것이 없으면 (2)의 재고 전송은 `TransferRestricted()` 게이트가 적용된 뒤
2. **재고 전송** 스토어프런트 주소로(인프라 영수증의 `arcTokenPurchase`).
3. **`enableToken(token, amount, price)`** 에서) 수행하며 — 이제 구매자는 wUSDC를 지불하고 RWA를 받습니다.

공유 *스토어프런트에서는* 출금 분할을 알아둘 가치가 있으며, 대칭적이지도 않습니다(`arc/roles.ts` 가 권한 주체입니다):

| 작업                                                         | 권한                                  | 보유자            |
| ---------------------------------------------------------- | ----------------------------------- | -------------- |
| `enableToken` / `disableToken` / `withdrawUnsoldArcTokens` | 토큰의 `ADMIN_ROLE` (`onlyTokenAdmin`) | 당신, 발행자        |
| `withdrawPurchaseTokens` (wUSDC 수익)                        | 스토어프런트의 `DEFAULT_ADMIN_ROLE`        | 스토어프런트를 배포한 사람 |

자체 호스팅 체인에서는 당신이 두 권한을 모두 가집니다. 공유 스토어프런트에서는 수익 풀은 모든 발행자의 수익이므로, 출금은 플랫폼 수준입니다 — 단독 통제를 가정하지 말고 그에 맞게 정산을 설계하십시오.

***

## 5단계 — 자체 KYC / 컴플라이언스 연결하기

이 부분은 고객이 yes라고 말하기 전에 읽는 섹션이므로, 산문이 아니라 코드입니다. **컴플라이언스는 토큰 계약 자체에 의해 강제됩니다** — 오프체인 화면, 시퀀서 필터, 또는 거래소 정책이 아닙니다. 규칙은 양쪽 지갑 경로의 어떤 실행 경로로도 토큰과 함께 이동합니다. 체인이 기록하는 것은 **결과** 당신의 KYC 결정의 상태를, 단일 불리언으로:

```solidity
// contracts/src/restrictions/WhitelistRestrictions.sol — 온체인 상태 전체를
struct WhitelistStorage {
    mapping(address => bool) isWhitelisted;   // ← 주소당 불리언 하나. 개인 식별 정보(PII)는 절대 없음.
    bool transfersAllowed;                    // false = 게이트 적용; 허용 목록에 있는 주소만 전송 가능
    EnumerableSet.AddressSet whitelistedAddresses;
}
```

### 당신의 프로세스가 기록하는 인터페이스

귀하의 KYC 벤더의 승인/거부 결정은 정확히 다음 호출 중 하나가 됩니다:

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

### 기록 가능한 주체

> **승인에 필요한 권한은 `MANAGER_ROLE` 모듈에 있습니다&#x20;*****—*****&#x20;토큰이 아닙니다. `ADMIN_ROLE` 에 있습니다.** `addToWhitelist` / `batchAddToWhitelist` / `removeFromWhitelist` 는 모두 `onlyRole(MANAGER_ROLE)`이며, 그 역할은 `WhitelistRestrictions` 인스턴스에 존재합니다. 토큰에서 인증한 뒤 모듈에 쓰는 것은 이 코드베이스가 이미 비용을 치른 실제 결함입니다. 거부에 대한 해결책으로 `ADMIN_ROLE` 를 제시하지 마십시오 — 이는 initialize 시 부여되고 `WHITELIST_ADMIN_ROLE` 어느 테스트 스위트에서도 확인되지 않으며 **(그 역할이 아무것도 게이트하지 않음을 주장합니다).** (`arc/roles.ts` 이 하나의 역할은 아무것도 막지 않는다는 것을).

`WhitelistRestrictions.initialize(issuer)` (마법사 3번째 트랜잭션)는 발행자에게 `DEFAULT_ADMIN_ROLE`, `ADMIN_ROLE`, `MANAGER_ROLE`, `WHITELIST_ADMIN_ROLE`, 그리고 `UPGRADER_ROLE` 를 이 모듈에서 부여합니다. 그래서 발행자는 기본 상태에서 `MANAGER_ROLE` 를 보유하고, 또한 위임할 수도 있습니다: 발행자가 `DEFAULT_ADMIN_ROLE`과 `grantRole(MANAGER_ROLE, serviceAccount)` 를 통해 쓰기 권한을 백엔드 서명자에게 넘깁니다.

### 결정이 온체인 쓰기로 이어지는 과정

벤더의 웹훅을 MANAGER\_ROLE을 보유한 서명자에게 연결하고, 승인되면 주소들을 배치하세요: `MANAGER_ROLE`,

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

// `signer`는 이 토큰의 허용 목록 모듈에서 MANAGER_ROLE을 보유해야 합니다.
const wallet = createWalletClient({ account, transport: http(chain.rpcUrl) });

// 벤더가 이 주소들을 "승인"했다고 보낸 경우:
await wallet.writeContract({
  address: whitelistModule,                 // getRestrictionModule을 통해 토큰에서 조회됨
  abi: whitelistAbi,
  functionName: 'batchAddToWhitelist',
  args: [approvedAddresses],
});
```

해결 `whitelistModule` 토큰 자체에서 (`ArcToken.getRestrictionModule(TRANSFER_RESTRICTION_TYPE)`), 절대 캐시된 프로젝션에서 가져오지 마십시오 — 잘못된 모듈에 쓰기를 시도하는 것이 한때 "모든 자산에 대한 승인"이 한 토큰의 허용 목록에 기록되게 만든 방식이었습니다.

### 지갑 서명 변형(자가 서비스 데모)

방문자가 스스로 가입하는 권한 없는 테스트 배포의 경우, 다음을 부여하세요 `MANAGER_ROLE` 에 `TestApprover` (`rome-contracts/src/TestApprover.sol`) whose `—` 가 **불변**. 그런 다음 `approve(address)` 는 누구나 자신의 지갑으로 호출할 수 있고, 자신의 가스를 지불합니다 — 호출하면 `addToWhitelist` 주소가 아직 목록에 없을 때만:

```solidity
function approve(address account) external {
    IWhitelistRestrictions target = IWhitelistRestrictions(module);   // 불변 — 하나의 모듈, 영구적으로
    if (!target.isWhitelisted(account)) target.addToWhitelist(account);
    emit Approved(account, msg.sender);
}
```

이것이 "로그인 게이트"입니다 — 보안 보관하지 않고도 방문자에게 실제 메커니즘(승인이 토큰이 강제하는 온체인 허용 목록 항목이 되는 것)을 보여줍니다. **절대 다음을 부여하지 마세요 `MANAGER_ROLE` 에 `TestApprover` 프로덕션 토큰에서** — 그 토큰의 허용 목록을 무권한으로 만듭니다.

### 게이트가 작동할 때와 제공자 교체

게이트는 자산이 **게이트 처리된** (`setTransfersAllowed(false)`, `ADMIN_ROLE` 된 후에만 전송을 제한합니다. 게이트가 해제되어 있는 동안에는 전송이 열려 있습니다 — 먼저 허용 목록을 구축한 다음 게이트를 거세요. 일단 게이트가 걸리면, 양쪽 중 어느 한쪽이라도 목록에 없으면 전송은 타입화된 오류 `TransferRestricted()` (`0xe827105e`).

> **로 되돌립니다.** 나중에 KYC 제공업체를 바꿔도 온체인 변경은 필요하지 않습니다. `MANAGER_ROLE` 허용 목록 모듈, 그 인터페이스, 그리고 저장하는 불리언은 제공업체에 종속되지 않습니다. 공급업체를 바꾸려면 동일한

***

## 1단계 — 동일한 자산을 Solana 지갑에 개방

같은 세 개의 계약에 Solana 지갑에서 접근할 수 있습니다 **두 번째 토큰 없이**. Solana 네이티브 사용자는 어디에도 EVM 키가 없습니다; 대신 그들의 EVM 신원은 *합성된*이며, 트랜잭션의 실제 Solana 서명자에서 온체인으로 파생됩니다:

```
합성 EVM 주소 = keccak256(solana_pubkey)[12..32]
```

Rome EVM 프로그램은 서명자 자체에서 이것을 파생합니다 (`do_tx_unsigned::derive_sender`), 그래서 위조할 수 없고 이에 대한 secp256k1 개인 키도 존재하지 않습니다 — **Solana 서명만이 이 주소를 구동할 수 있는 유일한 것입니다**. 참고용 파생 로직은 `arc/materialise/solana/identity.ts` (`syntheticAddress`), 온체인 규칙과 바이트 단위로 호환됩니다:

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

**빌더가 이 레인을 지원하기 위해 하는 일** — 참고로 *이것의 어떤 것도 계약 변경이 아닙니다*:

1. **합성 주소로 Solana 사용자를 허용 목록에 추가합니다.** 준수 계층에는 합성 주소가 평범한 주소처럼 보입니다: 사용자의 Solana 공개 키를 넣어 합성을 도출한 뒤 `batchAddToWhitelist([synthetic])`을 호출합니다. 하나의 허용 목록이 두 지갑 세계를 모두 포괄합니다.
2. **첫 값 이동 호출 전에 서명 PDA를 한 번 프로비저닝하세요.** 합성 주소에 서명하는 외부 권한 PDA는 먼저 존재해야 하며, 이를 생성하는 것은 `create_pda` 한 번의 호출입니다. 어느 쪽이든 보낼 수 있습니다: 레인을 통한 사용자의 Solana 지갑 자체( SDK의 `buildCreatePdaCall`, 이후 `isSyntheticProvisioned` 가 false를 반환한 뒤), 또는 EVM 키를 가진 발행자입니다. Bloom의 발행자 도구는 현재 온보딩의 일부로 이를 전송하고 있으며, 앱은 아직 사용자의 첫 동작에서 이를 수행하지 않으므로 보유자의 첫 구매 전에 프로비저닝하세요. SDK 호출로 어떻게 하는지는 [듀얼 레인 앱](https://docs.rome.builders/ko/developer-guides/dual-lane-app.md#one-time-activate-provision-the-synthetic).
3. **손으로 하지 말고 레인 라이브러리를 통해 제출하세요.** `submitDoTxUnsigned` (`arc/materialise/solana/submit.ts`)는 체인의 프록시에 트랜잭션 구성을 요청하며, 수작업으로 빌드한 것에서 잘못되는 부분을 처리합니다. 레인上的 모든 계약 호출은 **프록시가 구성한 Solana v1 트랜잭션** (`rome_composeUnsignedAtomicV1`)이며 주소 조회 테이블이 없고, 레인 라이브러리는 이전 형식으로 되돌아가지 않고 닫힌 상태로 실패합니다. 5단계의 현금 투입 동작은 앱이 자체적으로 구성하는 별도의 Solana 트랜잭션이지, 구성된 계약 호출이 아닙니다.
   * **계정 탐색과 컴퓨트 예산은 프록시의 책임입니다.** 프록시는 호출을 시뮬레이션하고 각 계정의 쓰기 가능 여부를 결정하며(호출의 `값` 는 시뮬레이션의 일부이므로 전달하세요), 반환하는 트랜잭션에 컴퓨트 및 힙 예산을 설정합니다. 당신의 코드 어디에도 컴퓨트 예산 지시문을 만들거나 수수료 풀 계정을 추가하는 일은 없습니다.
   * **호출당 두 번의 서명, 둘 다 Solana 키에서.** 지갑은 먼저 읽을 수 있는 승인 메시지(*Rome 승인* 과 unsigned EIP-1559 페이로드의 해시를 함께; Wallet Standard `solana:signMessage`를 서명합니다. 프록시는 호출을 구성하기 전에 이것을 검증합니다. 그런 다음 프록시가 반환한 v1 트랜잭션을 서명합니다(`solana:signTransaction` 를 원시 와이어에서). 레인 라이브러리는 이를 `signAuthHash` 그리고 `signV1Wire`로 받아들이며, 절대 하나로 합친 메서드가 아닙니다. 이를 기반으로 구축하기 전에 지갑이 v1 트랜잭션에 서명하는지 확인하세요: 오늘 기준 devnet에서는 Solflare가 가능하고 Phantom은 아직 아닙니다.
   * **앱은 서명된 트랜잭션을 Solana RPC로 직접 보냅니다.** 프록시는 구성할 뿐이며, 원자적 호출을 브로드캐스트하지 않습니다.
   * **서명을 요청하기 전에 검증하세요.** 레인 라이브러리는 구성된 메시지를 파싱하고 트랜잭션 프롬프트 전에 잘못된 것을 거부합니다.
4. **첫 wUSDC 지출 전에 일회성 래퍼 승인권을 먼저 부여하세요.** wUSDC는 사용자의 토큰을 그 사용자의 SPL 대리인으로 이동하므로, 한 번도 권한을 부여받지 않은 합성 주소는 첫 wUSDC 전송에서 SPL 오류 `0x4` 를 받습니다. 래퍼에서 `isEnabled(user)` 을 읽고, 그것이 false이면 `approve_spl(wrapper, 2^64-1, mint)` 를 Helper precompile에 첫 단계로 추가하세요. 이는 어느 레인에서든 한 번씩 하는 일반 호출입니다. See [지갑당 1회 권한 부여](https://docs.rome.builders/ko/core-concepts/token-interop.md#one-time-grant-per-wallet).
5. **사용하기 전에 현금을 먼저 넣으세요.** 합성은 휴면 상태에서 아무것도 보유하지 않습니다. 호출이 소비하는 것보다 적은 wUSDC를 보유할 때는, 부족분을 먼저 지갑의 자체 USDC 토큰 계정에서 이동하세요(합성의 토큰 계정을 무해하게 생성한 다음, Rome 프로그램의 activate-token-account 지시문이 EVM을 실행하지 않고 토큰을 이동함). 이는 한 번의 프롬프트로 서명되는 하나의 Solana 트랜잭션이며, 합성이 이미 충분히 보유하고 있으면 건너뜁니다.
6. **원자적 컴포저가 거부하는 것만 릴레이하세요.** 한 Solana 트랜잭션에 맞지 않는 호출(대략 1.4M 컴퓨트 유닛, 64개 계정, 4 KB)은 컴포저가 *외부 원자 계획에는 반복적 구성이 필요합니다*로 거부합니다. 정확히 그 거부가 발생했을 때만, 절대 그 전에는 `rome_relayUnsignedV1` 을 동일한 승인 서명으로 호출하세요: 프록시가 그것을 구성하고 제출하며, Solana 수수료를 지불하고, EVM 트랜잭션 해시(Solana 서명이 아님)를 반환합니다. 합성은 체인의 네이티브 가스를 wei로 지불하므로, 잔액이 `gasLimit x maxFeePerGas`보다 부족하면 먼저 `rome_composeExternalDepositV1` 로 보충하세요(지갑 서명 v1 트랜잭션; 금액은 10^12 wei의 배수여야 함), 실무상 지갑당 한 번입니다. 리버트, 네트워크 실패, 거부된 서명 같은 다른 오류는 릴레이되지 않고 다시 던져집니다. 세부 내용은 [릴레이된 호출과 긴 호출](https://docs.rome.builders/ko/developer-guides/call-evm-from-solana.md#relayed-calls-and-long-calls).

사용자가 **수수료 지불자** 이며 직접 호출에 대해 Solana 지갑에서 lamports(SOL)를 지불합니다; 사용자가 제어하는 합성은 자산을 보유하고 SOL은 보유하지 않습니다. 각 레인 전송 후에는 다음 전송 전에 EVM nonce를 폴링하세요 — 인덱서가 Solana 확인을 약간 뒤따르므로, 그렇지 않으면 다음 호출이 체인이 이미 사용한 nonce를 기반으로 구성될 수 있습니다.

> **원자성이 우선이고, 거부 시 릴레이.** 모든 호출의 기본값은 사용자의 지갑이 서명한, 하나의 Solana 트랜잭션 내부에서 실행되는 하나의 EVM 트랜잭션입니다. 릴레이는 맞지 않는 호출에 대한 예외일 뿐이며, 선호로 고르는 두 번째 경로가 아닙니다: 직접 호출은 두 번의 프롬프트, 릴레이된 호출은 한 번이며, 릴레이된 호출은 lamports 대신 Rome 가스로 지불됩니다. 다단계 여정(승인 후 구매)은 여러 개의 완전한 호출이며, 각 호출이 자체 트랜잭션이지 트랜잭션 간에 나뉜 하나의 실행이 아닙니다.

**RWA가 경계 밖으로 새지 않는 이유.** 자산은 EVM 상태 상주형입니다 — 그 잔액은 Rome EVM 프로그램의 계정 내부 저장소입니다. 그것의 **SPL 민트는 없고** Solana 네이티브로 이동할 것도 없습니다; 레인의 자산 이동 원시 기능은 SPL 토큰 계정에서 동작하며, EVM 저장소 잔액에는 그런 것이 없습니다. Solana 서명이 표현할 수 있는 모든 이동은 토큰 계약에 대한 호출이며, 이 호출은 허용 목록 게이트를 거칩니다 — 펀딩된 스위트는 EVM 키로 서명했든 Solana 키로 서명했든, 비허용 주소로의 전송은 동일하게 되돌아감을 검증합니다. 현금 레그(wUSDC)는 의도된 예외입니다: SPL 기반이며 *는* 사용자의 자체 토큰 계정으로 스윕됩니다.

***

## 1단계 — 배포 후 누가 권한을 보유하는지 알아두기

`ArcToken.initialize` 프록시 생성자(tx 1)에서 실행되며 역할을 `msg.sender` 에게 부여합니다 — 위저드 드라이버, 즉 발행자입니다. 다음 **다섯** 개의 역할을 명시적으로 부여합니다:

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

빌더가 놓치지 말아야 할 두 가지 결과:

* **`MINTER_ROLE`, `BURNER_ROLE`, 그리고 `UPGRADER_ROLE` 는 initialize에서 부여되지 않습니다.** 초기 공급량은 `초기화` 안에서 발행됩니다(내부 `_mint`, 역할 필요 없음), 하지만 *나중의* `mint` 또는 `burn` 에는 발행자가 먼저 자신에게 그 역할을 부여해야 합니다. 그들은 `DEFAULT_ADMIN_ROLE` 을 보유하므로 할 수 있습니다(모든 역할의 관리자 — 아무것도 `_setRoleAdmin`을 호출하지 않았기 때문에 `DEFAULT_ADMIN_ROLE` 가 그것들을 모두 관리합니다). 하지만 이는 의도된 추가 단계이지, 상시적인 권한이 아닙니다.
* **`UPGRADER_ROLE` 는 절대 팩토리에 부여되지 않습니다.** 팩토리 매개 업그레이드(`ArcTokenFactoryV2.upgradeToken`)는 **팩토리 자체** 가 `UPGRADER_ROLE` 토큰에서 `grantRole(UPGRADER_ROLE, factory)` 을 명시적으로 부여해야 합니다; 그렇지 않으면 발행자가 토큰을 직접 업그레이드합니다.

전체 21 권한 모델(6개 계약에 걸친 11개의 역할 이름 — 같은 이름이 각 계약마다 다른 권한입니다)은 `arc/roles.ts`. 다음을 요청하세요 `rolesRequiredFor(contract, functionName)` 에 문서화되어 있으며 역할 자신의 계약을 읽지 않습니다. 왜냐하면 4개의 스토어프런트 함수와 두 팩토리 함수는 *다른*  계약을 통해 2 USDC를 지불합니다.

***

## 2단계 — 수익 분배

토큰은 wUSDC로 수익을 지급합니다( `초기화`로 고정되어 있고, `setYieldToken` 아래로 `YIELD_MANAGER_ROLE`를 통해 변경 가능). 분배는 보유자 집합을 따라 진행됩니다:

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

올바르게 구동하는 데 중요한 메커니즘:

* **전체 `totalAmount` 은 호출자에게서 오직 `startIndex == 0` 창에서만** (`safeTransferFrom(msg.sender, this, totalAmount)`)으로 끌어옵니다. 첫 창 전에 그 총액을 토큰에 승인하세요; 이후 창은 이미 보유한 잔액에서 지급됩니다.
* **`nextIndex` 로 래핑됩니다 `0` 걷기가 완료되면.** 루프 `distributeYieldWithLimit(total, nextIndex, …)` 을 폴링하여 `nextIndex` 가 돌아오면 `0`.
* **수익 제한 보유자의 몫은 토큰 계약에 남습니다** — 재분배되지 않고 건너뜁니다.

> **Rome에서 실무상 한도는 `maxHolders = 1` 트랜잭션당** — 2단계의 동일한 62개 계정 한도이므로 — 수익은 트랜잭션당 보유자 하나씩 진행됩니다(보유자당 약 318 K 가스 측정). EVM이든 Solana 네이티브든 모든 허용 목록 보유자는 비례 배분을 받습니다; 참조 스크립트는 `measure-yield-batch.ts` 이며 펀딩된 스모크의 수익 단계가 이를 엔드 투 엔드로 검증합니다.

```bash
# USAGE.md 참조 형식: nextIndex가 0으로 돌아올 때까지 tx당 보유자 하나를 순회
distributeYieldWithLimit(total, offset, 1)
```

***

## 3단계 — 배포한 것을 검증하기

Rome에서는 소스가 어디에도 자동 제출되지 않으므로, 검증은 직접 실행하는 단계입니다. 인프라든 새 토큰이든 어떤 배포 이후에도, 읽기 전용·키 없음·idempotent 검증기를 실행하세요(이미 검증된 계약은 건너뛰므로, 토큰 발행 후 다시 실행하면 새 것만 검증됩니다):

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

그것은 **세** 토큰당 계약들(프록시 + 양쪽 모듈)과 인프라를 기대하며, 배포를 실패시키기보다 검증하지 못한 것을 보고합니다. 이것을 수동으로 한 번 수행했을 때 계약 7개를 놓쳤습니다.

자산을 Rome 레지스트리에 등록할 때 검증을 **게이트**로 취급하며, 장식이 아닙니다(`register-asset.ts`): 토큰은 `apps/arc/<chain>.json` 기록을 얻습니다 — 담고 있는 `standard: arc-permissioned-erc20` 과 `transferRestriction` 이름의 허용 목록 게이트는 Sourcify에서 세 계약 모두가 검증될 때만 부여됩니다. 그 기록은 사실을 위해 체인을 읽고(위저드가 배포한 토큰에는 커밋된 영수증이 없음) 로컬 레지스트리 체크아웃에만 씁니다; PR을 병합하는 일은 사람의 몫입니다.

```bash
CHAIN_ID=200010 npx tsx register-asset.ts <tokenAddress>        # 검증 + 레지스트리 기록 준비
CHAIN_ID=200010 DRY=1 npx tsx register-asset.ts <tokenAddress>  # 읽기 전용 미리보기
```

전체 루프의 엔드 투 엔드 증명을 위해 — 생성, 허용 목록 추가, 게이트, 양쪽 레인에서 판매, 수익 분배 — 어떤 체인에서든 펀딩된 스모크를 실행하세요:

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

***

## 4단계 — 무엇이 오프체인에 남는지 알기

신뢰 모델은 의도적으로 솔직하며, 빌더는 자신의 사용자에게도 같은 방식으로 설명해야 합니다:

* **허용 목록 플래그는 귀하의 오프체인 결정입니다.** KYC/AML은 귀하의 프로세스에서 이루어집니다 — 귀하의 벤더, 귀하의 규칙. 체인은 오직 *결과*, `isWhitelisted(addr)`.
* **온체인 상태는 주소당 하나의 불리언뿐입니다.** PII 없음, 문서 없음, 신원 주장 없음, 온체인 증명 없음, 주소가 누구의 것인지에 대한 암호학적 증명 없음. 이것이 Plume에서 사용되는 Arc의 모델입니다; 온체인 신원 표준(예: ERC-3643)의 더 무거운 전송을 더 가벼운 메커니즘과 발행자 보유 신뢰로 바꿉니다.
* **복구는 발행자의 권한이지, 탈출구가 아닙니다.** 분실된 지갑 — EVM이든 Solana든 — 은 대체 주소를 허용 목록에 추가하고, 필요하다면 귀하의 법적 절차에 따라 mint/burn/upgrade를 사용하여 복구됩니다(Arc에는 강제 전송 원시 기능이 내장되어 있지 않습니다). 따라서 발행자의 키 보관은 준수 태세의 일부입니다.
* **Bloom 자체의 릴레이 없음, 보관 표면 없음.** 사용자는 두 레인 모두에서 자신의 가스를 보유합니다. 앱이 운영하는 수수료 지불자 서비스는 키를 보관해야 한다는 뜻이며 — RWA 제품이 추가해서는 안 되는 표면입니다. Solana 레인의 단 하나의 릴레이는 한 트랜잭션에 맞지 않는 호출을 위한 체인 프록시의 것이며, 사용자는 여전히 자신의 서명으로 이를 승인하고 자신의 Rome 가스로 비용을 지불합니다.

***

## 참고: 툴링

모든 스크립트는 툴링의 `scripts/` 디렉터리에서 실행되며, `PRIVATE_KEY`, `CHAIN_ID`, 그리고 `REGISTRY_ROOT` 가 export됩니다.

| 스크립트                            | 하는 일                                        |
| ------------------------------- | ------------------------------------------- |
| `deploy-infra.ts`               | 체인당 한 번: wUSDC용으로 연결된 네 개의 공유 계약.           |
| `create-token.ts`               | 부분별 위저드 — 여덟 번의 트랜잭션, 하나의 토큰.               |
| `rotate-factory.ts`             | 컴파일러/아티팩트 변경 후 새 팩토리를 배포합니다; 다시 연결합니다.      |
| `verify-artifact-provenance.ts` | 배포된 팩토리가 귀하의 프록시 아티팩트를 수락하는지 증명합니다(읽기 전용).  |
| `verify-deployments.ts`         | 토큰 + 인프라당 세 계약 모두를 Sourcify에서 검증합니다(읽기 전용). |
| `register-asset.ts`             | 게이트를 검증한 후 레지스트리 준수 기록을 준비합니다.              |
| `measure-yield-batch.ts`        | 체인에서 트랜잭션당 수익 상한을 다시 측정합니다.                 |
| `smoke.ts`                      | 두 레인 전반의 펀딩된 엔드 투 엔드 스위트.                   |
| `sweep-synthetic-native.ts`     | 합성 계정에서 네이티브 가스를 회수합니다(테스트 위생).             |

더 깊은 배경은 이 가이드 옆에 있습니다: `docs/ARCHITECTURE.md` (계층화된 앱 모델), `docs/LANES.md` (두 레인과 보관), `docs/COMPLIANCE.md` (신뢰 모델), 그리고 `docs/USAGE.md` (운영자 런북).


---

# 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/ko/rome-1/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.
