> 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/tr/rome-uzerindeki-uygulamalar/bloom/building.md).

# Bloom üzerinde geliştirme

Bu kılavuz tek bir soruyu yanıtlıyor: **bir geliştirici bunu nasıl kendi başına yapar?** Bir Solidity gerçek dünya varlığı sözleşmesi alın, onu bir Rome zincirinde izinli bir token olarak ayağa kaldırın, ikinci bir token olmadan hem Solana cüzdanlarına hem de EVM cüzdanlarına açın ve kendi KYC/uyumluluk kararınızı ekleyin.

Hedef kitle, yaklaşımı değerlendiren veya benimseyen bir geliştiricidir. Bloom boyunca işlenmiş örnektir — onun canlı varlığı **ARCV ("Mineral Vault I")** Hadrian üzerinde (`200010`) aşağıdaki her adımın gerçek bir örneğidir ve dağıtım makbuzu (`deployments/200010.tokens/ARCV.json`) bu yöntemin ürettiği tam üç sözleşmeyi ve sekiz işlemi kaydeder.

Burada hiçbir şey varlık sözleşmelerini değiştirmez. Bloom, Plume'un Arc çerçevesini çalıştırır **değiştirilmeden** (içe alınmış ağaç yapısı `contracts/`, bayt düzeyinde birebir aynı `plumenetwork/contracts` şu sabitlemedeki `NOTICE`); Roma tarafındaki tek sözleşme `ArcTokenFactoryV2`, bu da bir işlev ekler. Asıl iş *nasıl* sizin dağıttığınız ve *nasıl* sözleşmeleri sizin yönettiğinizdir — onları değiştirmekte değil.

> **Yönteme hızlı bir bakış.** İzinli bir token **üç** dağıtılmış sözleşmeden oluşur. Şu şekilde dağıtılır: **parça parça** — işlem başına bir sözleşme — çünkü tek işlemde yapılan bir factory çağrısı Roma'nın işlem başına hesap sınırını aşar. Proxy'leri şuradan gelmelidir: **kökeni kilitli artefaktlar** yoksa zincir üzeri kayıt başarısız olur. Uyumluluk, her adres için bir **boolean'dır**, KYC sürecinizin yetkilendirdiği kişi tarafından yazılır. Ve aynı dağıtım, bir Solana cüzdanından bir **sentetik gönderen** üzerinden zincir içinde türetilerek erişilebilir — ikinci token yok, ikinci allowlist yok.

## Ön koşullar

> **Başlamadan önce.** Bu kılavuzun kullandığı ihraççı araçları henüz yayımlanmadı. Buna şu betikler de dahil:`deploy-infra.ts`, `create-token.ts` ve diğerleri), `contracts/` ve `rome-contracts/` ağaçları ve adını verdiği dağıtım makbuzları. İhraççılar bu araçları Rome ile onboarding yaparak alır. O zamana kadar kılavuzu, yöntemin ve her betiğin ne yaptığının bir açıklaması olarak okuyun.

Referans araçları bir `scripts/` dizinde bulunur (onboarding sırasında sağlanır; bağımlılıklarını `npm install`) ile kurun. Her komut, zincir bilgilerini sabitlemek yerine kayıt defterinden çözer; bu yüzden başka bir Rome zincirine yönlendirmek kod değişikliği değil, ortam değişikliğidir:

```bash
export PRIVATE_KEY=…       # hedef zincirde fonlanmış dağıtıcı/ihraççı anahtarı
export CHAIN_ID=200010     # zinciri seçer
export REGISTRY_ROOT=…     # Rome zincir kayıt defterinin bir checkout'u
# Solana hattı akışları ayrıca şunu gerektirir:
export SOLANA_KEYPAIR=…    # fonlu bir Solana anahtar çifti JSON'una yol (ücret ödeyen)
```

Rome zincirlerinde gas USDC cinsindendir; tam dağıtım dizisi devnet'te yaklaşık 10–15 yerel birim tutar. Anahtarlar yalnızca ortamdan gelir — asla depodan değil. Dağıtmadan önce sözleşmeleri bir kez derleyin, çünkü artefaktlar **mutlaka** şuradan gelmelidir: `rome-contracts/out` (bkz. adım 3):

```bash
cd contracts       && forge build --via-ir     # içe alınmış Arc paketi
cd rome-contracts  && forge build --via-ir     # ArcTokenFactoryV2 + kanonik proxy
```

***

## Adım 1 — İzinli bir tokenın ne olduğunu bilin *şu* burada

İzinli bir Bloom tokenı tek bir sözleşme değildir. O, **dağıtılmış üç sözleşmeden**oluşur, ayrıca ops'un zincir başına bir kez dağıttığı ve her ihraççının yeniden kullandığı dört ortak sözleşmeden oluşur.

**Token başına üç sözleşme** — her varlığın tam olarak sahip olduğu şunlardır:

| Sözleşme                     | Kaynak                                                      | Nedir                                                                                                                     |
| ---------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `ArcTokenProxy`              | `contracts/src/proxy/ArcTokenProxy.sol`                     | Tokenın kendisi — ortak `ArcToken` uygulamasını işaret eden bir UUPS proxy. Bakiyeler, sahipler ve roller burada bulunur. |
| `WhitelistRestrictions`      | `contracts/src/restrictions/WhitelistRestrictions.sol`      | Allowlist modülü. Her adres için bir boolean; varlık kısıtlıyken her transferde uygulanır.                                |
| `YieldBlacklistRestrictions` | `contracts/src/restrictions/YieldBlacklistRestrictions.sol` | Getiri modülü. Adresleri, elde ettikleri varlığa dokunmadan getiri dağıtımlarının dışında bırakır.                        |

**Zincir başına birer tane olan dört ortak sözleşme** (dağıtan: `deploy-infra.ts`):

| Sözleşme              | Rol                                                                                     |
| --------------------- | --------------------------------------------------------------------------------------- |
| `RestrictionsRouter`  | Modül türü kaydı — zincir bağlantısı, ops tarafından bir kez ayarlanır.                 |
| `ArcTokenFactoryV2`   | Kayıt + kanonik proxy codehash'i (adım 2–3).                                            |
| `ArcToken` (uygulama) | Her tokenın proxy aracılığıyla bağlandığı ortak, yeniden kullanılabilir varlık mantığı. |
| `ArcTokenPurchase`    | Her token ve ihraççı tarafından paylaşılan tek bir mağaza vitrini (adım 4).             |
| wUSDC                 | Nakit tarafı — getiri para birimi ve satış-satın alma para birimi.                      |

Transfer kısıtı ve getiri kısıtı **bilerek ayrı modüllerdir**: bir sahip, varlığı elinde tutarken geliri engellenebilir; yaptırımlar ve mahkeme kararları gerçekte böyle işler.

Bu "üç sözleşme" gerçeği, doğrulama için kritik önemdedir. `verify-deployments.ts` ve `register-asset.ts` ikisi de bir tokenın üç dağıtılmış sözleşmeye çözülmesini bekler — bir kez elle token doğrulamak, bir zincir genelinde yedisini kaçırdı (her getiri modülü ve üç whitelist modülü).

Yaşam döngüsünün üç aşaması ve tek yönlü bir kapısı vardır:

```
taslak     proxy canlı, bağlı modül yok — transferi hiçbir şey kısıtlamaz
  ↓
kısıtsız   modül bağlı, transfersAllowed = true   (bunu WhitelistRestrictions.initialize ayarlar)
  ↓  arz bas, allowlist'i oluştur               [geri alınabilir]
kısıtlı     setTransfersAllowed(false)                [TEK YÖNLÜ KAPI — arz kesinleşir]
```

Kısıtlama arz için tek yönlüdür çünkü mint ve burn `address(0)` karşı taraf olarak geçirir ve `address(0)` asla allowlist'e alınamaz — bu yüzden bir kez kısıtlandığında, artık yeni arz basılamaz. İzinli bir varlığın sahiplerine verdiği güvence budur.

***

## Adım 2 — Onu parça parça dağıtın, asla tek işlem olarak değil

Arc, tek seferlik bir `createToken` proxy'yi ve her iki modülü dağıtan ve bunları tek çağrıda bağlayan akış sunar. **Roma'da bunu kullanamazsınız.** O işlem şunları gerektirir: **77 Solana hesap kilidi**, ve Roma'nın işlem başına sınırı **62 kilittir**. Bu hiçbir zaman sığmaz — ayarlamayla da, optimizasyon geçişiyle de değil.

Bu yüzden dağıtım **parça parça**: her sözleşme kendi işleminde dağıtılır ve token `ArcTokenFactoryV2.registerToken` tek parça `createToken`yerine üzerinden factory'ye eşdeğer statü kazanır. Bu create sihirbazıdır ve ihraççı konsolunun adım adım yaptığı şey budur:

![create sihirbazı](https://4222476421-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)

Referans uygulama `arc/plan/create.ts` (`createSequence()`), bunu uygulama altı kart olarak gösterir (`bloom/lib/createCards.ts`) üzerinde **sekiz işlem**, sözleşmelerin zorunlu kıldığı tam sırayla:

| # | İşlem                            | Sözleşme çağrısı                                                                 |
| - | -------------------------------- | -------------------------------------------------------------------------------- |
| 1 | Varlığı dağıt                    | `new ArcTokenProxy(impl, initData)` burada `initData = ArcToken.initialize(...)` |
| 2 | İzin listesi modülünü dağıtın    | `new WhitelistRestrictions()`                                                    |
| 3 | Sizi yöneticisi olarak ayarlayın | `whitelist.initialize(issuer)`                                                   |
| 4 | Transferlerde bunu uygulayın     | `token.setRestrictionModule(TRANSFER, whitelist)`                                |
| 5 | Getiri modülünü dağıtın          | `new YieldBlacklistRestrictions()`                                               |
| 6 | Sizi yöneticisi olarak ayarlayın | `yieldBlacklist.initialize(issuer)`                                              |
| 7 | Getiride bunu uygulayın          | `token.setRestrictionModule(YIELD, yieldBlacklist)`                              |
| 8 | Fabrikaya kaydedin               | `factoryV2.registerToken(token, impl)`                                           |

Betik biçimi tek bir komuttur:

```bash
# zincir başına tek seferlik (token başına değil) — dört ortak sözleşmeyi dağıtır
npx tsx deploy-infra.ts

# token başına — sihirbazın betik olarak tekrar oynatılması
NAME="Mineral Vault I" SYMBOL=ARCV SUPPLY=1000000 DECIMALS=6 npx tsx create-token.ts
```

İhraççı (`PRIVATE_KEY`) her işlemi imzalar ve sonunda tokenın rollerini elinde tutar (`ArcToken.initialize` şunlara yetki verir: `msg.sender` — bkz. adım 7). `enableToken` ve factory aracılı herhangi bir yükseltmenin kilidini açan şeydir.

> **Bunu "optimize ederek" tekrar tek parçaya dönüştürmeyin.** Gidiş gelişleri azaltmak için bu çağrıları tek işlemde toplamak, parça parça yolun kaçınmak için var olduğu tam 62 kilit taşmasını yeniden getirir. Aynı sınır, getiri dağıtımının neden işlem başına bir sahip üzerinden ilerlediğini de açıklar (adım 8). Bir çağrı şu hatayla başarısız olursa `Çok fazla hesap: N > 62`, bir işlem çok fazla hesaba dokunuyordur — ayarlamayın, bölün.

***

## Adım 3 — Proxy'leri yalnızca kökeni kilitli artefaktlardan dağıtın

`registerToken` parça parça dağıtımların güvenli olmasını sağlayan güvenlik sınırıdır. Yalnızca şu tokenı kabul eder: **çalışma zamanı codehash'i kanonik olanla eşleşen `ArcTokenProxy`** dağıtım sırasında factory'ye gömülen:

```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();
    // …uygulama factory tarafından allowlist'te olmalı ve msg.sender
    //    tokenın ADMIN_ROLE'ünü tutmalı ve token zaten kayıtlı olmamalı.
}
```

Çünkü bu codehash **değişmezdir**, başka herhangi bir artefaktla oluşturulan bir proxy şu hata ile kapalı başarısız olur: `ProxyCodehashUnknown`. Buradan iki kural çıkar ve ikisi de CI ile `CLAUDE.md`:

1. **Token proxy'leri şuradan dağıtılmalıdır: `rome-contracts/out`** — asla şuradan değil: `contracts/out`, asla farklı bir derlemeden değil. Factory'nin kanonik codehash'inin sabitlediği derleme budur.
2. **`bytecode_hash = "none"` ve `cbor_metadata = false`** için `rome-contracts/foundry.toml` kritik önemdedir. Metadata etkin olduğunda, `ArcTokenProxy` çalışma zamanı *gömülü* factory'de (`type().runtimeCode`) yerleşik tek başına `out/` sihirbazın dağıttığı artefaktınkinden farklı bir CBOR/IPFS son eki taşır — bu yüzden zincir üzeri `registerToken` geri dönerken **kaynak içi tüm Foundry testleri geçer** (Foundry her iki kopyayı da gömdüğü için uyumsuzluğu göremez). `rome-contracts/test/ArtifactProvenance.t.sol` bu özelliği sabitler; fonlanmış çalışma bunu ilk yakalayan şeydi.

> **Yeşil geçen bir kaynak içi test paketi kökeni kanıtlamaz.** Bir imajı yayımlamadan önce ve HERHANGİ bir derleyici ayarı değişikliğinden sonra, bu özelliği şuna karşı kanıtlayın: *dağıtılmış* factory'ye (salt okunur, anahtarsız):
>
> ```bash
> cd scripts && CHAIN_ID=<id> npx tsx verify-artifact-provenance.ts
> ```
>
> Yerel `ArcTokenProxy` artefaktınızı hash'ler ve o hash'in dağıtılmış factory'nin bytecode'u içinde aynen yer aldığını doğrular.

Derleyici ayarları değişmek zorundaysa, **factory'yi döndürün** — yeni codehash'i sabitleyen yeni bir tane dağıtın ve yeniden bağlayın — kontrolü elle yamalamak yerine:

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

Döndürme, eski adresi makbuzda korur; eski factory'ye kayıtlı tokenların yeni factory'ye yeniden kaydedilmesi gerekir.

***

## Adım 4 — Ortak mağaza vitrini üzerinden satış açın

Satış, oluşturma işleminden ayrı bir eylemdir ve tek bir ortak `ArcTokenPurchase` vitrin üzerinde çalışır. Bir satış açılmadan önce üç şey doğru olmalıdır ve `ArcTokenPurchase.enableToken` bunların her birini zincir üzerinde kontrol eder:

```solidity
// contracts/src/ArcTokenPurchase.sol
function enableToken(address _tokenContract, uint256 _numberOfTokens, uint256 _tokenPrice)
    external onlyTokenAdmin(_tokenContract)                       // (a) tokenın ADMIN_ROLE'ünü tutuyorsunuz
{
    // (b) token factory tarafından bilinmeli — bunu registerToken (adım 2) sağladı:
    if (ArcTokenFactory(ps.tokenFactory).getTokenImplementation(_tokenContract) == address(0))
        revert TokenNotCreatedByFactory();
    // (c) vitrin zaten satış envanterini elinde tutmalı:
    if (ArcToken(_tokenContract).balanceOf(address(this)) < _numberOfTokens)
        revert ContractMissingRequiredTokens();
    // …fiyat ve miktar pozitif olmalı.
}
```

Kısıtlı bir varlığın zorunlu kıldığı dördüncü, örtük bir gereklilik vardır: çünkü **her transfer allowlist kapısından geçer**, envanteri vitrine taşımak ancak vitrin adresinin tokenınızda da whitelist'e alınmış olmasıyla başarılı olur. Bu yüzden satış açma dizisi şöyledir:

1. **Vitrini whitelist'e alın** tokenınızın whitelist modülünde (`batchAddToWhitelist([storefront])` — bkz. adım 5). Bu olmadan, (2)'deki envanter transferi geri döner `TransferRestricted()` bir kez kısıtlandığında.
2. **Envanteri aktarın** vitrin adresine (infra makbuzundaki `arcTokenPurchase`).
3. **`enableToken(token, amount, price)`** — alıcılar artık wUSDC öder ve RWA alır.

Çekim ayrımı, bir *ortak* vitrinde bilinmeye değerdir ve simetrik değildir (`arc/roles.ts` yetki budur):

| İşlem                                                      | Yetki                                   | Elinde tutan           |
| ---------------------------------------------------------- | --------------------------------------- | ---------------------- |
| `enableToken` / `disableToken` / `withdrawUnsoldArcTokens` | tokenın `ADMIN_ROLE` (`onlyTokenAdmin`) | siz, ihraççı           |
| `withdrawPurchaseTokens` (wUSDC gelirleri)                 | vitrinin `DEFAULT_ADMIN_ROLE`           | vitrini kim dağıttıysa |

Kendi barındırdığınız bir zincirde ikisi de sizsiniz. Ortak bir vitrinde ise gelir havuzu tüm ihraççıların kazançlarıdır; bu yüzden çekim platform düzeyindedir — mutlak kontrol varsaymak yerine mutabakatınızı buna göre tasarlayın.

***

## Adım 5 — Kendi KYC / uyumluluk sisteminizi bağlayın

Bir müşterinin evet demeden önce okuduğu bölüm burasıdır; bu yüzden düzyazı değil, koddur. **Uyumluluk, token sözleşmesinin kendisi tarafından uygulanır** — zincir dışı bir ekran, bir sequencer filtresi veya bir platform politikası tarafından değil. Kurallar, tokenla birlikte her yürütme yoluna, her iki cüzdan hattında da taşınır. Zincirin kaydettiği şey **sonuç** KYC kararınızın, tek bir boolean olarak

```solidity
// contracts/src/restrictions/WhitelistRestrictions.sol — zincir üzeri durum, tam haliyle
struct WhitelistStorage {
    mapping(address => bool) isWhitelisted;   // ← her adres için bir boolean. Asla PII yok.
    bool transfersAllowed;                    // false = kısıtlı; yalnızca whitelist'teki adresler transfer yapar
    EnumerableSet.AddressSet whitelistedAddresses;
}
```

### Sürecinizin yazdığı arayüz

KYC sağlayıcınızın onay/ret kararı tam olarak bu çağrılardan birine dönüşür:

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

### Kim yazabilir

> **Bir onayın ihtiyaç duyduğu yetki `MANAGER_ROLE` şu üzerindedir:&#x20;*****modül*****&#x20;— token üzerinde değil `ADMIN_ROLE` token üzerinde değil.** `addToWhitelist` / `batchAddToWhitelist` / `removeFromWhitelist` hepsi `onlyRole(MANAGER_ROLE)`, ve bu rol `WhitelistRestrictions` örneği üzerinde bulunur. Kimlik doğrulamasını `ADMIN_ROLE` token üzerinde yapıp sonra modüle yazmak, bu kod tabanının bedelini zaten ödediği gerçek bir kusurdur. Şunu çözüm olarak önermeyin: `WHITELIST_ADMIN_ROLE` bir ret için — bu yetki initialize sırasında verilir ve **paketin hiçbir yerinde kontrol edilmez** (`arc/roles.ts` (tek bir şeyi bile kısıtlamadığını doğrular).

`WhitelistRestrictions.initialize(issuer)` (sihirbazın tx 3'ü) ihraççıya `DEFAULT_ADMIN_ROLE`, `ADMIN_ROLE`, `MANAGER_ROLE`, `WHITELIST_ADMIN_ROLE`, ve `UPGRADER_ROLE` o modülde verir. Böylece ihraççı `MANAGER_ROLE` kutudan çıktığı haliyle bunu tutar ve ayrıca devredebilir: çünkü ihraççı `DEFAULT_ADMIN_ROLE`, bir `grantRole(MANAGER_ROLE, serviceAccount)` yazma yetkisini bir arka uç imzacısına verir.

### Bir kararın zincir üzeri yazıya dönüşmesi

Sağlayıcınızın webhook'unu şunu tutan bir imzacıyı gösterecek şekilde ayarlayın: `MANAGER_ROLE`, ve onay durumunda adresleri toplu işleyin:

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

// `signer` BU tokenın whitelist modülünde MANAGER_ROLE'ü tutmalıdır.
const wallet = createWalletClient({ account, transport: http(chain.rpcUrl) });

// sağlayıcı bu adresler için "onaylandı" dedi:
await wallet.writeContract({
  address: whitelistModule,                 // resolved FROM the token via getRestrictionModule
  abi: whitelistAbi,
  functionName: 'batchAddToWhitelist',
  args: [approvedAddresses],
});
```

Çöz `whitelistModule` tokenın kendisinden (`ArcToken.getRestrictionModule(TRANSFER_RESTRICTION_TYPE)`), asla önbelleğe alınmış bir projeksiyondan değil — yazmayı yanlış modüle yöneltmek, "her varlıkta onayla" özelliğinin bir zamanlar bir token'ın izin listesine yazmasına yol açtığı şeydir.

### Cüzdan tarafından imzalanan varyant (self-servis demo)

Ziyaretçilerin kendilerini kabul ettiği izinsiz bir test dağıtımı için, `MANAGER_ROLE` bir `TestApprover` (`rome-contracts/src/TestApprover.sol`) olan `modül` şu **değişmezdir**. Ardından `approve(address)` herkes tarafından, kendi cüzdanından, kendi gas'ını ödeyerek çağrılabilir — şunu çağırır `addToWhitelist` yalnızca adres zaten listede değilse:

```solidity
function approve(address account) external {
    IWhitelistRestrictions target = IWhitelistRestrictions(module);   // değiştirilemez — sonsuza dek tek bir modül
    if (!target.isWhitelisted(account)) target.addToWhitelist(account);
    emit Approved(account, msg.sender);
}
```

Bu, "giriş kapısı"dır — bir ziyaretçiye gerçek mekanizmayı (bir onayın zincir üzerinde bir izin listesi girdisine dönüşmesi ve token'ın ardından bunu zorunlu kılması) hiçbir şeyi saklama altına almadan gösterir. **Asla yetki vermeyin `MANAGER_ROLE` bir `TestApprover` üretim token'ında** — bu, o token'ın izin listesini izinsiz hâle getirir.

### Kapı devreye girdiğinde ve sağlayıcıları değiştirirken

Kapı, yalnızca varlık **kısıtlamaya alınmış** (`setTransfersAllowed(false)`, `ADMIN_ROLE` olduğunda kısıtlama uygular. Kapı açık değilken transferler açıktır — önce izin listenizi oluşturun, sonra kapıyı kapatın. Kapı kapatıldığında, taraflardan herhangi biri listede değilse bir transfer, türlendirilmiş hata ile geri döner `TransferRestricted()` (`0xe827105e`).

> **KYC sağlayıcılarını daha sonra değiştirmek zincir üzerinde hiçbir değişiklik gerektirmez.** İzin listesi modülü, arayüzü ve sakladığı boolean sağlayıcıdan bağımsızdır. Satıcı değiştirmek için, aynı `MANAGER_ROLE` imzalayana farklı bir karar kaynağı yönlendirin — yeniden dağıtım yok, taşıma yok, durum değişikliği yok. Zincir, çağrıyı hangi satıcının yaptığını asla bilmedi; yalnızca sonucu biliyordu.

***

## Adım 6 — Aynı varlığı Solana cüzdanlarına açın

Aynı üç sözleşmeye bir Solana cüzdanından erişilebilir **ikinci bir token olmadan**. Solana-yerel bir kullanıcının hiçbir yerde EVM anahtarı yoktur; bunun yerine EVM kimliği *sentetiktir*, işlemin gerçek Solana imzalayanından zincir üzerinde türetilir:

```
sentetik EVM adresi = keccak256(solana_pubkey)[12..32]
```

Rome EVM programı bunu imzalayanın kendisinden türetir (`do_tx_unsigned::derive_sender`), bu yüzden taklit edilemez ve bunun için hiçbir secp256k1 özel anahtarı yoktur — **bu adresi çalıştırabilecek tek şey Solana imzasıdır**. Referans türetim şudur `arc/materialise/solana/identity.ts` (`syntheticAddress`), zincir üstü kuralla bayt düzeyinde uyumludur:

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

**Bir geliştiricinin bu hattı desteklemek için yaptığı şey** — dikkat edin ki *bunların hiçbiri bir sözleşme değişikliği değildir*:

1. **Solana kullanıcısını sentetik adresiyle izin listesine ekleyin.** Uyumluluk katmanı için sentetik adres sıradan bir adrestir: kullanıcının Solana pubkey'ini yapıştırın, sentetiği türetin ve `batchAddToWhitelist([synthetic])`. Tek bir izin listesi her iki cüzdan dünyasını da kapsar.
2. **İmzalama PDA'sını, ilk değer taşıyan çağrılarından önce bir kez sağlayın.** Sentetik için imza atan dış yetki PDA'sı önce var olmalıdır ve onu oluşturmak tek bir `create_pda` çağrıdır. Her iki taraf da bunu gönderebilir: kullanıcının kendi Solana cüzdanı hattan (SDK'nın `buildCreatePdaCall`, sonra `isSyntheticProvisioned` false döndürdükten sonra), ya da ihraççı bir EVM anahtarıyla. Bloom'un ihraç araçları bunu bugün bir kullanıcıyı sisteme almanın parçası olarak gönderiyor; uygulama bunu henüz kullanıcının ilk eyleminde yapmıyor, bu yüzden kullanıcının ilk satın alımından önce hazırlayın. SDK çağrılarıyla bunun nasıl yapılacağı [Çift hatlı uygulama](https://docs.rome.builders/tr/gelistirici-kilavuzlari/dual-lane-app.md#one-time-activate-provision-the-synthetic).
3. **Elle değil, hat kütüphanesi üzerinden gönderin.** `submitDoTxUnsigned` (`arc/materialise/solana/submit.ts`) zincirin vekiline işlemi oluşturmasını ister ve elle oluşturulmuş bir işlemin yanlış yaptığı şeyleri halleder. Hattaki her sözleşme çağrısı bir **vekil tarafından oluşturulmuş Solana v1 işlemidir** (`rome_composeUnsignedAtomicV1`) adres arama tablosu olmadan gerçekleşir ve hat kütüphanesi daha eski bir biçime geri dönmek yerine kapalı şekilde başarısız olur. 5. adımdeki cash-in hamlesi, uygulamanın kendi başına oluşturduğu ayrı bir Solana işlemidir; oluşturulmuş bir sözleşme çağrısı değildir.
   * **Hesap keşfi ve compute bütçesi vekilin işidir.** Çağrıyı taklit eder, her hesabın yazılabilirliğine karar verir (çağrının `value` çağrının bir parçasıdır, bu yüzden onu iletin) ve döndürdüğü işlemde compute ve heap bütçesini ayarlar. Kodunuzda hiçbir şey compute-budget talimatları oluşturmaz veya fee-pool hesabını eklemez.
   * **Her çağrı için iki imza, ikisi de Solana anahtarından.** Cüzdan önce okunabilir bir yetkilendirme mesajını imzalar (*Rome yetkilendirmesi* ile imzasız EIP-1559 yükünün hash'i; Wallet Standard `solana:signMessage`), ve vekil çağrıyı oluşturmadan önce bunu doğrular. Ardından vekilin döndürdüğü v1 işlemini imzalar (`solana:signTransaction` ham kablo üzerinde). Hat kütüphanesi bunları şu şekilde alır `signAuthHash` ve `signV1Wire`, asla tek bir birleştirilmiş yöntem olarak değil. Üzerine inşa etmeden önce cüzdanınızın v1 işlemlerini imzaladığını kontrol edin: Solflare bugün devnet'te bunu yapıyor, Phantom ise henüz yapmıyor.
   * **Uygulama, imzalanmış işlemi bir Solana RPC'ye kendisi gönderir.** Vekil oluşturur; atomik bir çağrıyı yayınlamaz.
   * **İmza istemeden önce doğrulayın.** Hat kütüphanesi oluşturulmuş mesajı ayrıştırır ve işlem isteminden önce bozuk olanı reddeder.
4. **Tek seferlik wrapper yetkisini ilk wUSDC harcamasından önce verin.** wUSDC, kullanıcının tokenlarını o kullanıcının SPL vekili olarak taşır, bu yüzden hiç yetki verilmemiş sentetik bir adres SPL hatası alır `0x4` ilk wUSDC transferinde. Şuna bakın `isEnabled(user)` wrapper üzerinde ve false olduğunda, başına ekleyin `approve_spl(wrapper, 2^64-1, mint)` Helper precompile üzerinde çalışmanın ilk ayağı olarak. Her iki hatta da cüzdan başına bir kez yapılan sıradan bir çağrıdır. Şuna bakın [Cüzdan başına tek seferlik izin](https://docs.rome.builders/tr/temel-kavramlar/token-interop.md#one-time-grant-per-wallet).
5. **Harcayacak bir çağrıdan önce nakdi içeri alın.** Sentetik, boşta hiçbir şey tutmaz. Çağrının harcadığından daha az wUSDC tuttuğunda, önce eksik miktarı cüzdanın kendi USDC token hesabından taşıyın (sentetiğin token hesabının idempotent oluşturulması, ardından tokenları EVM'yi çalıştırmadan taşıyan Rome programının activate-token-account komutu). Bu, tek bir istemle imzalanan tek bir Solana işlemidir ve sentetik zaten yeterli miktarı tuttuğunda atlanır.
6. **Yalnızca atomik oluşturucunun reddettiğini iletin.** Tek bir Solana işlemine sığmayan bir çağrı (yaklaşık 1,4M compute unit, 64 hesap, 4 KB) oluşturucu tarafından şu hatayla reddedilir *dış atomik plan yinelemeli oluşturma gerektirir*. Tam olarak bu ret üzerine ve asla öncesinde değil, şunu çağırın `rome_relayUnsignedV1` aynı yetkilendirme imzasıyla: vekil onu oluşturur ve gönderir, Solana ücretlerini öder ve bir EVM işlem karmasıyla yanıt verir (Solana imzası değil). Sentetik, zincirin yerel gas'ını wei cinsinden öder, bu yüzden bakiyesi `gasLimit x maxFeePerGas`kadar yetersizse, önce şununla tamamlayın `rome_composeExternalDepositV1` (cüzdan tarafından imzalanan bir v1 işlem; miktar pratikte 10^12 wei'nin katı olmalıdır), fiiliyatta cüzdan başına bir kez. Geri alma, ağ hatası veya reddedilmiş imza gibi diğer hatalar yeniden fırlatılır, iletilmez. Ayrıntılar şurada [İletilen çağrılar ve uzun çağrılar](https://docs.rome.builders/tr/gelistirici-kilavuzlari/call-evm-from-solana.md#relayed-calls-and-long-calls).

Kullanıcı **ücret ödeyicidir** ve doğrudan bir çağrı için Solana cüzdanından lamport (SOL) öder; kontrol ettikleri sentetik varlıkları tutar ve hiçbir zaman SOL tutmaz. Her hat gönderiminden sonra, bir sonrakinden önce EVM nonce'unu sorgulayın — dizinleyici Solana onayının biraz gerisinde kalır ve aksi takdirde bir sonraki çağrı, zincirin zaten harcamış olduğu bir nonce üzerine kurulurdu.

> **Önce atomik, ret halinde ilet.** Her çağrının varsayılanı, kullanıcının cüzdanı tarafından imzalanan, bir Solana işleminin içinde yürütülen tek bir EVM işlemidir. İletim, sığmayan bir çağrı için istisnadır; tercihe göre seçilecek ikinci bir rota değildir: doğrudan çağrı iki istem, iletilmiş çağrı bir istemdir ve iletilmiş çağrı lamport yerine Rome gas ile ödenir. Çok adımlı bir yolculuk (önce onayla, sonra satın al) birkaç tam çağrıdır; her biri kendi işlemi olan ayrı çağrılardır, işlemler arasında bölünmüş tek bir yürütme değildir.

**RWA'nın sınır dışına neden sızamayacağı.** Varlık EVM durumunda yerleşiktir — bakiyeleri Rome EVM programının hesapları içindeki depolamadır. Bir **SPL mint'i yoktur** ve taşınacak Solana-yerel hiçbir şey yoktur; hattın varlık taşıma ilkelleri SPL token hesapları üzerinde çalışır, oysa bir EVM depolama bakiyesinin böyle bir hesabı yoktur. Solana imzasının ifade edebildiği her hareket token sözleşmesine bir çağrıdır; bu sözleşme izin listesi kapısını çalıştırır — fonlu test paketi, bir EVM anahtarı ya da Solana anahtarı tarafından imzalansa da izinli listede olmayan bir adrese transferin aynı şekilde geri döndüğünü doğrular. Nakit ayağı (wUSDC) kasıtlı istisnadır: SPL desteklidir ve *şu anda* kullanıcının kendi token hesabına süpürülür.

***

## Adım 7 — Dağıtımdan sonra yetkinin kimde olduğunu bilin

`ArcToken.initialize` vekil kurucusundan (tx 1) çalışır ve rolleri şuna verir `msg.sender` — sihirbaz sürücüsü, yani ihraççı. Şunları verir **beş** rolü açıkça:

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

Bir geliştiricinin kaçırmaması gereken iki sonuç:

* **`MINTER_ROLE`, `BURNER_ROLE`, ve `UPGRADER_ROLE` initialize sırasında VERİLMEZLER.** İlk arz şunun içinde mint edilir `başlat` (dahili bir `_mint`, rol gerekmez), ancak bir *daha sonra* `mint` veya `burn` için ihraççının önce kendisine rol vermesi gerekir. Verebilirler, çünkü ellerinde `DEFAULT_ADMIN_ROLE` (her rolün yöneticisi — hiçbir şey şunu çağırmaz `_setRoleAdmin`, bu yüzden `DEFAULT_ADMIN_ROLE` hepsini yönetir). Ancak bu bilinçli bir ek adımdır, kendiliğinden gelen bir yetki değildir.
* **`UPGRADER_ROLE` fabrikaya asla verilmez.** Fabrika aracılı yükseltmeler (`ArcTokenFactoryV2.upgradeToken`) şunu gerektirir **fabrikanın kendisinin** tutmasını `UPGRADER_ROLE` token üzerinde — bunu kendinize vermek hiçbir şey yapmaz. Bu yetki, fabrikanın geri alamayacağı tek yönlü bir kapıdır, bu yüzden isteğe bağlıdır: fabrika aracılı yükseltmeler istiyorsanız, `grantRole(UPGRADER_ROLE, factory)` açıkça verin; aksi takdirde ihraççı tokenı doğrudan yükseltir.

Tam 21 yetki modeli (altı sözleşme boyunca 11 rol adı — aynı ad her sözleşmede farklı bir yetkidir) şurada kodlanmıştır `arc/roles.ts`. Sorgulayın `rolesRequiredFor(contract, functionName)` bir rolün kendi sözleşmesini okumak yerine, çünkü dört storefront işlevi ve her iki fabrika işlevi, üzerinde bulunan bir yetki tarafından kısıtlanır *farklı* sözleşmesi üzerinden 2 USDC öder.

***

## Adım 8 — Getiriyi dağıtın

Token getiriyi wUSDC cinsinden öder (şuna sabitlenmiştir `başlat`, şununla değiştirilebilir `setYieldToken` altına `YIELD_MANAGER_ROLE`). Dağıtım, sahipler kümesi üzerinde ilerler:

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

Bunu doğru işletmek için önemli olan mekanikler:

* **Tam `totalAmount` çağrıyandan yalnızca `startIndex == 0` penceresinde çekilir** (`safeTransferFrom(msg.sender, this, totalAmount)`). İlk pencereden önce bu toplamı token için onaylayın; sonraki pencereler zaten elde tutulan bakiyeden öder.
* **`nextIndex` şuraya döner `0` dolaşım tamamlandığında.** Döngü `distributeYieldWithLimit(total, nextIndex, …)` olana kadar `nextIndex` geri gelir `0`.
* **Getiri kısıtlamalı sahiplerin payları token sözleşmesinde kalır** — atlanırlar, yeniden dağıtılmazlar.

> **Rome'da pratik üst sınır `maxHolders = 1` işlem başına** — adım 2'deki aynı 62 hesap sınırı — bu yüzden getiri işlem başına bir sahip üzerinden ilerler (sahip başına ölçülen \~318 K gas). İzinli listedeki her sahip, EVM ya da Solana-yerel olsun, orantılı pay alır; referans betik şudur `measure-yield-batch.ts` ve fonlu smoke testinin getiri adımı bunu uçtan uca doğrular.

```bash
# USAGE.md referans biçimi: nextIndex 0'a dönene kadar işlem başına bir sahip üzerinde ilerle
distributeYieldWithLimit(total, offset, 1)
```

***

## Adım 9 — Dağıttığınız şeyi doğrulayın

Rome'da hiçbir şey kaynakları otomatik olarak hiçbir yere göndermez, bu yüzden doğrulama sizin çalıştırdığınız bir adımdır. Herhangi bir dağıtımdan sonra — altyapı ya da yeni bir token — salt-okunur, anahtarsız, idempotent doğrulayıcıyı çalıştırın (zaten doğrulanmış sözleşmeler atlanır, bu yüzden bir token çıkardıktan sonra yeniden çalıştırmak yalnızca yenilerini doğrular):

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

Şunları bekler **üç** token başına sözleşmeler (proxy + her iki modül) ile altyapıyı ve bir dağıtımı başarısız kılmak yerine doğrulayamadıklarını raporlar. Bunu elle bir kez yapmak yedi sözleşmenin gözden kaçmasına neden oldu.

Varlığı Rome siciline kaydetmek, doğrulamayı bir **kapı**olarak ele alır, süsleme olarak değil (`register-asset.ts`): bir token şunu kazanır `apps/arc/<chain>.json` kaydını — şu etiketi taşıyan `standard: arc-permissioned-erc20` ve bir `transferRestriction` izin listesi kapısını adlandıran — ancak üç sözleşmesinin de Sourcify üzerinde doğrulandığında. Bu kayıt, gerçeklerini zincirden okur (sihirbazla dağıtılmış bir token'ın taahhüt edilmiş bir makbuzu yoktur) ve yalnızca yerel bir sicil checkout'u yazar; PR'ı bir kişinin tamamlaması gerekir.

```bash
CHAIN_ID=200010 npx tsx register-asset.ts <tokenAddress>        # doğrula + sicil kaydını hazırlayın
CHAIN_ID=200010 DRY=1 npx tsx register-asset.ts <tokenAddress>  # salt-okunur önizleme
```

Tüm döngünün uçtan uca kanıtı için — oluştur, izin ver, kapat, her iki hatta sat, getiriyi dağıt — fonlu smoke testini herhangi bir zincirde çalıştırın:

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

***

## Adım 10 — Zincir dışında neyin kaldığını bilin

Güven modeli kasıtlı olarak dürüsttür ve bir geliştirici bunu kendi kullanıcılarına da aynı şekilde aktarmalıdır:

* **İzin listesi bayrağı sizin zincir dışı kararınızdır.** KYC/AML süreci sizin süreçlerinizde gerçekleşir — satıcılarınız, kurallarınız. Zincir yalnızca şunu kaydeder ve uygular *sonuç*, `isWhitelisted(addr)`.
* **Zincir üzerindeki tek durum, adres başına bir booleandır.** Kişisel veri yok, belge yok, kimlik iddiası yok, zincir üstü beyan yok, bir adresin kime ait olduğuna dair kriptografik kanıt yok. Bu, Plume üzerinde kullanılan Arc modelidir; zincir üstü kimlik standardının (örn. ERC-3643) daha ağır aktarım mekanizmalarını daha hafif mekanikler ve ihraççının elindeki güven ile değiştirir.
* **Kurtarma, bir ihraççı yetkisidir; kaçış kapısı değildir.** Kaybolan bir cüzdan — EVM ya da Solana — yedek bir adresi izin listesine alarak ve gerekirse kendi hukuki süreciniz kapsamında mint/burn/upgrade kullanarak kurtarılır (Arc'ın yerleşik bir zorla transfer ilkeli yoktur). Bu nedenle ihraççının anahtar saklaması, uyumluluk duruşunun bir parçasıdır.
* **Bloom'un kendi relay'i yok, saklama yüzeyi yok.** Kullanıcılar her iki hatta da kendi gas'larını tutar. Uygulama tarafından yürütülen bir ücret ödeyici hizmet, anahtar tutmak anlamına gelir — bir RWA ürününün eklememesi gereken bir yüzey. Solana hattındaki tek relay, tek bir işlem için fazla büyük olan bir çağrı içindir ve yine de kullanıcı bunu kendi imzasıyla yetkilendirir ve kendi Rome gas'ıyla öder.

***

## Referans: araçlar

Her betik araçların `scripts/` dizininden çalışır, ve `PRIVATE_KEY`, `CHAIN_ID`, ve `REGISTRY_ROOT` dışa aktarılmıştır.

| Betik                           | Ne yapar                                                                                       |
| ------------------------------- | ---------------------------------------------------------------------------------------------- |
| `deploy-infra.ts`               | Zincir başına tek seferlik: wUSDC için yapılandırılmış dört ortak sözleşme.                    |
| `create-token.ts`               | Parçalı sihirbaz — sekiz işlem, bir token.                                                     |
| `rotate-factory.ts`             | Derleyici/artifact değişikliğinden sonra yeni bir fabrika dağıtın; yeniden bağlayın.           |
| `verify-artifact-provenance.ts` | Proxy artifact'inizin dağıtılmış fabrika tarafından kabul edildiğini kanıtlayın (salt-okunur). |
| `verify-deployments.ts`         | Token başına üç sözleşmenin tamamını + altyapıyı Sourcify üzerinde doğrulayın (salt-okunur).   |
| `register-asset.ts`             | Doğrulama kapısından geçir, sonra sicil uyumluluk kaydını hazırlayın.                          |
| `measure-yield-batch.ts`        | Bir zincirde işlem başına getiri üst sınırını yeniden ölçün.                                   |
| `smoke.ts`                      | Her iki hat boyunca fonlu uçtan uca paket.                                                     |
| `sweep-synthetic-native.ts`     | Sentetik hesaptan yerel gas'ı geri alın (test hijyeni).                                        |

Daha derin arka plan bu kılavuzun yanında bulunur: `docs/ARCHITECTURE.md` (katmanlı uygulama modeli), `docs/LANES.md` (iki hat ve saklama), `docs/COMPLIANCE.md` (güven modeli), ve `docs/USAGE.md` (işletici runbook'u).


---

# 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/tr/rome-uzerindeki-uygulamalar/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.
