seeker-connect

Seeker Connect

Seeker Connect は、ブラウザーでデバイス上に開いている Web ページを、Solana Mobile 認定デバイス専用のウォレットに接続します。Seeker は、そのようなデバイスの第 1 号です。公式の Mobile Wallet Adapter ライブラリを基盤とする、dapp 専用 SDK です。プロトコルを再実装するのではなく、UX/DX レイヤーを提供します。汎用的な MWA では「ウォレットを選択」する画面が中心ですが、Seeker Connect は MWA 仕様のエンドポイント固有 URI（Android App Link）メカニズムを通じてデバイスのウォレットを直接起動し、Nostr リレー経由でセッションを維持します。また、Seeker ブランドの進行状況表示とエラー UI を提供し、アプリには 「Seeker Connect」 という名前の通常の Wallet Standard ウォレットとして公開されます。

対象：Expo ／ React Native、Kotlin、Web のすべてが利用できます。 Expo または React Native アプリの場合は、まず以下の基本的な考え方を読んでから、references/react-native.md に進んでください。Kotlin アプリの場合は、references/kotlin.md を参照してください。npx solana-mobile@latest create の expo-kit-minimal および kotlin-compose-minimal テンプレートには、それぞれの実装が組み込み済みです。どちらも Web と同じクライアント API を公開し、リレーの設定は不要で、ブランド UI はネイティブに描画されます。このファイルの残りの部分では Web の実装について説明します。Seeker Connect を使わずに React Native で通常の Mobile Wallet Adapter を使用する場合は、solana-mobile-wallet スキルを参照してください。

基本的な考え方 — コードを書く前に読んでください

• 永続的な接続はありません。 ウォレットとのやり取り（接続、メッセージへの署名、トランザクションへの署名）のたびに、個別の短時間の MWA セッションを開き、リクエストを 1 つ実行してから終了します。やり取りのたびにウォレットアプリが起動し、ブランド付きの進行状況オーバーレイが表示されます。例外はサイレント接続で、キャッシュを読み取るだけでセッションは開きません。これは意図された動作です。再接続ループやキープアライブのロジックを組み込まないでください。
• 「接続済み」とは「キャッシュされた認証情報を保持している」という意味です。 最初の connect() では、ウォレットが発行した authToken とアカウント、機能が保存されます（既定では localStorage）。以降の操作ではこのトークンをサイレントに再利用するため、同意を繰り返し求めるプロンプトは表示されません。
• 切断時に行われるのは、トークンをローカルで破棄することだけです。 切断するためだけにウォレットアプリが起動することがないよう、意図的にウォレットの deauthorize は呼び出しません。
• デバイス上でのみ完了します。 デスクトップでは association-failed で接続に失敗します。通常は、ウォレット起動に応答するものがない場合、数秒以内に失敗します。アソシエーションのタイムアウトが適用されるのは、ウォレットが起動しても接続しない場合のみです。ウォレットは常に登録してください。ほかの環境ではアソシエーションの段階を通過できないだけです。
• SDK に既定のリレーは含まれていません。 Solana Mobile の relay.solanamobile.com を使用してください。本番環境を含め、無料で利用できます。利用には Solana Mobile の規約への同意が必要なので、開発者に同意するよう伝えてください — Step 2。

Step 1: インストール

新規プロジェクト： Solana Mobile CLI の react-kit-shadcn テンプレートには、Solana Mobile のリレー上で Seeker Connect がすでに設定されています。次に、create が出力する手順に従って、クイックスタートページでリレーの利用規約に同意するよう開発者に伝えてください。

npx solana-mobile@latest create my-app --template react-kit-shadcn

既存のアプリ： 以下のスニペットでインポートする Wallet Standard エントリーポイントと Wallet Standard ヘルパーをインストールします。

npm install @solana-mobile/seeker-connect-wallet-standard @solana/wallet-standard-features @wallet-standard/app @wallet-standard/features

0.1.2 以降を使用してください。それ以前のリリースは Mobile Wallet Adapter 2.x を使用しているため、セッションが切断されるとウォレット呼び出しが永久に保留されることがあります。0.1.2 では MWA 3.0 に移行し、代わりに session-closed で拒否されます。

Wallet Standard パッケージは、他の Seeker Connect パッケージ（core、ui、web）を依存関係として取り込みます。ただし、これらは再エクスポートされません。そのため、アプリが直接インポートするパッケージもインストールしてください（以下のオプションのボタンには @solana-mobile/seeker-connect-ui、リファレンスの命令型パスには @solana-mobile/seeker-connect-web）。pnpm のような厳格なパッケージマネージャーでは、宣言されていない推移的依存関係のインポートが拒否されます。

パッケージ	役割
@solana-mobile/seeker-connect-core	共通コントラクト：設定、エラー分類、SeekerLink ポート
@solana-mobile/seeker-connect-ui	Lit 要素：進行状況オーバーレイ、エラーダイアログ、ブランドボタン
@solana-mobile/seeker-connect-wallet-standard	エントリーポイント — Wallet Standard ウォレット
@solana-mobile/seeker-connect-web	Nostr 経由の MWA トランスポートと命令型 SDK

Step 2: リレーを設定する

Seeker Connect は、relayDomain で指定される Nostr リレーを介して、MWA の拡張リモート通信プロトコルを転送します。ペイロードは dapp とウォレット間でエンドツーエンド暗号化され、リレーが運ぶのは暗号文のみです。

relay.solanamobile.com を使用してください。 Solana Mobile は Seeker Connect 向けにこのリレーを運用しており、本番環境を含め無料で使用できます。ホスト名のみを指定してください。SDK が wss:// スキームを追加します。

リレーの利用規約に同意するよう開発者に伝えてください。 Solana Mobile のリレーを使用するには、Solana Mobile の利用規約への同意が必要です。リレーを組み込む際は必ずその旨を伝え、利用規約に同意できるクイックスタートページを開発者に案内してください。 https://docs.solanamobile.com/solana-mobile-stack/seeker-connect-quickstart

Step 3: 起動時に一度登録する

UI のレンダリング前に registerSeekerConnect を呼び出し、最初のレンダリングからウォレット検出の対象になるようにします。ブラウザー内で実行する必要があります。以下のスニペットは window を読み取るため、SSR（Next.js など）の場合はクライアント専用モジュールに呼び出しを置くか、typeof window !== 'undefined' でガードしてください。クライアントのみでレンダリングする通常のアプリでは、エントリーファイルのモジュールスコープに置いて問題ありません。

import { registerSeekerConnect } from '@solana-mobile/seeker-connect-wallet-standard';

registerSeekerConnect({
  identity: {
    name: 'My Dapp',
    uri: window.location.origin,
    icon: '/icon.png', // resolved relative to uri; shown in the wallet's consent UI
  },
  relayDomain: 'relay.solanamobile.com', // requires accepting Solana Mobile's terms — Step 2
});

設定：

オプション	必須	備考
associationTimeoutMs	いいえ	association-failed になるまで、起動にかけられる時間です。デフォルトは 30s です
chain	いいえ	認証時に要求するチェーンです。デフォルトは solana:mainnet です
firstConnectWalletBaseUri	いいえ	Solana Mobile が貼り付ける値を公開するまでは、未設定のままにしてください。未設定の場合、初回接続では汎用の solana-wallet: スキームが使われます。設定すると、そのホストにページが移動します。references/troubleshooting.md を参照してください
identity	はい	name、uri、任意の icon です。ウォレットの同意 UI に表示されます
relayDomain	はい	セッショントラフィックを運ぶ Nostr リレーです。Step 2 の relay.solanamobile.com を使用してください

registerSeekerConnect は、seekerLink、authorizationCache、presenter のオーバーライドも受け付けます。references/imperative-api.md を参照してください。

ステップ 4：ほかのウォレットと同じように使う

登録後、「Seeker Connect」は Wallet Standard レジストリに表示されるため、wallet-adapter、ConnectorKit、@solana/react-hooks、または @wallet-standard/app の生の一覧から、追加の配線なしで検出できます。既存の接続ボタンと署名コードはそのまま動作します。

公開される機能：standard:connect、standard:disconnect、standard:events、solana:signMessage、solana:signIn、そして初回接続後にウォレットが報告する機能に応じて、solana:signTransaction および／または solana:signAndSendTransaction。

ウォレットを直接操作する場合：

import { SeekerConnectWalletName } from '@solana-mobile/seeker-connect-wallet-standard';
import { getWallets } from '@wallet-standard/app';
import { StandardConnect } from '@wallet-standard/features';

const seeker = getWallets()
  .get()
  .find((wallet) => wallet.name === SeekerConnectWalletName);
const { accounts } = await seeker.features[StandardConnect].connect();

ページ読み込み時にサイレント接続してセッションを復元します。キャッシュを読み取り、ウォレットを起動せず、キャッシュがない場合はアカウント数 0 件で解決します。

const { accounts } = await seeker.features[StandardConnect].connect({ silent: true });

署名ルートを機能検出します。初回接続までは、両方のトランザクション機能が使えるものとして扱われます。接続後は、standard:events の change イベントで通知されるウォレットの実際の機能に基づいて再判定されます。呼び出す前に確認してください。

import { SolanaSignAndSendTransaction } from '@solana/wallet-standard-features';

const feature = seeker.features[SolanaSignAndSendTransaction];
if (feature) {
  const [{ signature }] = await feature.signAndSendTransaction({
    account,
    chain: seeker.chains[0],
    transaction,
  });
}

chain は Wallet Standard の入力の一部ですが、このウォレットでは無視されます。ネットワークは registerSeekerConnect に渡されたものが使用され、呼び出しのたびにキャッシュされた認証情報から再現されます。この 2 つは相互に照合されないため、mainnet で登録した状態で呼び出しごとに solana:devnet を指定しても、警告なしで mainnet に送信されます。両者が食い違わないよう seeker.chains[0] を渡し、ネットワークを変更するときは登録時に指定してください。

トランザクションは、シリアライズ済みの生バイト列（Uint8Array）として機能境界を越えます。legacy と v0 の両方に対応しています。アプリですでに使用しているクライアントライブラリでシリアライズしてください。サインインは solana:signIn を通じて SIWS 仕様に従います。domain のデフォルト値は window.location.host です。

サインインでユーザーを認証する場合、権限を持つのはクライアントではなくサーバーです。サーバー側で 1 回限りの短命な nonce を発行し、セッションを作成する前に、期待されるドメインと有効期間を含め、返されたメッセージと署名をサーバー側で検証してください。seeker-genesis-token スキルでは、このサーバーフローを順を追って説明しています。

コードでエラーを処理する

ウォレットの処理結果が失敗すると、code を持つ SeekerConnectError で拒否されます。

コード	意味
association-failed	タイムアウト、リレーへの到達不能または設定ミス、あるいは Seeker 以外の端末であるなどの理由で、どのウォレットも起動を完了できませんでした
authorization-declined	ユーザーが認証を拒否しました。キャッシュされたトークンは消去され、次回の接続では改めて同意を求めます
cancelled	ユーザーが進行状況オーバーレイを閉じました。通常の結果であり、エラーとして表示してはいけません
request-declined	ウォレットが署名または送信を拒否しました
session-closed	処理が完了する前にセッションが終了しました。signAndSendTransaction の後でもトランザクションが送信済みの可能性があり、このエラーには署名が含まれません。自動再試行は絶対に行わないでください。references/troubleshooting.md を参照してください
wallet-error	その他のウォレットから報告されたエラー

そのほか、通常の Error になる失敗が 3 つあります。これらはウォレットの処理結果ではなく、使い方の誤りです。signAndSendTransaction に対応していないと報告したウォレットでこれを呼び出す場合、接続に成功する前に署名を呼び出す場合、そしてウォレットが結果なしで応答したサインインです。

この違いによって、誰がエラーを表示するかが決まります。ブランド付きダイアログが起動するのは SeekerConnectError の場合に限られ、それ以外では起動しません。上記のコードのうち、通常の結果として何も表示せずに処理される cancelled を除くすべてが対象です。3 つの通常の Error はプレゼンターに届かないため、アプリが何も表示しない場合、気づかれないまま失敗します。まず型を判定し、次に .code を判定してください。

import { SeekerConnectError, SeekerConnectErrorCode } from '@solana-mobile/seeker-connect-wallet-standard';

try {
  await seeker.features[StandardConnect].connect();
} catch (error) {
  if (error instanceof SeekerConnectError) {
    if (error.code === SeekerConnectErrorCode.cancelled) {
      return; // user closed the overlay; nothing to report
    }
    // The SDK has shown its dialog. Log, and leave the UI in the disconnected state.
    console.error(error);
    return;
  }
  // No dialog was shown for this one. Surface it yourself.
  showToast('Could not connect to the wallet.'); // your app's own error UI
  console.error(error);
}

オプション：ブランド付きの接続ボタン

@solana-mobile/seeker-connect-ui には、Shadow DOM を使うカスタム要素 <seeker-connect-button> が含まれているため、ホスト側の CSS は不要です。SDK は要素を初回使用時に定義します。起動時に defineSeekerConnectElements() を呼び出すと、事前に定義できます。

import { defineSeekerConnectElements } from '@solana-mobile/seeker-connect-ui';

defineSeekerConnectElements();

<seeker-connect-button theme="dark" variant="sign-in"></seeker-connect-button>

属性は disabled、theme="light" | "dark"（ホストページのテーマを指定）、およびラベル用の variant="connect"（デフォルト）または variant="sign-in" です。click を接続またはサインインの呼び出しに結び付ける処理は、ご自身で行ってください。このボタンは表示専用です。

リファレンス資料

• references/kotlin.md — Kotlin SDK：Gradle のセットアップ、SeekerConnect コンストラクター、クライアントメソッド、Compose ボタンとダイアログ、SeekerConnectException のコード
• references/react-native.md — React Native パッケージ：インストール、https の必須要件、クライアントメソッド、ネイティブボタン
• references/imperative-api.md — createNostrSeekerLink().transact を使う Wallet Standard 非対応の方法、および seekerLink ／ authorizationCache ／ presenter のオーバーライド
• references/troubleshooting.md — 関連付けの失敗、デスクトップでのテスト、機能のケイパビリティに基づく判定、キャッシュの動作

関連スキル

• seeker-domains — アドレスの代わりに .skr 名を表示します
• seeker-genesis-token — 接続後に Seeker デバイスの所有権を確認します
• solana-mobile — solana-mobile create を支える CLI、テンプレート、ツールチェーン
• solana-mobile-wallet — Seeker Connect を使わず、Mobile Wallet Adapter を直接使って React Native アプリでウォレットを接続します

リンク

• MWA の Web ドキュメント：https://docs.solanamobile.com/get-started/web/installation
• Seeker Connect のドキュメント：https://docs.solanamobile.com/solana-mobile-stack/seeker-connect
• Seeker Connect のクイックスタート（リレーの利用条件はこちらに記載されています）：https://docs.solanamobile.com/solana-mobile-stack/seeker-connect-quickstart
• Seeker Connect リポジトリ：https://github.com/solana-mobile/seeker-connect