> For the complete documentation index, see [llms.txt](https://docs.kpk.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kpk.io/funds/infrastructure/architecture/deployment/cross-chain-deployment.md).

# Cross-chain deployment (CCIP)

How a single transaction on any wired chain deploys a fund there and fans the operational stack out over Chainlink CCIP to the other chains it can reach, at the same addresses everywhere.

A fund spans one or more chains, and its Portfolio Safe, Manager Safe, and Roles Modifiers must share the **same address on every chain** (see [Architecture overview](https://docs.kpk.io/funds/infrastructure/architecture/architecture-overview.md)). Doing that by hand means running [`deployStack`](https://docs.kpk.io/funds/infrastructure/architecture/deployment.md) on each chain from the same account, in separate transactions. **`CcipOivDeployer`** automates it: a **single transaction on any wired chain** deploys that chain's part of the fund **and** fans the operational stack out over **Chainlink CCIP** to every other wired chain that is not a shares chain and that it can reach, producing identical Portfolio / Manager / Roles addresses across all chains.

**Source:** [`CcipOivDeployer.sol`](https://github.com/karpatkey/onchain-investment-vehicles/blob/main/src/CcipOivDeployer.sol)

| At a glance      |                                                                                                                  |
| ---------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Contract**     | `CcipOivDeployer` (external orchestrator around `KpkOivFactory`)                                                 |
| **Address**      | `0xD99e4B13fc50A6321f6A84f2D4F83d6e34AE699D`, same on every chain                                                |
| **Origin chain** | Any wired chain; there is no designated source chain                                                             |
| **Entry points** | `deployEverywhere` · `dispatchTo` · `deployLocal` (permissionless) · `promoteShares` (fund governance)           |
| **Addresses**    | [Deployment addresses](https://docs.kpk.io/funds/infrastructure/architecture/deployment/deployment-addresses.md) |

## Why an orchestrator (not CCIP inside the factory)

`KpkOivFactory` mixes `msg.sender` into every CREATE2 salt to stop salt-squatting, so its cross-chain address invariant holds only when the **same caller** invokes the factory on every chain. A raw CCIP integration would break this: on a destination chain the factory's caller would be the CCIP Router, not the original account.

`CcipOivDeployer` solves it by being the **single, uniform caller** of the factory on every chain. Because the orchestrator is itself deployed at the **same address on all chains** (deterministic CREATE2, identical creation code), the factory sees one identical `msg.sender` everywhere, and the address invariant is preserved, with **no CCIP logic inside the factory's deployment path**. All CCIP, fee, and router logic lives in the orchestrator.

## Shares chains

Every fund declares a **shares-chain topology**: the list of chains that carry its `kpkShares` token, and the base asset it uses on each.

```solidity
struct SharesChain {
    uint256 chainId;   // a chain that runs deployOiv for this fund
    address asset;     // the fund's base asset on that chain
}
```

* Every chain **in** `sharesChains` gets the full fund (stack + shares token). Every other wired chain gets the operational stack only, through the fan-out when the origin has a CCIP lane to it, or otherwise through `dispatchTo` from another chain or `deployLocal` on that chain.
* The topology must be non-empty, **strictly ascending by `chainId`**, and at most 20 entries.
* The topology is **hashed into the fund's salt**, so pass the **same array everywhere**, for the life of the fund. A different topology is a different fund, at different addresses.
* A fund with more than one shares chain cannot also use `additionalAssets` (`AdditionalAssetsNeedASingleSharesChain`): those asset addresses are chain-specific but bound into the salt.
* A declared chain is skipped by the fan-out and refuses inbound stacks, so it holds nothing until its own `deployLocal` runs. Declare only the chains you intend to use; a chain added later goes through [`promoteShares`](#adding-shares-to-a-new-chain).

Shares tokens are **never** deployed over CCIP. Each shares chain is filled by a transaction on that chain.

## The flow

1. **Local half.** If the origin chain is in `sharesChains`, the orchestrator runs `deployOiv` there (stack + shares token). Otherwise it runs `deployStack`; starting from a stack-only chain is supported.
2. **Fan-out.** One CCIP message goes to every other wired chain that is **not** a shares chain and that the local router can reach. Each destination runs `deployStack` at the same addresses.
3. **Other shares chains.** Each remaining chain in `sharesChains` is filled by its own **`deployLocal(config, sharesChains)`** call on that chain.

The orchestrator derives each destination's `StackConfig` by calling the factory's own `oivToStackConfig(config)` helper at runtime, so the mapping can never drift and fragment a fund's addresses.

## Entry points

`deployEverywhere`, `dispatchTo`, and `deployLocal` are **permissionless**. The two CCIP-sending entry points are **caller-funded** (fees paid in native gas as `msg.value`; see [CCIP fees](#ccip-fees)) and run on any wired chain.

| Function                                                                    | Purpose                                                                                                      |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `deployEverywhere(config, sharesChains, gasLimit)`                          | Deploy locally and fan out to **every reachable** wired chain that is not a shares chain.                    |
| `deployEverywhere(config, sharesChains, destChainIds[], gasLimit)`          | Same, but only to the given destination chains.                                                              |
| `deployEverywhere(config, gasLimit)`                                        | Shorthand for a single shares chain: **this** one, with `config.sharesParams.asset` as its base asset.       |
| `dispatchTo(config, sharesChains, destChainIds[], gasLimit)`                | CCIP fan-out **only** (no local deploy), to add a stack chain later or retry a permanently-failed delivery.  |
| `deployLocal(config, sharesChains)`                                         | Deploy this chain's part with no CCIP at all: shares token on a declared shares chain, stack otherwise.      |
| `promoteShares(config, sharesChains)`                                       | Add the shares token to a chain the topology does **not** declare. Restricted to fund governance; see below. |
| `quoteDeployEverywhere(config, [sharesChains, [destChainIds[],]] gasLimit)` | View: total native fee and per-destination breakdown to size `msg.value`.                                    |
| `predictOiv(config, sharesChains)`                                          | View: the addresses the fund will have (applies the orchestrator's salt derivation; see below).              |
| `supportedChainIds()`                                                       | View: the wired chains **this** chain can currently reach over CCIP.                                         |

```solidity
function deployEverywhere(OivConfig calldata config, SharesChain[] calldata sharesChains, uint256 gasLimit)
    external payable returns (OivInstance memory instance, bytes32[] memory messageIds);

function dispatchTo(OivConfig calldata config, SharesChain[] calldata sharesChains,
                    uint256[] calldata destChainIds, uint256 gasLimit)
    external payable returns (bytes32[] memory messageIds);

function deployLocal(OivConfig calldata config, SharesChain[] calldata sharesChains)
    external returns (OivInstance memory instance);

function promoteShares(OivConfig calldata config, SharesChain[] calldata sharesChains)
    external returns (OivInstance memory instance);

function quoteDeployEverywhere(OivConfig calldata config, SharesChain[] calldata sharesChains, uint256 gasLimit)
    external view returns (uint256 totalFee, uint256[] memory feePerDestination);

function predictOiv(OivConfig calldata config, SharesChain[] calldata sharesChains)
    external view returns (OivInstance memory);
```

{% hint style="info" %}
**Config-bound salt.** The orchestrator is the factory's *uniform* caller, which would neutralise the factory's caller-mixed anti-squat salt. To restore it, the orchestrator derives the salt from the **whole config plus the topology**: `salt = keccak256(abi.encode(config, sharesChains))`, with the per-chain base asset zeroed (it is committed to through `sharesChains` instead). Ignored fields (`sharesParams.admin` / `.safe` and the role lists of an unconfigured timelock) are zeroed too, so they cannot split one fund into two. Any config difference (notably `admin`) changes **every** deployed address, so an attacker cannot land a fund at another config's addresses; an identical config and topology still yield identical addresses on every chain, **whichever chain originates**. Offchain tooling must predict via **`predictOiv(config, sharesChains)`**, not the factory's raw `predictOivAddresses`.
{% endhint %}

{% hint style="warning" %}
The `deployEverywhere(config, gasLimit)` shorthand makes the **calling chain** the fund's only shares chain. The topology is part of the salt, so calling it from a different chain describes a **different fund** at different addresses, not the same fund homed elsewhere.
{% endhint %}

## CCIP fees

Every cross-chain message costs a CCIP fee. `deployEverywhere` sends **one message per destination chain**, so the amount to pay is the **sum of the per-destination fees**.

* **Paid in native gas, by the caller.** The fee is paid in the **origin chain's native token** as the **`msg.value`** of the `deployEverywhere` / `dispatchTo` call: the account that triggers the deployment funds it. CCIP is **not** paid in LINK here, and the orchestrator keeps **no fee treasury**, so there is nothing to pre-fund or drain.
* **What a fee covers.** For each destination, the CCIP Router prices delivering the message **and** executing `ccipReceive` there up to the `gasLimit` passed. The total therefore scales with the **number of destinations** and the **gas limit**.
* **Quote before you send.** `quoteDeployEverywhere` is a view that returns the **`totalFee`** and the **per-destination breakdown**. Send at least `totalFee` as `msg.value`.
* **Surplus is refunded.** If `msg.value` exceeds the total fee, the excess is **refunded to the caller** in the same transaction, so sending a small buffer over the quote is safe.
* **Fees are not refunded for a failed delivery.** A message that reverts on arrival still spent its fee. The orchestrator validates the whole config, including the shares half and the timelocks, on the origin chain **before** pricing, so most mistakes revert before any fee is paid.

### Gas limit

`gasLimit` is the destination execution budget baked into each message's price. It is **prepaid**, so unspent destination gas is not refunded, and too low a limit makes the destination delivery fail (see [Operational model](#operational-model)).

* **Pass 3,000,000 for any timelocked fund.** CCIP caps destination execution at 3,000,000 gas on many lanes, and a timelocked `deployStack` with a large role set needs about 2.6M–2.8M plus about 80k for the `ccipReceive` frame.
* A fund with **no exec timelock** measures about 1.58M; 2,000,000 is ample.
* The Manager Safe can have at most **10 owners** for anything sent over CCIP (`ManagerOwnersExceedCcipBudget`), so the stack fits under the cap.

{% hint style="info" %}
No LINK pre-funding or fee treasury is required: quote the fee with `quoteDeployEverywhere` and send it, plus a small buffer, as `msg.value`.
{% endhint %}

## Security model

`ccipReceive` accepts a message only when **all three** hold:

1. `msg.sender` is the configured CCIP Router.
2. `message.sourceChainSelector` is one of the chains in the orchestrator's registry.
3. The decoded source sender equals `address(this)`, the sibling orchestrator on the originating chain (same address everywhere).

Check (3) is the load-bearing guard: only a contract at the orchestrator's address can be the source sender. A destination also **refuses a stack aimed at one of the fund's shares chains** (`SharesChainRefusesStack`), so nobody can occupy the addresses that chain's shares deployment needs. If a delivery finds the fund's stack already deployed at its addresses under the expected exec governance, it succeeds rather than failing.

All three checks assume the configured router is genuine. The orchestrator owner can repoint it (`configure`), so a hostile owner or router could land a stack at a fund's addresses on a chain under a different exec owner; a genuine delivery then fails rather than reporting success, but the addresses stay occupied. This is why the owner must remain a governance multisig (see [Deployment addresses](https://docs.kpk.io/funds/infrastructure/architecture/deployment/deployment-addresses.md#ownership)).

{% hint style="info" %}
The orchestrator never holds a privileged role on any deployed fund. The exec Roles Modifier (owned by `config.admin` or the fund's exec timelock) remains the authoritative gatekeeper of Portfolio Safe execution ([Roles and operators](https://docs.kpk.io/funds/infrastructure/architecture/core-concepts/roles-and-operators.md)).
{% endhint %}

## Operational model

{% hint style="warning" %}
Cross-chain delivery is **asynchronous, not atomic.** The origin transaction confirms once the messages are dispatched; each destination stack materialises later (after origin-chain finality) when CCIP delivers to `ccipReceive`.
{% endhint %}

* **Partial failure is possible.** A destination message can fail (e.g. gas underestimate). It then enters CCIP's `FAILED` state and can be **manually re-executed** within its retry window. Monitor delivery on the [CCIP Explorer](https://ccip.chain.link).
* **Recovery / add a stack chain.** `deployEverywhere` is the first fan-out and cannot be re-run with the same config (its local deploy would revert `StackAlreadyDeployedHere`; a fully wired stack is the one thing adoption refuses). To extend a fund to a new stack chain, or resend to one whose delivery permanently failed, use **`dispatchTo`** with the **same** `config` and `sharesChains`, so the stack lands at the fund's existing addresses. Don't re-dispatch to a chain that already has the stack: the fee is spent either way.
* **Fees.** Paid by the caller in native gas as `msg.value`; quote and size them per [CCIP fees](#ccip-fees).
* **Preconditions.** `deployStack` reverts unless the canonical `Empty` contract and the Safe MultiSend / Zodiac `MultiSendUnwrapper` contracts are present on the target chain. They are on every chain listed on [Deployment addresses](https://docs.kpk.io/funds/infrastructure/architecture/deployment/deployment-addresses.md).
* **New funds only.** Addresses are keyed to the orchestrator and the factory generation, so a fund deployed directly by an EOA, or on an earlier factory generation, cannot be extended through this path. A fund using CCIP must enter through the current ([salt v4](https://docs.kpk.io/funds/infrastructure/architecture/deployment/deployment-addresses.md)) orchestrator from the start.

## Adding shares to a new chain

Two situations, with different calls:

* **A chain that is in `sharesChains` but has not deployed yet**: call **`deployLocal(config, sharesChains)`** on that chain. Not the factory's raw `deployOiv` (it uses `config.salt` verbatim and builds a separate fund at different addresses), and not `promoteShares` (it reverts `SharesChainAlreadyDeclared` for a declared chain).
* **A chain that is not in `sharesChains` at all**: call **`promoteShares(config, sharesChains)`** on that chain, passing the fund's **original** config and topology. The promoted shares token lands at the fund's existing shares address, and nothing else moves.

`promoteShares` is the one gated entry point, because a promoted chain's base asset is not committed to by the topology: an open promotion would let anyone holding the config deploy a shares token in an asset of their choosing at the fund's canonical address. Its preconditions:

* **The caller is the exec Roles Modifier's live owner on that chain**, not `config.admin` as such. That is `admin` while nothing has been rotated, the exec timelock on a timelocked fund, and whatever governance now owns the modifier after a rotation.
* **A fund born with an exec timelock** stays promotable only while that **birth timelock still owns** the exec Roles Modifier (`TimelockMismatch` otherwise). `execTimelock` is part of the salt, so it cannot be restated.
* **A fund born without an exec timelock and without a `sharesTimelock`** is refused `PromotionWouldRearmTheBirthAdmin` after **any** rotation of exec governance, including to a hand-deployed exec timelock, because the promoted token's `DEFAULT_ADMIN_ROLE` would otherwise go to the replaced `admin`, with no way to take it back.
* The fund's operational stack already exists on that chain (`StackNotDeployed` otherwise).
* The Portfolio Safe has already approved the predicted shares proxy for **`type(uint256).max`** on the base asset **and** every `canRedeem` additional asset (`ApprovalNotGranted` otherwise). The proxy address is predictable, so approve first.
* Every `additionalAssets` entry has code on that chain at the same address (`AdditionalAssetHasNoCodeHere` otherwise).

{% hint style="warning" %}
**Give funds their timelocks at birth; don't retrofit.** The rules above are fail-safe (a refused promotion changes no state and costs only the transaction's gas), but they mean a fund whose governance was changed after birth may be unable to add shares chains. Pass the **original** `admin` in the config; the live owner is read from the chain.
{% endhint %}

## Supported destinations

The orchestrator's chain registry is **seeded at construction** with 19 chains, identically on every chain. CCIP lanes are **directional**, so being in the registry does not mean a chain is reachable from every origin. Call **`supportedChainIds()`** on the origin chain to see which chains its router can reach right now:

* The all-chains `deployEverywhere` **skips** unreachable chains silently.
* An **explicitly named** unreachable chain reverts **`LaneNotSupported(chainId, selector)`**, from the quote and the deploy alike, **before any fee is paid**.

The orchestrator owner can still correct or retire registry entries (`setChainSelector` / `removeChainSelector`). The full chain list is on [Deployment addresses](https://docs.kpk.io/funds/infrastructure/architecture/deployment/deployment-addresses.md).

{% hint style="warning" %}
**Robinhood Chain is not wired for CCIP.** The salt v4 contracts are deployed there, but Robinhood Chain is not in the registry seeded at construction, so CCIP fan-out does not work to or from it: `deployEverywhere` and `dispatchTo` revert `UnknownChain` on Robinhood Chain, and the other chains' orchestrators reject its messages (`InvalidSourceChain`). A Fund that lives only on Robinhood Chain deploys locally through the orchestrator's `deployLocal`, with `sharesChains = [{chainId: 4663, asset}]` and the same asset in `sharesParams.asset`; a topology that does not name Robinhood Chain lands only the operational stack there. The factory's `deployOiv` works too, but builds a Fund the orchestrator can never extend (see [Operational model](#operational-model)). Cross-chain Funds that include Robinhood Chain need the Security Council Safe to add Robinhood Chain's selector (`setChainSelector`) on Robinhood Chain and on each chain that should talk to it, one Safe transaction per chain; `supportedChainIds()` then shows which lanes CCIP serves.
{% endhint %}


---

# 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.kpk.io/funds/infrastructure/architecture/deployment/cross-chain-deployment.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.
