Base Solana Bridge Guide #437
Conversation
🟡 Heimdall Review Status
|
|
Review Error for kmk142789 @ 2025-10-06 14:32:37 UTC |
| The Base-Solana bridge enables bidirectional token transfers and message passing between Base and Solana networks. This bridge allows you to: | ||
|
|
||
| * **Transfer tokens** between Base and Solana | ||
| * **Send arbitrary cross-chain messages** |
There was a problem hiding this comment.
Maybe also mention the ability to combine transfer + calls
| ## How it works | ||
|
|
||
| ### On Base | ||
| The Base bridge contract locks or burns your tokens and emits a message. Validators collect these messages into Merkle trees and post roots to Solana every ~15 minutes. You then prove your message exists in the tree to complete the transfer on Solana. |
There was a problem hiding this comment.
The bridge contract locks or burns when sending messages from Base -> Solana. It also mints / unlocks tokens when receiving messages from Solana. Also, validators do not build merkle trees, this is done directly in the Bridge contract itself, and validators verify the merkle root every 300 finalized blocks to be relayed to Solana
| </Tip> | ||
|
|
||
| ### On Solana | ||
| The Solana bridge program locks or burns your tokens and emits events. Validators relay these messages to Base where they're executed through your personal Twin contract - a smart contract that acts as your execution context on Base. |
There was a problem hiding this comment.
a smart contract that acts as your execution context on Base.
Is this redundant after the Tip right before it?
There was a problem hiding this comment.
Not redundant - the tip explains a bit more and gives more context
There was a problem hiding this comment.
Ah I see what you mean. I think it's ok to leave it there to make sure whoever is reading only that section has the full context.
| </Tip> | ||
|
|
||
| ### On Solana | ||
| The Solana bridge program locks or burns your tokens and emits events. Validators relay these messages to Base where they're executed through your personal Twin contract - a smart contract that acts as your execution context on Base. |
There was a problem hiding this comment.
where they're executed through your personal Twin
This is only for messaging, but not for token transfers
There was a problem hiding this comment.
added clarification
| </Card> | ||
| </CardGroup> | ||
|
|
||
| ## Solana to Base |
There was a problem hiding this comment.
I think this section should probably make it clear that the bridge is a pull-based model in the Solana -> Base direction as well. Meaning a bridge flow requires 3 steps:
- Initiate the bridge on Solana
- Wait for validators to pre-approve the message
- Execute the message on Base
We will be operating a relayer service that will handle step 3 for users that only want to worry about the init tx on Solana
|
|
||
| The Solana to Base flow in this example uses automatic relay for seamless transfers. Your SOL is locked in a Solana vault, and the relayer automatically executes the message on Base to mint wrapped SOL. | ||
|
|
||
| <GithubRepoCard title="Solana to Base Example" githubUrl="https://github.com/basebase-bridge-examples/tree/main/solToBaseWithAutoRelay" /> |
There was a problem hiding this comment.
I thought more about this and you can probably just link to https://github.com/base/bridge/blob/main/scripts/src/commands/sol/onchain/bridge/solana-to-base/bridge-sol.handler.ts which is what I based my example off of
| To bridge custom SPL tokens, | ||
| you need to create wrapped ERC20 representations on Base using the CrossChainERC20Factory. | ||
|
|
||
| <GithubRepoCard title="Token Wrapping Example" githubUrl="https://github.com/basebase-bridge-examples/tree/main/wrapSolTokenOnBase" /> |
There was a problem hiding this comment.
|
|
||
| **Key Programs:** | ||
| - [**Bridge Program**](https://github.com/base/bridge/blob/main/solana/programs/bridge): Handles outgoing transfers | ||
| - [**Base Relayer Program**](https://github.com/base/bridge/blob/main/solana/programs/base_relayer): Coordinates message relay |
There was a problem hiding this comment.
The relayer program is not part of the core bridge - this is a convenience feature we are operating on top of the bridge to reduce friction in the Solana -> Base direction
There was a problem hiding this comment.
It's good to leave it there to make sure people are aware of it, but I added a callout to make sure it's visible
Co-authored-by: Jack Chuma <[email protected]>
| ## How it works | ||
|
|
||
| ### On Base | ||
| The Base bridge contract locks or burns tokens when sending messages to Solana, |
There was a problem hiding this comment.
We say "locks or burns" and "mints or unlocks"
Is it truly either? Or are we using these words as synonyms? If its just synonyms we should pick a single word. I think "lock" and "unlock" are the most immediately understood by the widest audience
There was a problem hiding this comment.
it's either, and it depends if the token is native to base (locks) or native to solana (burns) - I'll clarify it though, thanks
There was a problem hiding this comment.
Added callouts to clarify
There was a problem hiding this comment.
A broader preference of mine would be to move the "how it works" section below the implementation sections. And then in the implementation sections, we could have an internal link to the how it works section, something like "Read here to learn more about how the solana <>Base bridge works"
This focuses the doc on implementation and our general goal of shortening time to implementation, while still ensuring that the way the bridge works is documented
I would generally agree once we have clearer and easier paths towards integration (SDK), but I think in this case, it is unfortunately hard to start implementing without a basic understanding of how the bridge works - as it's a still a bare-bone smart contracts protocol and any developer would have to interact with the contract directly |
What changed? Why?
Adding a guide for developers using the new Base <> Solana bridge