KeeperHub / KeeperHub/keeperhub

Instant cross-chain bridging: add a Relay.link plugin

Open
#2,370 3 comments 0 reactions 0 assignees View on GitHub
enhancement needs-discussion
Dominant language
TypeScript
Stars
24
Forks
93
Avg merge
1d 8h
Merged PRs (30d)
266

Description

### Before filing

- [x] I searched open and closed issues for this proposal.
- [x] I checked the docs and the current behaviour on `staging`.
- [x] This is one change, not several. (Several means several issues.)

### Reason: what you cannot do today

Checked against staging at 6e2d908ec.

KeeperHub already moves tokens across chains. protocols/chainlink.ts exposes CCIP — ccip-send, ccip-get-fee, ccip-approve-bridge-token, and the matching balance and allowance checks. So this is not a missing capability; it is a coverage and latency one.

What I cannot do is bridge on a pair CCIP has no lane for, or bridge fast enough that the rest of the workflow can depend on the funds having arrived.

What that rules out, concretely , workflows that are expressible today right up to the point where value has to cross a chain:

React to a condition on one chain and act on another inside a single run: a price or position check on chain A, then a swap or repayment on chain B that depends on the funds being there. Today the second half cannot assume the first half landed.
Top up a wallet on whichever chain is running low, from where the balance actually is, on a schedule.
Take a payout or yield on the chain it accrues on and consolidate it somewhere else, without the run ending at the bridge.

### Reason: what the workaround costs

CCIP settles on source chain finality, so a workflow whose next step needs the funds present has to wait out that window inside the run. The workaround is to split into two workflows joined by a webhook or a polled balance check, which means the first run's state has to be reconstructed on the far side the amount, the recipient, and whatever the branch condition was. That state round-trip is the cost, and it grows with every field the second half needs.

Where there is no CCIP lane for the pair at all, there is no workaround inside KeeperHub: the bridge happens outside and the workflow starts after it.

### Scope: what this touches, and what it does not

Touches: one new plugins/relay/ — index.ts plus steps/, following plugins/cowswap/ exactly. Registration is automatic through pnpm discover-plugins, which regenerates plugins/index.ts.

Deliberately does not touch: protocols/ (no new ABI protocol — see the plan); the executor; the existing CCIP actions, which stay exactly as they are and remain the right choice where a lane exists and latency does not matter; database schema; billing.

Is this one change? There is a real seam and I want it on the record rather than assumed away. A quote action could ship and be correct with the execute action reverted — a workflow can branch on route availability or price without ever bridging. By the letter of the rule in ISSUES.md that makes them separate issues.

I am proposing them as one anyway, because a quote step alone does not make the blocked task possible, and the unit that does is quote plus execute plus status. If triage reads that seam the other way, splitting it costs nothing and I will file the quote half first.

### Plan: what you propose

A plugin, not a protocol.

protocols/ is defineAbiProtocol — contract-ABI shaped, and it produces plugins through protocolToPlugin. Relay's quoting and request-tracking surface is HTTP, and an ABI definition alone cannot produce a route. The precedent for this exact split is already in the repo: CoWSwap has protocols/cowswap.ts for the on-chain settlement contracts and plugins/cowswap/steps/ calling the orderbook API over fetch. Relay wants the plugin half, at least to begin with.


Action | Shape
-- | --
get-quote | origin and destination chain, token, amount → route, fee, estimated time
execute-bridge | takes a quote, performs the origin-chain transfer, returns a request id
get-request-status | polls a request id to completion

Existing callers: unaffected. This is purely additive — no response shape, status code, or default changes.

What I would need to determine before building. I can see the KeeperHub side; I have not verified the Relay side, and these four change the design rather than just the code:

  1. Whether the origin-chain send reuses the existing plugins/web3 signing path or needs its own.
  2. Whether execute-bridge should block on destination settlement inside the run, or return a request id for a separate status step. This is the latency question that motivates the whole issue, and it interacts with workflow timeouts — I lean to the non-blocking pair, but it is a decision, not a detail.
  3. Which chains to expose: the intersection of Relay's supported set and the chain list the wallet modal already offers.
  4. Whether the public API needs a key or carries rate limits worth surfacing as a credential.

### Plan: alternatives you considered

Do nothing. CCIP covers the lanes it covers. The cost is above, and it is bounded, this is a convenience and latency argument, not a correctness one.
Extend the CCIP integration instead. Does not help. Lane coverage and finality-based settlement are properties of CCIP, not gaps in how KeeperHub integrates it.
A generic multi-provider bridge abstraction. Rejected as premature with one provider, and against the grain of the repo: CoWSwap, Hyperliquid, Safe and Robinhood each have their own plugin rather than sitting behind a shared facade.
Model Relay as a protocols/ ABI definition. Rejected: the quoting surface is HTTP. The on-chain half alone cannot produce a route, so an ABI protocol would be a partial integration that still needs the plugin.

### Scope: compatibility

- [ ] Changes an existing response shape, status code, CLI flag, or default.
- [ ] Adds, removes, or upgrades a dependency.
- [ ] Changes database schema or requires a migration.
- [x] Touches authentication, permissions, validation, or spend limits.
- [ ] Changes pricing, plan limits, or anything a user is charged.

Contributor guide

Open the contributing guide

Research direction

Start by reading plugins/cowswap/index.ts and plugins/cowswap/steps/, then compare protocols/cowswap.ts and the plugins/web3 signing path. Resolve the Relay API, signing, supported-chain, credential, and blocking-versus-status decisions before implementing plugins/relay/index.ts and its steps/. Done means quote, execute-bridge, and get-request-status are exposed and pnpm discover-plugins regenerates plugins/index.ts.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
backend-api-design, blockchain
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.