> ## Documentation Index
> Fetch the complete documentation index at: https://daehan-base.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Base-Solana 브릿지
> Base와 Solana 메인넷 간의 토큰 및 메시지 브릿지
export const GithubRepoCard = ({title, githubUrl}) => {
return
;
};
Base-Solana 브릿지는 Base와 Solana 네트워크 간의 양방향 토큰 전송 및 메시지 전달을 가능하게 합니다. 이 브릿지를 통해 다음을 할 수 있습니다:
* **토큰 전송**: Base와 Solana 간 토큰 이동
* **임의의 크로스체인 메시지 전송**
* **두 흐름 결합 (임의 호출과 함께 전송)**
* **랩핑된 토큰 배포**: 어느 체인에서든 가능
이 가이드는 브릿지 아키텍처, 프로덕션 주소, 그리고 실용적인 구현 패턴을 다룹니다.
## 작동 방식
### Base에서
Base 브릿지 컨트랙트는 Solana로 토큰을 전송할 때 토큰을 잠그거나 소각하고, Solana에서 토큰을 수신할 때 토큰을 민팅하거나 잠금 해제합니다. Bridge 컨트랙트 자체는 나가는 메시지로부터 머클 트리를 구성합니다. 검증자는 약 \~300개의 최종 확정된 블록마다 머클 루트를 확인하고 Solana로 전달합니다. 그런 다음 메시지가 트리에 존재함을 증명하여 Solana에서 전송을 완료합니다.
Base 네이티브 토큰은 Solana로 브릿징할 때 잠기고, Solana 네이티브 토큰은 소각됩니다.
Solana 네이티브 토큰은 Base로 브릿징할 때 민팅되고, Base 네이티브 토큰은 잠금 해제됩니다.
**핵심 스마트 컨트랙트:**
* [**Bridge Contract**](https://github.com/base/bridge/blob/main/base/src/Bridge.sol): 나가는 전송 처리
* [**CrossChainERC20**](https://github.com/base/bridge/blob/main/base/src/CrossChainERC20.sol): 크로스체인 전송을 위한 민팅/소각 가능 토큰
* [**BridgeValidator**](https://github.com/base/bridge/blob/main/base/src/BridgeValidator.sol): 오라클 서명으로 메시지 검증
* [**Twin Contract**](https://github.com/base/bridge/blob/main/base/src/Twin.sol): Solana에서 오는 호출을 실행하기 위한 Base 위의 개인 스마트 컨트랙트
**Twin Contract이란?**\
각 Solana 지갑은 Base 위의 Twin 컨트랙트에 결정론적으로 매핑됩니다. 브릿지 메시지에 컨트랙트 호출을 첨부하면, 해당 호출은 이 Twin 컨트랙트에서 실행됩니다. 즉, Twin이 Base에서 `msg.sender`가 됩니다.
### Solana에서
Solana 브릿지 프로그램은 토큰을 잠그거나 소각하고 이벤트를 발생시켜 토큰 전송을 처리합니다. 메시징의 경우, 검증자가 이 이벤트를 Base로 전달하여 Twin 컨트랙트를 통해 실행됩니다.
**핵심 프로그램 (Solana Mainnet-Beta):**
* [**Bridge Program**](https://github.com/base/bridge/blob/main/solana/programs/bridge): 나가는 전송 및 메시지 커밋 처리.
* [**Base Relayer Program**](https://github.com/base/bridge/blob/main/solana/programs/base_relayer): Base에서 가스를 선불로 지불할 수 있는 선택적 릴레이어.
릴레이어 프로그램은 핵심 브릿지의 일부가 아닙니다. Solana → Base 방향에서 Solana 사용자를 대신하여 Base 가스 수수료를 지불할 수 있는 선택적 편의 레이어입니다.
사용자는 여전히 Solana 트랜잭션에 `PayForRelay`를 추가하여 가스 수수료를 지불해야 합니다.
사용자가 `PayForRelay`를 추가하지 않으면 릴레이어 프로그램이 가스 수수료를 지불하지 않습니다.
전체 저장소는 여기에서 접근할 수 있습니다:
## 브릿징 흐름
Base에서 즉시 실행을 위한 선택적 릴레이어가 있는 푸시 기반
완전한 커스터디와 함께 증명 기반 소각 및 잠금 해제
브릿징 + 컨트랙트 호출을 위한 프로덕션 터미널 UI
## Solana에서 Base로
**흐름:** SOL/SPL 잠금 → (선택 사항) 릴레이 비용 지불 → 검증자 승인 → Base에서 민팅 + 실행
Solana에서 Base 브릿지는 3단계가 필요한 풀 기반 모델을 사용합니다:
1. **Solana에서 브릿지 시작** - Solana 볼트에 SOL 또는 네이티브 SPL 토큰 잠금
2. **검증자가 메시지를 사전 승인할 때까지 대기** - 검증자가 브릿지 메시지를 확인하고 승인
3. **Base에서 메시지 실행** - 승인된 메시지가 Base에서 실행되어 SOL을 민팅하고 추가적인 임의 호출 실행
Solana에서 Base로 브릿징할 때, 네이티브 SOL/SPL이 잠기고 Base에서 ERC20 SOL이 민팅됩니다.
Solana → Base 메시지에 실행할 호출이 포함된 경우, ABI 인코딩된 호출이 **Base에서 실행 가능**한지 확인해야 합니다. Base에서 실행할 수 없는 호출은 **취소될 수 없습니다**. 동일한 트랜잭션에서 토큰을 브릿징하는 경우, 해당 토큰은 **잠깁니다**.
참조 스크립트(자동 릴레이, 토큰 랩핑, CLI 유틸리티)는 공식 저장소의 `scripts/` 디렉토리에 있습니다:
### 자동 릴레이 예시
자동 릴레이로 SOL을 브릿징하는 방법을 보여주는 샘플 스크립트입니다
```typescript solToBaseWithAutoRelay/index.ts expandable theme={null}
// Configure
const TO = "0x8c1a617bdb47342f9c17ac8750e0b070c372c721"; // Base address
const AMOUNT = 0.001; // SOL amount
// Bridge SOL with auto-relay
const ixs = [
getBridgeSolInstruction({
payer,
from: payer,
solVault: solVaultAddress,
bridge: bridgeAccountAddress,
outgoingMessage,
to: toBytes(TO),
remoteToken: toBytes("0xC5b9112382f3c87AFE8e1A28fa52452aF81085AD"), // SOL on Base
amount: BigInt(AMOUNT * 10**9),
}),
await buildPayForRelayIx(RELAYER_PROGRAM_ID, outgoingMessage, payer)
];
await buildAndSendTransaction(SOLANA_RPC_URL, ixs, payer);
```
자세한 내용은 [Solana에서 Base 릴레이 스크립트](https://github.com/base/bridge/blob/main/scripts/src/commands/sol/bridge/solana-to-base/bridge-sol.handler.ts)를 참조하세요.
### 커스텀 SPL 토큰 랩핑
위 예시는 네이티브 SOL을 Base로 브릿징하는 방법을 보여줍니다.
커스텀 SPL 토큰을 브릿징하려면 CrossChainERC20Factory를 사용하여 Base에서 랩핑된 ERC20 표현을 만들어야 합니다.
```typescript wrapSolTokenOnBase/index.ts expandable theme={null}
// Deploy wrapped token on Base
const mintBytes32 = getBase58Codec().encode(SOLANA_SPL_MINT_ADDRESS).toHex();
await client.writeContract({
address: "0x58207331CBF8Af87BB6453b610E6579D9878e4EA", // Factory
abi: TokenFactory,
functionName: "deploy",
args: [`0x${mintBytes32}`, "Token Name", "SYMBOL", 9],
});
```
## Base에서 Solana로
**흐름:** Base에서 ERC20 SOL 소각 → 최종성 대기 → 머클 증명 생성 → Solana에서 실행
Base에서 랩핑된 토큰을 소각하고, 메시지가 증명 가능해질 때까지 기다린 다음, Solana에서 증명을 실행하여 네이티브 자산을 잠금 해제합니다. 이 경로는 완전한 커스터디를 제공하며 증명자가 필요합니다.
```typescript bridgeSolFromBaseToSolana/index.ts expandable theme={null}
// Step 1: Burn SOL on Base
const transfer = {
localToken: "0xC5b9112382f3c87AFE8e1A28fa52452aF81085AD", // SOL (on Base)
remoteToken: pubkeyToBytes32(SOL_ADDRESS),
to: pubkeyToBytes32(solanaAddress),
remoteAmount: BigInt(AMOUNT * 10**9),
};
const txHash = await client.writeContract({
address: "0xB2068ECCDb908902C76E3f965c1712a9cF64171E", // Bridge
abi: Bridge,
functionName: "bridgeToken",
args: [transfer, []],
});
// Step 2: Wait for finalization
const isProvable = await isBridgeMessageProvable(txHash);
// Step 3: Generate proof
const { event, rawProof } = await generateProof(txHash, baseBlockNumber);
// Step 4: Execute on Solana
const proveIx = getProveMessageInstruction({
nonce: event.message.nonce,
sender: toBytes(event.message.sender),
data: toBytes(event.message.data),
proof: rawProof.map(e => toBytes(e)),
messageHash: toBytes(event.messageHash),
});
const relayIx = getRelayMessageInstruction({ message: messagePda });
await buildAndSendTransaction(SOLANA_RPC_URL, [proveIx, relayIx], payer);
```
**Base → Solana** 방향에서 사용자를 위해 Solana 트랜잭션에 서명하고 제출하는 릴레이어를 운영하는 경우, 릴레이어 pubkey를 서명자로 요구하는 트랜잭션에 **서명하지 마세요**.
악의적인 사용자는 릴레이어 pubkey를 필수 서명자로 포함하는 트랜잭션을 인코딩할 수 있습니다. 서명하고 제출하면 릴레이어 자금을 훔칠 수 있는 명령을 포함한 임의 명령을 의도치 않게 승인할 수 있습니다. 기본적인 완화 조치로 pubkey를 서명자로 지정하는 트랜잭션을 무시하세요.
## 유틸리티
저장소에는 Solana와 Base 주소 형식 간 변환, 트랜잭션 서명을 위한 Solana CLI 키페어 가져오기, Solana 트랜잭션 빌드 및 전송을 위한 유틸리티가 포함되어 있습니다.
### 주소 변환
Base 컨트랙트용으로 Solana pubkey를 bytes32로 변환:
```typescript example.ts theme={null}
// Convert Solana pubkey to bytes32 for Base contracts
import { pubkeyToBytes32 } from "./utils/pubkeyToBytes32";
const bytes32Address = pubkeyToBytes32(solanaAddress);
```
### 키페어 관리
트랜잭션 서명을 위한 Solana CLI 키페어 가져오기:
```typescript example.ts theme={null}
import { getSolanaCliConfigKeypairSigner } from "./utils/keypair";
const payer = await getSolanaCliConfigKeypairSigner();
```
### 트랜잭션 빌딩
Solana 트랜잭션 빌드 및 전송:
```typescript example.ts theme={null}
import { buildAndSendTransaction } from "./utils/buildAndSendTransaction";
const signature = await buildAndSendTransaction(SOLANA_RPC_URL, ixs, payer);
```
## Terminally Onchain 예시
[Terminally Onchain](https://terminallyonchain.com/)은 커맨드 터미널 UI를 통해 브릿지를 노출하는 프로덕션 Next.js 앱입니다. 사용자는 Solana 지갑을 연결하고 Base에서 브릿지 및 컨트랙트 호출과 같은 명령을 입력합니다:
```bash theme={null}
bridge 0.0001 sol 0xYourTwin --call-contract 0x311935Cd80B76769bF2ecC9D8Ab7635b2139cf82 \
--call-selector "transfer(address,uint256)" \
--call-args 0x0000000000000000000000000000000000000000 100000000000000
```
워크플로우:
1. **명령 파싱:** 터미널 파서가 자산, 목적지, 선택적 Base 호출(셀렉터 + 인수 + 값)을 분석합니다.
2. **브릿지 스테이징:** `queueBridge`가 SPL 오버라이드를 검증하고, `encodeFunctionData`를 통해 Base 호출을 ABI 인코딩하며, 릴레이 오버라이드를 스테이징합니다.
3. **실행:** `solanaBridge.bridge()`가 목적지(ENS/Basename)를 분석하고, 잔액을 확인하며, `realBridgeImplementation`을 호출하여 Solana 트랜잭션에 서명하고 전송합니다.
4. **릴레이 + 호출:** 릴레이 가스가 선불로 지불된 경우, Base 릴레이어는 ERC20 SOL이 민팅된 직후 사용자의 Twin 컨트랙트에서 첨부된 호출을 실행합니다.
핵심 구현 참조:
* `src/lib/bridge.ts`: 자산 분석(민트 주소 지원), 환경 인식 RPC 연결, 호출 첨부 지원.
* `src/lib/realBridgeImplementation.ts`: 환경별 PDA 및 가스 수신자를 사용하여 `PayForRelay` + `bridge_sol`/`bridge_spl` 명령으로 Solana 트랜잭션을 빌드합니다.
* `src/components/MainContent.tsx`: 명령 스테이징, 로그 뷰어, 임의 Base 호출을 위한 ABI 인코딩이 포함된 터미널 UI.
* `src/components/WalletConnection.tsx`: 연결된 Solana 지갑을 위해 Base Mainnet/Sepolia에서 결정론적 Twin 주소를 가져옵니다.
### 터미널 실행
```bash Terminal theme={null}
git clone https://github.com/base/sol2base.git
cd sol2base
npm install --legacy-peer-deps
# Configure env (RPC URLs, relayer addresses, CDP API keys, etc.)
cp env.template .env.local
npm run dev # defaults to http://localhost:3000
```
터미널은 Base Sepolia ↔ Solana Devnet과 Base Mainnet ↔ Solana Mainnet 모두를 노출합니다. UI의 네트워크 드롭다운을 사용하여 전환하세요.
`.env` 파일에 `CDP_API_KEY`를 설정하면 파우셋에 접근할 수 있습니다.
## 컨트랙트 주소
### Base 메인넷
```json theme={null}
{
"Bridge": "0x3eff766C76a1be2Ce1aCF2B69c78bCae257D5188",
"BridgeValidator": "0xAF24c1c24Ff3BF1e6D882518120fC25442d6794B",
"CrossChainERC20Factory": "0xDD56781d0509650f8C2981231B6C917f2d5d7dF2",
"SOL": "0x311935Cd80B76769bF2ecC9D8Ab7635b2139cf82"
}
```
### Solana 메인넷
```json theme={null}
{
"BridgeProgram": "HNCne2FkVaNghhjKXapxJzPaBvAKDG1Ge3gqhZyfVWLM",
"BaseRelayerProgram": "g1et5VenhfJHJwsdJsDbxWZuotD5H4iELNG61kS4fb9"
}
```
### Base Sepolia
```json theme={null}
{
"Bridge": "0x01824a90d32A69022DdAEcC6C5C14Ed08dB4EB9B",
"BridgeValidator": "0xa80C07DF38fB1A5b3E6a4f4FAAB71E7a056a4EC7",
"CrossChainERC20Factory": "0x488EB7F7cb2568e31595D48cb26F63963Cc7565D",
"SOL": "0xCace0c896714DaF7098FFD8CC54aFCFe0338b4BC",
"FLYWHEEL_ADDRESS": "0x00000F14AD09382841DB481403D1775ADeE1179F",
"BRIDGE_CAMPAIGN_ADDRESS": "0xE2AD1C34382410C30d826B019A0B3700F5c4e6c9"
}
```
### Solana Devnet
```json theme={null}
{
"BridgeProgram": "7c6mteAcTXaQ1MFBCrnuzoZVTTAEfZwa6wgy4bqX3KXC",
"BaseRelayerProgram": "56MBBEYAtQAdjT4e1NzHD8XaoyRSTvfgbSVVcEcHj51H",
"GasFeeReceiver": "AFs1LCbodhvwpgX3u3URLsud6R1XMSaMiQ5LtXw4GKYT"
}
```
## 리소스
소스 코드, 컨트랙트, 프로그램, 스크립트
Solana mainnet-beta 트랜잭션 모니터링
Base 메인넷 트랜잭션 모니터링
Base 커뮤니티에서 도움 받기