> 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/de/apps-auf-rome/bloom/building.md).

# Auf Bloom aufbauen

Dieser Leitfaden beantwortet eine Frage: **Wie macht ein Builder das selbst?** Nimm einen Solidity-Real-World-Asset-Vertrag, stelle ihn auf einer Rome-Chain als berechtigtes Token bereit, öffne ihn sowohl für Solana-Wallets als auch für EVM-Wallets, ohne ein zweites Token zu benötigen, und binde deine eigene KYC-/Compliance-Entscheidung ein.

Die Zielgruppe ist ein Entwickler, der den Ansatz evaluiert oder übernimmt. Bloom ist durchgehend das ausgearbeitete Beispiel — sein Live-Asset **ARCV ("Mineral Vault I")** auf Hadrian (`200010`) ist eine reale Instanz jedes der folgenden Schritte, und seine Deploy-Quittung (`deployments/200010.tokens/ARCV.json`) dokumentiert die exakten drei Verträge und acht Transaktionen, die diese Methode erzeugt.

Nichts hier verändert die Asset-Verträge. Bloom verwendet Plumes Arc-Framework **unverändert** (der vendorte Baum in `contracts/`, byteidentisch zu `plumenetwork/contracts` am Pin in `NOTICE`); der einzige Vertrag auf Rome-Seite ist `ArcTokenFactoryV2`, das eine Funktion hinzufügt. Die Arbeit liegt darin, dass *wie* du bereitstellst und *wie* du die Verträge steuerst — nicht darin, sie zu ändern.

> **Die Methode auf einen Blick.** Ein berechtigtes Token ist **drei** bereitgestellte Verträge. Es wird **stückweise** bereitgestellt — ein Vertrag pro Transaktion — weil ein Factory-Aufruf in einer einzigen Transaktion das Konto-pro-Transaktion-Limit von Rome überschreitet. Seine Proxys müssen aus **herkunftsgebundenen Artefakten** stammen, oder die On-Chain-Registrierung schlägt sicher fehl. Compliance ist ein **Boolean pro Adresse**, geschrieben von demjenigen, den dein KYC-Prozess autorisiert. Und dieselbe Bereitstellung ist von einer Solana-Wallet aus über einen **synthetischen Sender** zugänglich, der on-chain abgeleitet wird — kein zweites Token, keine zweite Allowlist.

## Voraussetzungen

> **Bevor du beginnst.** Das Issuer-Tooling, das dieser Leitfaden verwendet, ist noch nicht veröffentlicht. Das umfasst die Skripte (`deploy-infra.ts`, `create-token.ts` und der Rest), die `contracts/` und `rome-contracts/` Baumstrukturen und die Deploy-Quittungen, die es benennt. Issuer erhalten dieses Tooling durch das Onboarding bei Rome. Bis dahin lies den Leitfaden als Beschreibung der Methode und dessen, was jedes Skript tut.

Das Referenz-Tooling liegt in einem `scripts/` Verzeichnis (wird beim Onboarding bereitgestellt; installiere seine Abhängigkeiten mit `npm install`). Jeder Befehl löst Kettendaten aus dem Registry auf statt sie fest einzubauen, daher ist das Umstellen auf eine andere Rome-Chain eine Umgebungsänderung, keine Codeänderung:

```bash
export PRIVATE_KEY=…       # mit Guthaben versehener Deploy-/Issuer-Schlüssel auf der Ziel-Chain
export CHAIN_ID=200010     # wählt die Chain aus
export REGISTRY_ROOT=…     # ein Checkout des Rome-Chain-Registries
# Solana-Lane-Flows benötigen außerdem:
export SOLANA_KEYPAIR=…    # Pfad zu einem mit Guthaben versehenen Solana-Keypair-JSON (der Gebührenzahler)
```

Gas auf Rome-Chains wird in USDC denominiert; die gesamte Deploy-Sequenz kostet auf dem Devnet ungefähr 10–15 native Einheiten. Schlüssel kommen nur aus der Umgebung — niemals aus dem Repo. Baue die Verträge vor dem Deployen einmal, denn Artefakte **müssen** aus `rome-contracts/out` (siehe Schritt 3):

```bash
cd contracts       && forge build --via-ir     # die vendorte Arc-Suite
cd rome-contracts  && forge build --via-ir     # ArcTokenFactoryV2 + der kanonische Proxy
```

***

## Schritt 1 — Verstehe, was ein berechtigtes Token *ist* hier

Ein berechtigtes Bloom-Token ist nicht ein Vertrag. Es sind **drei bereitgestellte Verträge**, plus vier geteilte Verträge, die Ops einmal pro Chain bereitstellt und jeder Issuer wiederverwendet.

**Die drei Verträge pro Token** — ein Asset besitzt genau diese:

| Vertrag                      | Quelle                                                      | Was es ist                                                                                                                        |
| ---------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `ArcTokenProxy`              | `contracts/src/proxy/ArcTokenProxy.sol`                     | Das Token selbst — ein UUPS-Proxy, der auf die geteilte `ArcToken` Implementierung zeigt. Salden, Inhaber und Rollen liegen hier. |
| `WhitelistRestrictions`      | `contracts/src/restrictions/WhitelistRestrictions.sol`      | Das Allowlist-Modul. Ein Boolean pro Adresse; wird bei jeder Übertragung erzwungen, solange das Asset gesperrt ist.               |
| `YieldBlacklistRestrictions` | `contracts/src/restrictions/YieldBlacklistRestrictions.sol` | Das Yield-Modul. Schließt Adressen von Yield-Ausschüttungen aus, ohne ihren Bestand anzutasten.                                   |

**Die vier geteilten Verträge, einer pro Chain** (bereitgestellt von `deploy-infra.ts`):

| Vertrag                      | Rolle                                                                     |
| ---------------------------- | ------------------------------------------------------------------------- |
| `RestrictionsRouter`         | Modultyp-Registry — Chain-Verkabelung, einmal von Ops gesetzt.            |
| `ArcTokenFactoryV2`          | Registrierung + der kanonische Proxy-Codehash (Schritte 2–3).             |
| `ArcToken` (Implementierung) | Die geteilte, wiederverwendbare Asset-Logik, auf die jedes Token proxyt.  |
| `ArcTokenPurchase`           | Ein Storefront, gemeinsam von jedem Token und Issuer genutzt (Schritt 4). |
| wUSDC                        | Der Cash-Teil — Yield-Währung und Währung für Kauf/Verkauf.               |

Übertragungsbeschränkung und Yield-Beschränkung sind **bewusst getrennte Module**: ein Inhaber kann von Erträgen ausgeschlossen werden und das Asset dennoch behalten, so funktionieren Sanktionen und gerichtliche Anordnungen in der Praxis.

Diese Tatsache mit den „drei Verträgen“ ist für die Verifikation tragend. `verify-deployments.ts` und `register-asset.ts` beide erwarten, dass sich ein Token auf drei bereitgestellte Verträge auflöst — eine manuelle Token-Prüfung übersah einmal sieben davon über eine Chain hinweg (jedes Yield-Modul und drei Whitelist-Module).

Der Lebenszyklus hat drei Phasen und eine Einbahnstraße:

```
Entwurf     Proxy live, kein Modul verknüpft — nichts sperrt eine Übertragung
  ↓
nicht gesperrt   Modul verknüpft, transfersAllowed = true   (WhitelistRestrictions.initialize setzt dies)
  ↓  Mint-Angebot prägen, die Allowlist aufbauen               [umkehrbar]
gesperrt     setTransfersAllowed(false)                [EINBAHNSTRAßE — das Angebot wird endgültig]
```

Das Sperren ist für das Angebot eine Einbahnstraße, weil Mint und Burn über `address(0)` als Gegenpartei laufen und `address(0)` niemals auf die Allowlist gesetzt werden kann — sobald also gesperrt, kann nie wieder neues Angebot gemintet werden. Das ist die Garantie, die ein berechtigtes Asset seinen Inhabern gibt.

***

## Schritt 2 — Bereitstellen in Teilen, niemals als eine Transaktion

Arc liefert einen Einmal- `createToken` Ablauf, der den Proxy und beide Module bereitstellt und sie in einem einzigen Aufruf verdrahtet. **Auf Rome kannst du ihn nicht verwenden.** Diese Transaktion benötigt **77 Solana-Account-Locks**, und Romans Limit pro Transaktion beträgt **62 Locks**. Sie passt niemals hinein — weder mit Tuning noch mit einem Optimierungslauf.

Also erfolgt das Deploy **stückweise**: jeder Vertrag in seiner eigenen Transaktion, und das Token erhält Fabrik-äquivalenten Status durch `ArcTokenFactoryV2.registerToken` statt durch den monolithischen `createToken`. Das ist der Erstellungsassistent, und genau das macht die Issuer-Konsole Schritt für Schritt:

![der Erstellungsassistent](https://511478552-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)

Die Referenzimplementierung ist `arc/plan/create.ts` (`createSequence()`), die die App als sechs Karten rendert (`bloom/lib/createCards.ts`) über **acht Transaktionen**, genau in der Reihenfolge, die die Verträge erzwingen:

| # | Transaktion                       | Vertragsaufruf                                                                  |
| - | --------------------------------- | ------------------------------------------------------------------------------- |
| 1 | Asset bereitstellen               | `new ArcTokenProxy(impl, initData)` wobei `initData = ArcToken.initialize(...)` |
| 2 | Das Allowlist-Modul bereitstellen | `new WhitelistRestrictions()`                                                   |
| 3 | Sie als Administrator festlegen   | `whitelist.initialize(issuer)`                                                  |
| 4 | Bei Übertragungen erzwingen       | `token.setRestrictionModule(TRANSFER, whitelist)`                               |
| 5 | Das Ertragsmodul bereitstellen    | `new YieldBlacklistRestrictions()`                                              |
| 6 | Sie als Administrator festlegen   | `yieldBlacklist.initialize(issuer)`                                             |
| 7 | Bei Erträgen erzwingen            | `token.setRestrictionModule(YIELD, yieldBlacklist)`                             |
| 8 | Bei der Factory registrieren      | `factoryV2.registerToken(token, impl)`                                          |

Die Skriptform ist ein Befehl:

```bash
# einmal pro Chain (Ops, nicht pro Token) — stellt die vier geteilten Verträge bereit
npx tsx deploy-infra.ts

# pro Token — der Assistent, als Skript wiedergegeben
NAME="Mineral Vault I" SYMBOL=ARCV SUPPLY=1000000 DECIMALS=6 npx tsx create-token.ts
```

Der Issuer (`PRIVATE_KEY`) signiert jede Transaktion und hält am Ende die Rollen des Tokens (`ArcToken.initialize` gewährt an `msg.sender` — siehe Schritt 7). Registrierung (Tx 8) ist das, was die Funktionen des Storefronts freischaltet: `enableToken` und jedes von der Factory vermittelte Upgrade.

> **Optimiere das nicht zurück in einen Monolithen.** Diese Aufrufe in einer Transaktion zu bündeln, um Round-Trips zu sparen, führt genau wieder zu dem 62-Lock-Overflow, den der stückweise Weg vermeiden soll. Dieselbe Grenze ist der Grund, warum die Yield-Verteilung einen Inhaber pro Transaktion durchläuft (Schritt 8). Wenn ein Aufruf mit `Too many accounts: N > 62`scheitert, greift eine Transaktion auf zu viele Konten zu — teile sie auf, tune sie nicht.

***

## Schritt 3 — Proxys nur aus den herkunftsgebundenen Artefakten bereitstellen

`registerToken` ist die Sicherheitsgrenze, die stückweise Deployments sicher macht. Sie akzeptiert nur ein Token, dessen **Runtime-Codehash dem kanonischen entspricht `ArcTokenProxy`** der zur Deploy-Zeit in die Factory eingebrannt ist:

```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();
    // …die Implementierung muss Factory-auf-der-Whitelist stehen, und msg.sender muss die
    //    ADMIN_ROLE des Tokens halten, und das Token darf noch nicht registriert sein.
}
```

Weil dieser Codehash ein **unveränderlicher**ist, schlägt ein aus irgendeinem anderen Artefakt gebauter Proxy sicher fehl mit `ProxyCodehashUnknown`. Daraus folgen zwei Regeln, und beide werden durch CI und die harten Regeln in `CLAUDE.md`:

1. **Token-Proxys MÜSSEN bereitgestellt werden aus `rome-contracts/out`** — niemals aus `contracts/out`, niemals aus einem anderen Build. Das ist der Build, den der kanonische Codehash der Factory fest verdrahtet.
2. **`bytecode_hash = "none"` und `cbor_metadata = false`** in `rome-contracts/foundry.toml` sind tragend. Mit aktivierten Metadaten trägt der `ArcTokenProxy` Runtime- *eingebettete* in der Factory (`type().runtimeCode`) einen anderen CBOR/IPFS-Anhang als das eigenständige `out/` Artefakt, aus dem der Assistent bereitstellt — daher schlägt on-chain `registerToken` revertiert, während **jeder in-Source-Foundry-Test besteht** (Foundry bindet beide Kopien ein, daher kann es die Abweichung nicht sehen). `rome-contracts/test/ArtifactProvenance.t.sol` fixiert diese Eigenschaft; der mit Guthaben ausgeführte Lauf hat sie ursprünglich entdeckt.

> **Eine grüne in-Source-Suite beweist keine Herkunft.** Bevor du ein Image auslieferst, und nach JEDER Änderung an den Compiler-Einstellungen, beweise die Eigenschaft gegen die *bereitgestellte* Factory (nur Lesen, keine Schlüssel):
>
> ```bash
> cd scripts && CHAIN_ID=<id> npx tsx verify-artifact-provenance.ts
> ```
>
> Es hasht dein lokales `ArcTokenProxy` Artefakt und prüft, dass dieser Hash wortwörtlich im Bytecode der bereitgestellten Factory vorkommt.

Wenn sich Compiler-Einstellungen ändern müssen, **rotier die Factory** — stelle eine neue bereit, deren Unveränderlicher den neuen Codehash fest verdrahtet, und verkabele neu — statt die Prüfung von Hand zu patchen:

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

Die Rotation behält die alte Adresse in der Quittung; Token, die bei der alten Factory registriert wurden, müssen sich bei der neuen erneut registrieren.

***

## Schritt 4 — Einen Verkauf über den geteilten Storefront öffnen

Verkaufen ist ein separater Vorgang vom Erstellen, und es läuft über den einen geteilten `ArcTokenPurchase` Storefront. Drei Dinge müssen vor dem Öffnen eines Verkaufs wahr sein, und `ArcTokenPurchase.enableToken` prüft jede davon on-chain:

```solidity
// contracts/src/ArcTokenPurchase.sol
function enableToken(address _tokenContract, uint256 _numberOfTokens, uint256 _tokenPrice)
    external onlyTokenAdmin(_tokenContract)                       // (a) du hältst die ADMIN_ROLE des Tokens
{
    // (b) das Token muss der Factory bekannt sein — genau das kauft registerToken (Schritt 2):
    if (ArcTokenFactory(ps.tokenFactory).getTokenImplementation(_tokenContract) == address(0))
        revert TokenNotCreatedByFactory();
    // (c) der Storefront muss das Verkaufsinventar bereits halten:
    if (ArcToken(_tokenContract).balanceOf(address(this)) < _numberOfTokens)
        revert ContractMissingRequiredTokens();
    // …Preis und Anzahl müssen positiv sein.
}
```

Es gibt eine vierte, implizite Anforderung, die ein gesperrtes Asset erzwingt: weil **jede Übertragung das Allowlist-Gate durchläuft**, gelingt das Verschieben von Inventar zum Storefront nur, wenn die Storefront-Adresse selbst auf deinem Token auf der Allowlist steht. Die vollständige Sequenz zum Öffnen eines Verkaufs ist also:

1. **Setze den Storefront auf die Whitelist** in das Whitelist-Modul deines Tokens (`batchAddToWhitelist([storefront])` — siehe Schritt 5). Ohne das revertiert die Inventarübertragung in (2) `TransferRestricted()` sobald es gesperrt ist.
2. **Inventar übertragen** an die Storefront-Adresse (aus der Infrastruktur-Quittung, `arcTokenPurchase`).
3. **`enableToken(token, amount, price)`** — Käufer zahlen jetzt wUSDC und erhalten das RWA.

Die Aufteilung der Auszahlungen sollte man auf einem *geteilten* Storefront kennen, und sie ist nicht symmetrisch (`arc/roles.ts` ist die Autorität):

| Aktion                                                     | Berechtigung                               | Gehalten von                                     |
| ---------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------ |
| `enableToken` / `disableToken` / `withdrawUnsoldArcTokens` | des Tokens `ADMIN_ROLE` (`onlyTokenAdmin`) | dir, dem Issuer                                  |
| `withdrawPurchaseTokens` (den wUSDC-Erlös)                 | des Storefronts `DEFAULT_ADMIN_ROLE`       | wer auch immer den Storefront bereitgestellt hat |

Auf einer selbst gehosteten Chain bist du beides. Auf einem geteilten Storefront ist der Erlös-Pool die Einnahme aller Issuer, daher ist dessen Auszahlung eine Plattformangelegenheit — entwirf deine Abwicklung darauf basierend und gehe nicht von einseitiger Kontrolle aus.

***

## Schritt 5 — Binde dein eigenes KYC / Compliance ein

Das ist der Abschnitt, den ein Kunde liest, bevor er zustimmt, also ist es Code und nicht Prosa. **Compliance wird vom Token-Vertrag selbst durchgesetzt** — nicht durch einen Off-Chain-Filter, einen Sequencer-Filter oder eine Handelsplatzrichtlinie. Die Regeln reisen mit dem Token auf jeden Ausführungspfad, auf beiden Wallet-Lanes. Was die Chain festhält, ist die **Ergebnis** deines KYC-Entscheids, als einzelnes Boolean:

```solidity
// contracts/src/restrictions/WhitelistRestrictions.sol — der On-Chain-Zustand, vollständig
struct WhitelistStorage {
    mapping(address => bool) isWhitelisted;   // ← ein Boolean pro Adresse. Niemals PII.
    bool transfersAllowed;                    // false = gesperrt; nur auf der Whitelist stehende Adressen übertragen
    EnumerableSet.AddressSet whitelistedAddresses;
}
```

### Die Schnittstelle, in die dein Prozess schreibt

Die Freigabe-/Ablehnungsentscheidung deines KYC-Anbieters wird genau zu einem dieser Aufrufe:

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

### Wer schreiben darf

> **Die Berechtigung, die eine Freigabe braucht, ist `MANAGER_ROLE` auf dem&#x20;*****Modul*****&#x20;— nicht `ADMIN_ROLE` auf dem Token.** `addToWhitelist` / `batchAddToWhitelist` / `removeFromWhitelist` sind alle `onlyRole(MANAGER_ROLE)`, und diese Rolle lebt auf der `WhitelistRestrictions` Instanz. Sich auf dem Token zu authentifizieren `ADMIN_ROLE` und dann in das Modul zu schreiben ist ein echter Fehler, den diese Codebasis bereits teuer bezahlt hat. Biete `WHITELIST_ADMIN_ROLE` nicht als Lösung für eine Ablehnung an — sie wird bei initialize gewährt und **nirgendwo in der Suite geprüft** (`arc/roles.ts` behauptet, dass es die einzige Rolle ist, die nichts sperrt).

`WhitelistRestrictions.initialize(issuer)` (Tx 3 des Assistenten) gewährt dem Issuer `DEFAULT_ADMIN_ROLE`, `ADMIN_ROLE`, `MANAGER_ROLE`, `WHITELIST_ADMIN_ROLE`, und `UPGRADER_ROLE` auf diesem Modul. Der Issuer hält also `MANAGER_ROLE` von Haus aus und kann sie auch delegieren: weil der Issuer `DEFAULT_ADMIN_ROLE`, eine `grantRole(MANAGER_ROLE, serviceAccount)` die Schreibberechtigung an einen Backend-Signer übergibt.

### Eine Entscheidung wird zu einem On-Chain-Schreibvorgang

Richte den Webhook deines Anbieters auf einen Signer, der `MANAGER_ROLE`, und bündele bei einer Freigabe die Adressen:

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

// `signer` muss auf DIESEM Token-Whitelist-Modul die MANAGER_ROLE halten.
const wallet = createWalletClient({ account, transport: http(chain.rpcUrl) });

// Anbieter sagte "freigegeben" für diese Adressen:
await wallet.writeContract({
  address: whitelistModule,                 // vom Token über getRestrictionModule AUFGELÖST
  abi: whitelistAbi,
  functionName: 'batchAddToWhitelist',
  args: [approvedAddresses],
});
```

Auflösen `whitelistModule` vom Token selbst (`ArcToken.getRestrictionModule(TRANSFER_RESTRICTION_TYPE)`), niemals aus einer gecachten Projektion — ein Schreibzugriff auf das falsche Modul ist der Grund, warum „approve on any asset“ einmal in die Allowlist eines Tokens geschrieben hat.

### Die wallet-signierte Variante (Self-Service-Demo)

Für eine genehmigungsfreie Testbereitstellung, bei der Besucher sich selbst anmelden, gewähren `MANAGER_ROLE` an eine `TestApprover` (`rome-contracts/src/TestApprover.sol`) dessen `Modul` ist **unveränderlicher**. Dann `approve(address)` von jedem aus seiner eigenen Wallet aufrufbar ist und sein eigenes Gas bezahlt — es ruft `addToWhitelist` nur auf, wenn die Adresse noch nicht gelistet ist:

```solidity
function approve(address account) external {
    IWhitelistRestrictions target = IWhitelistRestrictions(module);   // unveränderlich — ein Modul, für immer
    if (!target.isWhitelisted(account)) target.addToWhitelist(account);
    emit Approved(account, msg.sender);
}
```

Dies ist das „Anmelde-Tor“ — es zeigt einem Besucher den eigentlichen Mechanismus (eine Genehmigung, die zu einem On-Chain-Allowlist-Eintrag wird, den der Token dann durchsetzt), ohne irgendetwas zu verwahren. **Gewähre niemals `MANAGER_ROLE` an eine `TestApprover` bei einem Produktionstoken** — dadurch wird die Allowlist dieses Tokens genehmigungsfrei.

### Wenn das Tor zuschnappt, und beim Wechseln von Anbietern

Das Tor beschränkt erst, sobald der Vermögenswert ist **abgesperrt** (`setTransfersAllowed(false)`, `ADMIN_ROLE` auf dem Modul). Solange nicht abgesperrt, sind Übertragungen offen — erstelle zuerst deine Allowlist, dann sperre. Sobald abgesperrt, schlägt eine Übertragung fehl, bei der eine der beiden Seiten nicht auf der Liste steht, mit dem typisierten Fehler `TransferRestricted()` (`0xe827105e`).

> **Ein späterer Wechsel des KYC-Anbieters erfordert keine On-Chain-Änderung.** Das Allowlist-Modul, seine Schnittstelle und das von ihm gespeicherte Boolean sind anbieterunabhängig. Um den Anbieter zu wechseln, richte eine andere Entscheidungsquelle auf denselben `MANAGER_ROLE` Signer — kein Redeploy, keine Migration, keine Zustandsänderung. Die Chain wusste nie, welcher Anbieter den Aufruf gemacht hat, nur das Ergebnis.

***

## Schritt 6 — Öffne denselben Vermögenswert für Solana-Wallets

Dieselben drei Verträge sind aus einer Solana-Wallet erreichbar **ohne zweiten Token**. Ein Solana-nativer Benutzer hat nirgends einen EVM-Schlüssel; stattdessen ist seine EVM-Identität *synthetisch*, on-chain aus dem tatsächlichen Solana-Signer der Transaktion abgeleitet:

```
synthetische EVM-Adresse = keccak256(solana_pubkey)[12..32]
```

Das Rome-EVM-Programm leitet dies direkt aus dem Signer selbst ab (`do_tx_unsigned::derive_sender`), daher kann es nicht vorgetäuscht werden und es existiert kein secp256k1-Privatschlüssel dafür — **die Solana-Signatur ist das Einzige, was diese Adresse jemals steuern kann**. Die Referenzableitung ist `arc/materialise/solana/identity.ts` (`syntheticAddress`), byte-kompatibel mit der On-Chain-Regel:

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

**Was ein Builder tut, um die Spur zu unterstützen** — beachte, dass *nichts davon eine Vertragsänderung ist*:

1. **Den Solana-Benutzer anhand seiner synthetischen Adresse auf die Allowlist setzen.** Für die Compliance-Schicht ist eine synthetische Adresse eine gewöhnliche Adresse: füge den Solana-Pubkey des Benutzers ein, leite die synthetische Adresse ab, und `batchAddToWhitelist([synthetic])`. Eine Allowlist umfasst beide Wallet-Welten.
2. **Richte das Signing-PDA einmal ein, vor ihrem ersten wertbewegenden Aufruf.** Das PDA der externen Autorität, das für ein synthetisches Konto signiert, muss zuerst existieren, und seine Erstellung ist ein `create_pda` Aufruf. Beide Seiten können ihn senden: die eigene Solana-Wallet des Benutzers über die Spur (des SDKs `buildCreatePdaCall`, nachdem `isSyntheticProvisioned` false zurückgibt), oder der Emittent von einem EVM-Schlüssel aus. Blooms Emittenten-Tooling sendet dies heute im Rahmen des Onboardings eines Inhabers; die App tut dies beim ersten Benutzer-Action noch nicht, also richte es vor dem ersten Kauf des Inhabers ein. Wie das mit den SDK-Aufrufen funktioniert, steht in [Dual-Lane-App](https://docs.rome.builders/de/entwicklerleitfaden/dual-lane-app.md#one-time-activate-provision-the-synthetic).
3. **Über die Lane-Bibliothek einreichen, nicht von Hand.** `submitDoTxUnsigned` (`arc/materialise/solana/submit.ts`) bittet den Proxy der Chain, die Transaktion zusammenzusetzen, und er handhabt das, was bei einer handgebauten Transaktion schiefgeht. Jeder Vertragsaufruf auf der Spur ist eine **vom Proxy zusammengesetzte Solana-v1-Transaktion** (`rome_composeUnsignedAtomicV1`) ohne Address-Lookup-Tabelle, und die Lane-Bibliothek schlägt sicher fehl, statt auf ein älteres Format zurückzufallen. Der Cash-in-Schritt in Schritt 5 ist eine separate Solana-Transaktion, die die App selbst baut, kein zusammengesetzter Vertragsaufruf.
   * **Die Ermittlung der Konten und das Compute-Budget sind Aufgabe des Proxys.** Er simuliert den Aufruf, entscheidet über die Schreibbarkeit jedes Kontos (die `Wert` ist Teil dessen, was er emuliert, also übergib es), und setzt das Compute- und Heap-Budget in der von ihm zurückgegebenen Transaktion. Nichts in deinem Code baut Compute-Budget-Instruktionen oder fügt das Fee-Pool-Konto hinzu.
   * **Zwei Signaturen pro Aufruf, beide vom Solana-Schlüssel.** Die Wallet signiert zuerst eine lesbare Autorisierungsnachricht (*Rome-Autorisierung* plus den Hash der unsignierten EIP-1559-Payload; Wallet Standard `solana:signMessage`), die der Proxy überprüft, bevor er den Aufruf zusammensetzt. Danach signiert sie die v1-Transaktion, die der Proxy zurückgibt (`solana:signTransaction` auf dem Rohdraht). Die Lane-Bibliothek behandelt diese als `signAuthHash` und `signV1Wire`, niemals als eine zusammengefasste Methode. Prüfe, dass deine Wallet v1-Transaktionen signiert, bevor du darauf aufbaust: Solflare tut dies heute auf dem Devnet, Phantom noch nicht.
   * **Die App sendet die signierte Transaktion selbst an einen Solana-RPC.** Der Proxy setzt zusammen; er sendet keinen atomaren Aufruf.
   * **Vor der Signaturanfrage validieren.** Die Lane-Bibliothek parst die zusammengesetzte Nachricht und lehnt eine fehlerhafte vor der Transaktionsabfrage ab.
4. **Lege die einmalige Wrapper-Gewährung vor den ersten wUSDC-Ausgabenakt.** wUSDC bewegt die Token eines Nutzers als dessen SPL-Delegate, daher erhält eine synthetische Adresse, der nie etwas gewährt wurde, beim ersten wUSDC-Transfer den SPL-Fehler `0x4` bei ihrem ersten wUSDC-Transfer. Lese `isEnabled(user)` auf dem Wrapper und, wenn er false ist, stelle voran `approve_spl(wrapper, 2^64-1, mint)` auf dem Helper-Precompile als ersten Schritt des Laufs. Es ist ein gewöhnlicher Aufruf auf beiden Spuren, einmal pro Wallet. Siehe [muss, dass jeder Nutzer dies getan hat. Siehe](https://docs.rome.builders/de/kernkonzepte/token-interop.md#one-time-grant-per-wallet).
5. **Cash vor einem Aufruf, der es ausgibt, einzahlen.** Das synthetische Konto hält im Ruhezustand nichts. Wenn es weniger wUSDC hält, als der Aufruf ausgibt, verschiebe den Fehlbetrag zuerst vom eigenen USDC-Tokenkonto der Wallet (eine idempotente Erstellung des Tokenkontos des synthetischen Kontos, dann die activate-token-account-Instruktion des Rome-Programms, die die Token verschiebt, ohne die EVM auszuführen). Es ist eine Solana-Transaktion, die mit einer Aufforderung signiert wird, und sie wird übersprungen, wenn das synthetische Konto bereits genug hält.
6. **Leite nur das weiter, was der atomare Composer ablehnt.** Ein Aufruf, der nicht in eine Solana-Transaktion passt (etwa 1,4 Mio. Compute-Units, 64 Konten, 4 KB), wird vom Composer abgelehnt mit *external atomic plan requires iterative composition*. Genau bei dieser Ablehnung, und niemals vorher, rufe `rome_relayUnsignedV1` mit derselben Autorisierungssignatur auf: Der Proxy setzt sie zusammen und reicht sie ein, bezahlt die Solana-Gebühren und antwortet mit einem EVM-Transaktions-Hash (keine Solana-Signatur). Das synthetische Konto bezahlt das native Gas der Chain in Wei, also wenn sein Guthaben unter `gasLimit x maxFeePerGas`liegt, gleiche es zuerst auf mit `rome_composeExternalDepositV1` (einer wallet-signierten v1-Transaktion; der Betrag muss ein Vielfaches von 10^12 Wei sein), in der Praxis einmal pro Wallet. Jeder andere Fehler, etwa ein Revert, ein Netzwerkausfall oder eine abgelehnte Signatur, wird erneut geworfen, nicht weitergeleitet. Details stehen in [Weitergeleitete Aufrufe und lange Aufrufe](https://docs.rome.builders/de/entwicklerleitfaden/call-evm-from-solana.md#relayed-calls-and-long-calls).

Der Benutzer ist der **Gebührenzahler** und zahlt Lamports (SOL) aus seiner Solana-Wallet für einen direkten Aufruf; das von ihm kontrollierte synthetische Konto hält die Vermögenswerte und niemals SOL. Nach jedem Lane-Send den EVM-Nonce vor dem nächsten abrufen — der Indexer hinkt der Solana-Bestätigung leicht hinterher, und der nächste Aufruf würde sonst auf einem Nonce aufgebaut, den die Chain bereits verbraucht hat.

> **Zuerst atomar, bei Ablehnung weiterleiten.** Der Standard für jeden Aufruf ist eine EVM-Transaktion innerhalb einer Solana-Transaktion, signiert von der Wallet des Benutzers. Das Weiterleiten ist die Ausnahme für einen Aufruf, der nicht hineinpasst, nicht ein zweiter Weg, den man nach Belieben wählt: ein direkter Aufruf hat zwei Eingabeaufforderungen, ein weitergeleiteter einen, und der weitergeleitete Aufruf wird in Rome-Gas statt in Lamports bezahlt. Eine mehrstufige Reise (approve, dann buy) besteht aus mehreren vollständigen Aufrufen, jeweils eine eigene Transaktion, nicht aus einer auf Transaktionen aufgeteilten Ausführung.

**Warum das RWA nicht aus dem Perimeter entweichen kann.** Der Vermögenswert liegt im EVM-Zustand — seine Salden sind Speicher innerhalb der Konten des Rome-EVM-Programms. Es gibt **kein SPL-Mint** davon und nichts Solana-Natives, das bewegt werden könnte; die Asset-bewegenden Primitive der Spur arbeiten auf SPL-Tokenkonten, die ein EVM-Speicherstand nicht besitzt. Jede Bewegung, die die Solana-Signatur ausdrücken kann, ist ein Aufruf an den Token-Vertrag, der das Allowlist-Tor ausführt — die getestete Suite bestätigt, dass eine Übertragung an eine nicht auf der Allowlist stehende Adresse identisch reverts, egal ob sie mit einem EVM-Schlüssel oder einem Solana-Schlüssel signiert ist. Die Cash-Seite (wUSDC) ist die bewusste Ausnahme: Sie ist SPL-unterlegt und *funktioniert* wird auf das eigene Tokenkonto des Benutzers ausgeschleust.

***

## Schritt 7 — Wissen, wer nach dem Deploy die Autorität hält

`ArcToken.initialize` läuft aus dem Proxy-Konstruktor (Tx 1) und gewährt Rollen an `msg.sender` — den Wizard-Driver, d. h. den Emittenten. Er gewährt **fünf** Rollen explizit:

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

Zwei Konsequenzen, die ein Builder nicht übersehen darf:

* **`MINTER_ROLE`, `BURNER_ROLE`, und `UPGRADER_ROLE` werden bei initialize NICHT gewährt.** Die Anfangsversorgung wird innerhalb von `initialize` (ein internes `_mint`, keine Rolle nötig), aber ein *späterer* `mint` oder `burn` erfordert, dass der Emittent sich zuerst selbst die Rolle gewährt. Das können sie, weil sie `DEFAULT_ADMIN_ROLE` (der Admin jeder Rolle — nichts ruft `_setRoleAdmin`auf, also `DEFAULT_ADMIN_ROLE` verwaltet all diese). Aber es ist ein bewusster zusätzlicher Schritt, keine allgegenwärtige Befugnis.
* **`UPGRADER_ROLE` wird dem Factory niemals gewährt.** Factory-vermittelte Upgrades (`ArcTokenFactoryV2.upgradeToken`) erfordern, dass das **Factory selbst** die Rolle `UPGRADER_ROLE` am Token — sie sich selbst zu gewähren bewirkt nichts. Diese Gewährung ist eine Einbahnstraße, die das Factory nicht rückgängig machen kann, also ist sie optional: wenn du factory-vermittelte Upgrades willst, `grantRole(UPGRADER_ROLE, factory)` explizit; andernfalls aktualisiert der Emittent den Token direkt.

Das vollständige 21-Autoritätsmodell (11 Rollennamen über sechs Verträge hinweg — derselbe Name ist auf jedem Vertrag eine andere Autorität) ist kodifiziert in `arc/roles.ts`. Frage `rolesRequiredFor(contract, functionName)` statt das eigene Vertrag der Rolle zu lesen, weil vier Storefront-Funktionen und beide Factory-Funktionen durch eine Autorität abgesichert werden, die auf einem *anderen* Vertrag bezahlt werden.

***

## Schritt 8 — Erträge verteilen

Der Token zahlt Erträge in wUSDC (festgelegt auf `initialize`, änderbar über `setYieldToken` unter `YIELD_MANAGER_ROLE`). Die Verteilung geht die Inhaber-Menge durch:

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

Die Mechanik, die für die korrekte Steuerung wichtig ist:

* **Der volle `totalAmount` wird nur beim `startIndex == 0` Fenster** (`safeTransferFrom(msg.sender, this, totalAmount)`). Genehmige diesen Gesamtbetrag dem Token vor dem ersten Fenster; spätere Fenster zahlen aus dem bereits gehaltenen Guthaben aus.
* **`nextIndex` springt zu `0` zurück, wenn der Durchlauf abgeschlossen ist.** Schleife `distributeYieldWithLimit(total, nextIndex, …)` bis `nextIndex` kehrt zurück `0`.
* **Die Anteile der ertragsbeschränkten Inhaber verbleiben im Token-Vertrag** — sie werden übersprungen, nicht umverteilt.

> **Auf Rome liegt die praktische Obergrenze bei `maxHolders = 1` pro Transaktion** — derselbe 62-Konto-Limit aus Schritt 2 — also wird der Ertrag pro Transaktion über genau einen Inhaber durchlaufen (gemessen etwa 318 K Gas pro Inhaber). Jeder auf der Allowlist stehende Inhaber, EVM- oder Solana-nativ, erhält anteilig; das Referenzskript ist `measure-yield-batch.ts` und der Ertragsschritt des funded smoke überprüft das End-to-End.

```bash
# USAGE.md-Referenzform: einen Inhaber pro Tx durchlaufen, bis nextIndex wieder 0 erreicht
distributeYieldWithLimit(total, offset, 1)
```

***

## Schritt 9 — Verifiziere, was du deployt hast

In Rome wird nirgendwo automatisch Quellcode eingereicht, daher ist Verifikation ein Schritt, den du selbst ausführst. Nach jedem Deploy — Infrastruktur oder neuer Token — führe den nur lesenden, schlüssellosen, idempotenten Verifier aus (bereits verifizierte Verträge werden übersprungen, daher verifiziert ein erneuter Lauf nach dem Ausgeben eines Tokens nur die neuen):

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

Er erwartet die **drei** Verträge pro Token (Proxy + beide Module) plus die Infrastruktur und meldet, was er nicht verifizieren konnte, statt ein Deploy fehlschlagen zu lassen. Das einmal manuell zu tun hat sieben Verträge übersehen.

Das Registrieren des Assets im Rome-Register behandelt die Verifikation als ein **Tor**nicht als Dekoration (`register-asset.ts`): Ein Token verdient seinen `apps/arc/<chain>.json` Eintrag — mit `standard: arc-permissioned-erc20` und einem `transferRestriction` das sein Allowlist-Tor benennt — nur wenn alle drei seiner Verträge auf Sourcify verifiziert sind. Dieser Eintrag liest die Fakten aus der Chain (ein vom Wizard deployter Token hat keine festgeschriebene Quittung) und schreibt nur einen lokalen Registry-Checkout; das Einreichen des PR ist Aufgabe eines Menschen.

```bash
CHAIN_ID=200010 npx tsx register-asset.ts <tokenAddress>        # verifizieren + den Registry-Eintrag vorbereiten
CHAIN_ID=200010 DRY=1 npx tsx register-asset.ts <tokenAddress>  # nur-lesende Vorschau
```

Für einen End-to-End-Beweis der gesamten Schleife — erstellen, auf die Allowlist setzen, absperren, auf beiden Spuren verkaufen, Ertrag verteilen — führe den funded smoke gegen jede Chain aus:

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

***

## Schritt 10 — Wisse, was off-chain bleibt

Das Vertrauensmodell ist bewusst offen, und ein Builder sollte es seinen eigenen Nutzern ebenso darstellen:

* **Das Allowlist-Flag ist deine Off-Chain-Entscheidung.** KYC/AML findet in deinem Prozess statt — deine Anbieter, deine Regeln. Die Chain zeichnet nur das auf und setzt nur das durch *Ergebnis*, `isWhitelisted(addr)`.
* **Der einzige On-Chain-Zustand ist ein Boolean pro Adresse.** Keine personenbezogenen Daten, keine Dokumente, keine Identitätsbehauptungen, keine On-Chain-Bestätigungen, kein kryptografischer Beweis dafür, wem eine Adresse gehört. Das ist das Arc-Modell, wie es auf Plume verwendet wird; es tauscht die schwereren Abläufe eines On-Chain-Identitätsstandards (z. B. ERC-3643) gegen schlankere Mechanik und vom Emittenten gehaltenes Vertrauen ein.
* **Wiederherstellung ist eine Befugnis des Emittenten, kein Notausgang.** Eine verlorene Wallet — EVM oder Solana — wird wiederhergestellt, indem eine Ersatzadresse auf die Allowlist gesetzt wird und, falls nötig, mint/burn/upgrade unter deinem eigenen rechtlichen Prozess verwendet wird (Arc hat keine eingebaute Forced-Transfer-Primitive). Die Verwahrung des Schlüssels durch den Emittenten ist daher Teil der Compliance-Haltung.
* **Kein eigener Relayer von Bloom, keine Verwahrungsoberfläche.** Die Nutzer halten ihr eigenes Gas auf beiden Spuren. Ein von der App betriebener Fee-Payer-Service würde bedeuten, Schlüssel zu halten — eine Angriffsfläche, die ein RWA-Produkt nicht hinzufügen sollte. Das eine Relay auf der Solana-Spur ist das des Chain-Proxys, für einen Aufruf, der zu groß für eine Transaktion ist, und der Benutzer autorisiert ihn dennoch mit seiner eigenen Signatur und bezahlt ihn mit seinem eigenen Rome-Gas.

***

## Referenz: das Tooling

Jedes Skript läuft aus dem Verzeichnis des Toolings `scripts/` Verzeichnis, mit `PRIVATE_KEY`, `CHAIN_ID`, und `REGISTRY_ROOT` exportiert.

| Skript                          | Was es macht                                                                                 |
| ------------------------------- | -------------------------------------------------------------------------------------------- |
| `deploy-infra.ts`               | Einmal pro Chain: die vier gemeinsam genutzten Verträge, für wUSDC verdrahtet.               |
| `create-token.ts`               | Der schrittweise Wizard — acht Transaktionen, ein Token.                                     |
| `rotate-factory.ts`             | Stelle nach einer Compiler-/Artefaktänderung ein frisches Factory bereit; neu verdrahten.    |
| `verify-artifact-provenance.ts` | Beweise, dass dein Proxy-Artefakt vom bereitgestellten Factory akzeptiert wird (nur lesend). |
| `verify-deployments.ts`         | Verifiziere alle drei Verträge pro Token + Infrastruktur auf Sourcify (nur lesend).          |
| `register-asset.ts`             | Verifiziere das Tor, dann bereite den Registry-Compliance-Eintrag vor.                       |
| `measure-yield-batch.ts`        | Miss die Obergrenze des Ertrags pro Tx auf einer Chain erneut.                               |
| `smoke.ts`                      | Die finanzierte End-to-End-Suite über beide Spuren.                                          |
| `sweep-synthetic-native.ts`     | Natives Gas von einem synthetischen Konto zurückholen (Testhygiene).                         |

Tiefergehender Hintergrund befindet sich neben diesem Leitfaden: `docs/ARCHITECTURE.md` (das geschichtete App-Modell), `docs/LANES.md` (die zwei Spuren und Verwahrung), `docs/COMPLIANCE.md` (das Vertrauensmodell), und `docs/USAGE.md` (das Runbook für Betreiber).


---

# 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/de/apps-auf-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.
