docs: Foreign chain transaction design doc #1920

netrome · 2026-01-30T11:25:04Z

Closes #1918

This is a high level design document that highlights the most significant parts (as I see it) of the planned design for the upcoming foreign chain transactions feature.

This is to help anyone get up to speed on the current design and to make sure we can effectively and quickly break down, review and merge this feature while maintaining strong alignment on what we're doing.

gilcu3

LGTM as a first draft, left a few questions that might improve it in a second round

gilcu3 · 2026-01-30T14:52:52Z

docs/foreign_chain_transactions.md

+## Scope
+
+- In scope: contract-level API for verify+sign requests, node-side verification via configured RPC providers, deterministic provider selection, and extensible per-chain verifiers.
+- Out of scope: on-chain light clients / cryptographic proofs, multi-round MPC consensus on verification results, and non-ECDSA schemes for verify_foreign_transaction (initially ECDSA only).


as used below:

Suggested change

- Out of scope: on-chain light clients / cryptographic proofs, multi-round MPC consensus on verification results, and non-ECDSA schemes for verify_foreign_transaction (initially ECDSA only).

- Out of scope: on-chain light clients / cryptographic proofs, multi-round MPC consensus on verification results, and non-ECDSA schemes for `verify_foreign_transaction` (initially ECDSA only).

gilcu3 · 2026-01-30T14:54:08Z

docs/foreign_chain_transactions.md

+At a high level:
+
+1. A user submits a `verify_foreign_transaction` request with a chain-specific verification config.
+2. MPC nodes verify the foreign transaction via configured RPC providers.


how does this trust relation work? Does the node need to trust the RPC provider, or the information obtained can be itself verified against some ground truth, for example a fixed public key?

No, we trust the RPC providers. But this trust is diluted by the fact that multiple RPC providers need to return the same result.

I see, so colluding RPC providers could easily break the system. I forgot to mention, one thing I missed from the doc is a concrete attacker model, where this details would become explicit

gilcu3 · 2026-01-30T14:56:21Z

docs/foreign_chain_transactions.md

+
+1. A user submits a `verify_foreign_transaction` request with a chain-specific verification config.
+2. MPC nodes verify the foreign transaction via configured RPC providers.
+3. If verified, MPC signs `sha256(tx_id_bytes)` with the derived domain key and returns the signature on-chain.


are we planning to use this with existing domains?

I guess sha256(tx_id_bytes) is some application dependent step in the signature process, but for the application we will support initially it is the correct one?

Yes, this will work with any existing ECDSA domains according to the current proposal. I'm a bit questioning if we should have dedicated domains for this or some sort of separation between this and the sign use case though.

I guess there is a trade-off. Using existing domains is more efficient, simple and risky, but having a different domain is more cumbersome and secure

Edit: We want to enforce separate domains for this. (discussed on Slack).

gilcu3 · 2026-01-30T14:57:23Z

docs/foreign_chain_transactions.md

+// Contract DTOs
+pub struct VerifyForeignTxRequestArgs {
+    pub chain: ForeignChain,
+    pub tx_id: TransactionId, // TxID is the payload we're signing


I find it strange that we call this transaction id, but at the same time it is the transaction payload

Oh right, ForeignTransactionId would be a better name for this. This is the payload we're signing, but it's a transaction ID on another chain.

so basically all we are signing is a transaction ID from another chain, not really an arbitrary payload?

Yes exactly. The feature is basically just signing a transaction ID right now. Though we might need to change that.

gilcu3 · 2026-01-30T14:59:11Z

docs/foreign_chain_transactions.md

+    pub chain: ForeignChain,
+    pub tx_id: TransactionId, // TxID is the payload we're signing
+    pub path: String, // Key derivation path
+    pub domain_id: Option<DomainId>, // Defaults to 0 (legacy ECDSA)


why do we need the Option for legacy here? Is there any requirement about compatibility with the current sign method?

Good observation. Let's make this required.

gilcu3 · 2026-01-30T15:05:31Z

docs/foreign_chain_transactions.md

+
+### Node Configuration and Policy Updates
+
+- Node config contains chain RPC providers and timeouts (API keys stay local).


Hmm I understand now. So the contract contains only the RpcProvider names, while the node store the actual details, so that they are detached.

Yes, exactly. Good to see this is clear.

gilcu3 · 2026-01-30T15:07:09Z

docs/foreign_chain_transactions.md

+- On startup, nodes compare local config to the on-chain policy.
+- If different, a node submits a vote for the policy derived from its local config.


are we expecting many policy changes? By this we are moving away from the current manual process to vote for anything, which is good, but at the same time will add complexity to the process, so there is a trade-off there

Yes, the reason for nodes to automatically vote is to ensure they have the actual configuration they are voting for. We originally considered having normal operator votes, but it felt like it would be easy for operators to forget updating their configuration before casting there votes for example.

So what would happen if they don't? The node would simply not start? How would the operator change this config when the node is running in a TEE?

Config updates in TEE is a bit of a pain point. The node would still operate even if it disagrees on the config, but I imagine it wouldn't collaborate on requests that it hasn't voted on.

I think we'll need to add better ways of dynamically updating node configuration once we've shipped the MVP of this feature.

gilcu3 · 2026-01-30T15:10:12Z

docs/foreign_chain_transactions.md

+Each node selects a provider using a deterministic hash of:
+
+```
+hash = sha256(participant_id || request_id || provider_name)
+```
+
+Providers are sorted by this hash to build a deterministic ordering:
+
+- **Primary provider** = first in the ordering.
+- **Fallback** = subsequent providers in order.
+- Each provider can include backup URLs for failover.
+
+This ensures different nodes query different providers for the same request while preserving determinism.


This does not really describe completely how it avoids that two nodes query the same provider, and at the same time is not very efficient. We might want to iterate a bit on this before settling it

Yeah, this is a very lean and not exact formulation. I started working on expanding it but found a precise explanation to be a bit too much and I don't think this is important for the first iteration as it's not user-facing. The important part here is that it's possible to derive a consistent ordering and using this ordering to ensure nodes vote for different providers.

Basically if we have the providers P1 P2 P3 P4 and nodes N1 N2 N3 N4 N5, we'd have N1 -> P1, N2 -> P2, N3 -> P3, N4 -> P4, N5 -> P1.

gilcu3 · 2026-01-30T15:11:52Z

docs/foreign_chain_transactions.md

+  signing availability.
+- **Finality semantics**: Finality definitions differ across chains; mapping them correctly is critical.
+- **Operational friction**: Unanimous voting for policy updates may slow rollouts and hot fixes.
+- **Config drift**: Nodes missing required provider keys will fail startup validation.


is this accurate? It didn't seem to be the case by the description above?

Yeah I'll remove it

gilcu3 · 2026-01-30T15:14:12Z

docs/foreign_chain_transactions.md

+## Discussion points
+- Why do we return a signature? Can't we just return a bool.
+  - A signature suggests this is a "proof" that can be validated by someone else than the caller, but currently it seems like this proof could easily be forged by just calling the normal "sign" method.
+- Finality interface right now diverges from the original PR. Are we okay with this new structure?


We can avoid this collision by tweaking the key derivation properly

netrome · 2026-01-31T12:58:26Z

I'll merge this PR and apply all updates in a follow-up. I think it can be nice to track how this proposal has evolved in our version history.

netrome added 10 commits January 30, 2026 12:08

chore: Add prompt

6c10683

Update prompt

d896653

Update prompt again

80b216d

PR description summary in design doc

cb19c04

docs: Draft design doc for foreign_chain_transactions

1d68430

Simplify charts

ceb0676

fix: Simplifications

7806bdf

Further simplify charts

4282c29

Purpose & motivation update

ad5caeb

Remove more slop

b681d7e

kevindeforth mentioned this pull request Jan 30, 2026

docs: Draft Proposal: Separating Oracle and MPC Networks #1922

Draft

netrome added 9 commits January 30, 2026 13:51

More simplifications and updates

ca29976

docs: Elaborate on key types

b734627

Some minor updates

f7a38c5

More readability improvements

1c159be

docs: Document contract state

f804f06

clear out some slop

43fd020

Small touch

12e973d

Design update

5bda324

Expand on API keys

5ef5cfb

netrome mentioned this pull request Jan 30, 2026

docs: create design document for foreign chain transactions #1917

Closed

Another discussion question

3889265

netrome marked this pull request as ready for review January 30, 2026 14:35

netrome changed the title ~~docs: Foreign chain design doc~~ docs: Foreign chain transaction design doc Jan 30, 2026

netrome self-assigned this Jan 30, 2026

DSharifi approved these changes Jan 30, 2026

View reviewed changes

gilcu3 approved these changes Jan 30, 2026

View reviewed changes

netrome added this pull request to the merge queue Jan 31, 2026

netrome mentioned this pull request Jan 31, 2026

Initial round of updates to foreign chain transaction design doc #1924

Open

Merged via the queue into main with commit 9eee495 Jan 31, 2026
13 checks passed

netrome deleted the foreign-chain-design-doc branch January 31, 2026 13:22

	- Out of scope: on-chain light clients / cryptographic proofs, multi-round MPC consensus on verification results, and non-ECDSA schemes for verify_foreign_transaction (initially ECDSA only).
	- Out of scope: on-chain light clients / cryptographic proofs, multi-round MPC consensus on verification results, and non-ECDSA schemes for `verify_foreign_transaction` (initially ECDSA only).


		### Node Configuration and Policy Updates

		- Node config contains chain RPC providers and timeouts (API keys stay local).

		- On startup, nodes compare local config to the on-chain policy.
		- If different, a node submits a vote for the policy derived from its local config.

docs: Foreign chain transaction design doc #1920

docs: Foreign chain transaction design doc #1920

Conversation

netrome commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gilcu3 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

netrome commented Jan 31, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

netrome commented Jan 30, 2026 •

edited

Loading