본문으로 건너뛰기

릴레이로 지갑 연결

릴레이 연결을 사용하면 데스크톱 dApp의 QR을 모바일 지갑으로 스캔하거나, 같은 기기에서 딥링크를 열어 지갑 세션을 수립할 수 있습니다. 사용자가 승인하면 transport: "relay"인 WalletConnection이 활성 세션이 됩니다.

Scope Connect(scope)처럼 브라우저에 주입된 프로바이더가 없는 릴레이 전용 지갑은 이 흐름으로 연결합니다. @scope-connect/appkit-react는 UI 없는 appKit.pair()를 useWalletConnection 훅으로 감싸, 페어링 URI를 pairingUri로 노출하고 <PairingQr />로 렌더링합니다. connect("scope")처럼 릴레이 지갑 ID를 넘기면 훅이 내부에서 pair()를 호출하고 릴레이 경로로 자동 전달합니다.

이 가이드는 React 바인딩에서 설명하는 Provider 마운트와 훅 구성을 전제로 합니다.

준비 사항​

  • React 18 이상 프로젝트에 @scope-connect/appkit-react 설치 및 ScopeAppKitProvider 마운트 (React 바인딩)
  • QR을 표시할 화면과 사용자의 취소·재시도 동작

릴레이에는 추가 config가 필요하지 않습니다. 릴레이 WSS 엔드포인트는 @scope-connect/appkit 빌드 시점에 고정되며(DEFAULT_RELAY_URL), dApp이 런타임에 다른 릴레이를 지정할 수 없습니다. clientId는 필수 옵션이고, 백엔드 루트도 같은 방식으로 빌드 시점에 고정됩니다.

app/providers.tsx
"use client";

import dynamic from "next/dynamic";
import type { ReactNode } from "react";
import type { ScopeAppKitConfig } from "@scope-connect/appkit-react";

// 커넥터가 window에 접근하므로 클라이언트에서만 마운트합니다.
const ScopeAppKitProvider = dynamic(
() => import("@scope-connect/appkit-react").then((m) => m.ScopeAppKitProvider),
{ ssr: false },
);

export function AppKitProviders({ children }: { children: ReactNode }) {
// 릴레이용 추가 설정은 없습니다 — 엔드포인트는 SDK에 빌드 시점에 고정됩니다.
const config: ScopeAppKitConfig = {
dappName: "Example dApp",
clientId: process.env.NEXT_PUBLIC_APPKIT_CLIENT_ID,
};

return <ScopeAppKitProvider config={config}>{children}</ScopeAppKitProvider>;
}

루트 레이아웃에서 앱을 감싸는 방법과 Next.js transpile·SSR 설정은 React 바인딩을 참고합니다.

1. 페어링 시작​

React에서는 appKit.pair()를 직접 호출하지 않습니다. useWalletConnection()의 connect(walletId)에 릴레이 지갑 ID("scope")를 넘기면, 훅이 내부에서 pair()를 호출하고 릴레이 경로로 전달합니다.

app/RelayConnect.tsx
"use client";

import { useWalletConnection } from "@scope-connect/appkit-react";

export function RelayConnect() {
const conn = useWalletConnection();

return (
<button
onClick={() => void conn.connect("scope")}
disabled={conn.connectionStatus === "connecting"}
>
Scope Connect로 연결
</button>
);
}

connect("scope")은 먼저 Connect 백엔드에서 릴레이 토큰을 받고 WebSocket을 연결한 뒤 페어링을 시작합니다. 요청할 체인·메서드·이벤트(requiredNamespaces)는 훅이 기본값으로 구성하며, connect("scope", "eip155:1")처럼 두 번째 인자로 특정 체인만 요청하도록 좁힐 수 있습니다.

requiredNamespaces를 직접 제어해야 한다면 useScopeAppKit()으로 얻은 AppKit 인스턴스의 pair()를 호출합니다. 이때 체인은 하드코딩하지 말고 getSupportedNetworks()로 SDK가 지원하는 EVM(eip155) 네트워크에서 가져옵니다.

const appkit = useScopeAppKit();

const eip155Chains = appkit
.getSupportedNetworks()
.filter((network) => network.namespace === "eip155")
.map((network) => network.chainId);

const pairing = await appkit.pair({
requiredNamespaces: {
eip155: {
chains: eip155Chains,
methods: ["eth_signTypedData_v4"],
events: ["accountsChanged", "chainChanged"],
},
},
metadata: { name: "Example dApp" },
});

methods에는 eth_signTypedData_v4를 반드시 포함합니다 — 현재 WalletKit 지갑이 릴레이 세션에서 서명하는 유일한 메서드이며, 지갑은 다른 메서드를 요청해도 세션을 eth_signTypedData_v4로 좁혀 승인하고 그 외 서명 요청은 거부합니다.

2. QR 표시​

connect("scope") 호출 직후 훅의 pairingUri가 scope: 페어링 URI로 채워집니다. 이 값을 <PairingQr />에 넘기면 QR로 렌더링됩니다. PairingQr는 내부에서 qrcode를 사용하므로 별도 설치가 필요 없습니다.

app/RelayConnect.tsx
"use client";

import { useWalletConnection, PairingQr } from "@scope-connect/appkit-react";

export function RelayConnect() {
const conn = useWalletConnection();

// 릴레이 페어링 중 → QR 표시
if (conn.pairingUri) {
return (
<div>
<PairingQr uri={conn.pairingUri} size={256} />
<p>지갑에서 QR을 스캔하고 연결을 승인하세요.</p>
</div>
);
}

// 시작 전 → 연결 버튼
return (
<button
onClick={() => void conn.connect("scope")}
disabled={conn.connectionStatus === "connecting"}
>
Scope Connect로 연결
</button>
);
}

pairingUri는 페어링 중에만 null이 아닌 값이고, 연결이 완료되거나 실패하면 다시 null이 됩니다. 같은 기기에서는 이 값이 곧 scope: URI이므로 버튼에서 window.location.assign(conn.pairingUri)로 열 수 있으나, 대상 지갑이 scope: URI 스킴을 등록한 경우에만 표시합니다.

페어링 URI는 비밀값입니다

pairingUri에는 세션 대칭키인 symKey가 포함됩니다. 이 값과 QR 원문을 로그·오류 추적·분석 이벤트·영구 저장소에 남기거나 URL query로 전달하지 않습니다. 화면을 닫거나 실패하면 기존 값을 재사용하지 말고 disconnect()으로 정리한 뒤 새 connect()로 다시 시작합니다.

3. 지갑 승인 기다리기​

UI 없는 AppKit을 직접 사용할 때는 pairing.session을 await하지만, React에서는 훅의 connectionStatus를 관찰합니다. 지갑이 연결 제안을 승인하고 세션 연결을 마치면 connectionStatus가 "connected"로 바뀌고 connectedAddress·displayAddress가 채워집니다.

// 연결됨 → 계정 표시
if (conn.connectionStatus === "connected" && conn.connectedAddress) {
return (
<div>
<p>연결됨: {conn.displayAddress}</p>
<button onClick={() => void conn.disconnect()}>연결 해제</button>
</div>
);
}

connectedAddress는 전체 계정 주소, displayAddress는 축약 표시용 주소입니다. 연결된 세션은 릴레이 전송을 사용하며, 이후 useScopeAppKit()으로 얻은 AppKit 인스턴스의 request()·서명 호출이 활성 릴레이 세션으로 전달됩니다. 이 블록을 기본 제공 <ConnectedCard />로 대체할 수도 있습니다.

4. 오류 처리​

훅은 릴레이 오류를 세부 코드가 아니라 상태로 축약해 노출합니다. 두 가지를 구분해 처리합니다.

  • notInstalledWalletId === "scope" — 현재 AppKit 설정으로 페어링을 시작할 수 없는 상태입니다(INVALID_CONFIG). 릴레이 엔드포인트는 빌드에 고정돼 있으므로, 남는 원인은 AppKit 자체 설정(예: 초기화 누락)입니다.
  • connectionStatus === "failed" — 세션 연결 실패입니다. 승인 시간 만료(SESSION_TIMEOUT), 지갑의 세션 응답 검증 실패(INVALID_RESPONSE), 릴레이 연결 종료 등이 모두 여기로 모입니다. 훅은 실제 원인을 콘솔에 기록합니다.

사용자가 지갑에서 거절하면(USER_REJECTED) status는 실패가 아니라 "idle"로 돌아갑니다. 실패 원인을 코드로 분기해 안내하려면 훅의 lastError를 읽습니다 — 마지막 연결 실패의 AppResultCode와 메시지를 담고, 재시도하면 초기화됩니다(useWalletConnection 반환값).

앞 절들의 분기를 하나로 모은 전체 컴포넌트입니다.

app/RelayConnect.tsx
"use client";

import { useWalletConnection, PairingQr } from "@scope-connect/appkit-react";

export function RelayConnect() {
const conn = useWalletConnection();

// 릴레이 미설정 → config 안내
if (conn.notInstalledWalletId === "scope") {
return <p>이 환경에서는 Scope Connect 지갑을 사용할 수 없습니다.</p>;
}

// 연결됨 → 계정 표시
if (conn.connectionStatus === "connected" && conn.connectedAddress) {
return (
<div>
<p>연결됨: {conn.displayAddress}</p>
<button onClick={() => void conn.disconnect()}>연결 해제</button>
</div>
);
}

// 실패 → 새 QR로 재시도
if (conn.connectionStatus === "failed") {
return (
<div>
<p>연결에 실패했습니다. 새 QR로 다시 시도하세요.</p>
<button onClick={() => void conn.connect("scope")}>다시 시도</button>
</div>
);
}

// 페어링 중 → QR 표시
if (conn.pairingUri) {
return (
<div>
<PairingQr uri={conn.pairingUri} size={256} />
<p>지갑에서 QR을 스캔하고 연결을 승인하세요.</p>
<button onClick={() => void conn.disconnect()}>취소</button>
</div>
);
}

// 그 외(idle/connecting) → 연결 버튼
return (
<button
onClick={() => void conn.connect("scope")}
disabled={conn.connectionStatus === "connecting"}
>
Scope Connect로 연결
</button>
);
}

세부 오류 코드(RelayConnectionError, RelayRpcError, AppResultCode)로 분기해야 한다면 훅 대신 useScopeAppKit()이 반환하는 AppKit 인스턴스의 pair()를 직접 호출해 try/catch로 분류합니다. WebSocket close code와 릴레이 RPC code는 AppKit 릴레이 오류, 세션 오류 코드는 AppResultCode를 기준으로 대응합니다.

5. 시간 초과와 화면 닫기 처리​

현재 proposal 승인과 session settle은 각각 300초 제한을 사용하며 바꿀 수 없습니다. 시간이 초과되면 connectionStatus가 "failed"로 바뀌므로, 진행 상태에는 정확한 남은 시간을 알려 주기보다 "지갑에서 승인 대기 중"이라고 표시하고 실패 시 connect("scope")로 재시도하게 합니다. 기본 제한은 제한 시간에서 확인합니다.

사용자가 QR 화면을 닫으면 disconnect()으로 진행 중인 페어링을 정리합니다. 훅의 disconnect()은 진행 중인 pair()를 무효화하고 pairingUri와 상태를 초기화하므로, 이후에는 새 connect()만 허용됩니다.

// useWalletConnection()에서 얻은 conn을 사용하는 취소 핸들러
async function closePairing() {
try {
await conn.disconnect();
} catch {
// 화면은 닫되, 로깅에 pairingUri를 포함하지 않습니다.
}
}

다음 단계​