mini-apps

Nimiq ミニアプリ

ミニアプリは、モバイルの WebView で Nimiq Pay 内で実行されるウェブアプリケーションです。注入されたプロバイダーを通じてウォレットと通信します。アプリはサンドボックス内で実行され、秘密鍵にはアクセスできません。機密性の高い操作にはすべて、ネイティブダイアログを通じたユーザーの承認が必要です。

進め方

開発者の依頼から進め方が明らかな場合は、該当する手順に直接進んでください。

• 新しいものの構築、作成、開始、またはひな形の作成を希望している → references/scaffold.md を読み、手順に従います
• 既存のコードを変換、移植、移行、または適合させたい → references/convert.md を読み、手順に従います
• リリース前の確認、レビュー、検証、または監査を希望している → references/checklist.md を読み、手順に従います
• すでに開発中で、具体的な質問がある → 以下のルールに従い、必要に応じて API リファレンスを参照します

背景情報がない状態で呼び出された場合、または意図が不明確な場合は、以下の選択肢を提示して、開発者に選んでもらってください。

1. 最初から始める — アイデアはありますが、プロジェクトはまだありません
2. 既存のアプリを変換する — Nimiq Pay 内で実行したいウェブアプリがあります
3. アプリの準備状況を確認する — リリース前にミニアプリを検証したいです
4. 開発を進める — すでに開発中で、ルールと API の情報だけが必要です

推測しないでください。開発者が必要としているものを理解するまで、リファレンスを読み込まないでください。

ひな形作成または変換の手順を完了した後は、必ず最終ステップとしてチェックリスト（references/checklist.md）を実行してください。いずれの手順でも、開発者がアプリの完成、準備完了、または完了を伝えた場合は、チェックリストを実行してください。

プロバイダー

利用可能なプロバイダーは 2 種類です。アプリの要件に応じて、一方または両方を使用してください。

Nimiq プロバイダー

NIM の支払い、メッセージ署名、ステーキング、ブロックチェーンの状態照会に使用します。Mini App SDK の init() ヘルパーを通じてのみアクセスしてください。それ以外の方法でアクセスしないでください。

import { init } from '@nimiq/mini-app-sdk'

const nimiq = await init()

利用可能な機能：

• アカウントへのアクセス：ユーザーの Nimiq アドレスを一覧表示します。ユーザーの確認が必要です。
• メッセージ署名：ユーザーの Nimiq キーで任意のメッセージに署名します。ユーザーの確認が必要です。
• コンセンサスとブロックの状態：ウォレットがネットワークのコンセンサスを確立しているか確認し、現在のブロック高を取得します。確認は不要です。
• NIM の支払い：基本的な NIM トランザクションを、テキストデータを添付する場合としない場合のどちらでも送信します。ユーザーの確認が必要です。金額の単位は Luna です（1 NIM = 100,000 Luna）。メソッド：sendBasicTransaction、sendBasicTransactionWithData。
• ステーキング：いずれもユーザーの確認が必要です。機能とメソッドの対応は次のとおりです。新しいステーカーを作成する（sendNewStakerTransaction）、ステークを追加する（sendStakeTransaction）、アクティブなステークを設定する（sendSetActiveStakeTransaction）、委任を更新する（sendUpdateStakerTransaction）、ステークを引退させる（sendRetireStakeTransaction）、ステークを削除する（sendRemoveStakeTransaction）。

メソッドの正確なシグネチャ、パラメーター、戻り値の型については、references/nimiq-provider-api.md を参照してください。

Ethereum プロバイダー

EVM チェーンとのやり取り、ERC-20 トークン、メッセージ署名、コントラクト呼び出しに使用します。window.ethereum からアクセスします。標準の EIP-1193 プロバイダーです。SDK は不要です。

利用できる機能：

• アカウントへのアクセス：ユーザーの Ethereum アドレスをリクエストします。同じアドレスをすべての EVM チェーンで使用できます。ユーザーの確認が必要です。
• メッセージ署名：型付き構造化データ（許可、注文の承認、ログインチャレンジ）には、eth_signTypedData_v4（EIP-712）を優先してください。署名対象を不透明なハッシュではなく、読みやすい形式でユーザーに提示できます。構造として表示する必要のないプレーンテキストメッセージに限り、personal_sign を使用してください。どちらもユーザーの確認が必要です。
• トランザクション：ネイティブトークンの送金またはコントラクト呼び出しを実行します（eth_sendTransaction）。ユーザーの確認が必要です。
• チェーン管理：アクティブな EVM チェーンを切り替える（wallet_switchEthereumChain）か、新しいチェーンを追加します（wallet_addEthereumChain）。ユーザーの確認が必要です。
• 読み取り専用のクエリ：残高の取得、コントラクトの呼び出し、ガスの見積もり、ブロックとログの読み取り、トランザクションレシートの取得を行います。確認は不要です。RPC 経由でルーティングされます。
• 任意の RPC：rpcCall は、標準リストにないメソッドの JSON-RPC リクエストをホスト経由でプロキシします。使用は必要最低限にし、上記の型付きメソッドを優先してください。
• 検出：Nimiq Pay は EIP-6963 を実装しているため、ウォレット検出ライブラリー（wagmi、RainbowKit など）が自動的に検出します。プロバイダーを手動で通知する必要はありません。

正確なメソッドシグネチャー、パラメーター、戻り値の型については、references/ethereum-provider-api.md を参照してください。

サポート対象の EVM チェーン

現在 Nimiq Pay で公開されているチェーンは以下のとおりです。wallet_addEthereumChain を使用してカスタムチェーンを追加できます。Sepolia は開発とテスト専用です。Sepolia 上でトランザクションを実行するミニアプリを、実際のユーザーに公開しないでください。

チェーン ID、トークンアドレス、小数点以下の桁数については、references/chains-and-tokens.md を参照してください。

ERC-20 トークンのルール

サポート対象のチェーン上にある ERC-20 トークンは、すべて window.ethereum からアクセスできます。カスタムプロバイダーや追加設定は不要です。

手順は常に次のとおりです：

1. wallet_switchEthereumChain で正しいチェーンに切り替えます
2. eth_call（balanceOf などの読み取り）または eth_sendTransaction（transfer などの書き込み）を使用して、トークンコントラクトを呼び出します

ABI エンコードには EVM ライブラリー（viem、ethers.js、または wagmi）を使用してください。コントラクト呼び出しを手動でエンコードしないでください。

USDT と USDC の小数点以下の桁数は 6 桁で、ほとんどの ERC-20 トークンで使われる 18 桁ではありません。金額の解析やフォーマットには、必ずトークンの実際の decimals 値を使用してください。1 USDT の残高を小数点以下 18 桁で表示すると、1.0 ではなく 0.000000000001 と表示されます。

モバイルファースト

ミニアプリはモバイル端末上の Nimiq Pay 内で動作します。UI に関するあらゆる判断で、この点を考慮してください。

• 小さな画面を優先して設計してください。デスクトップ専用のレイアウトは避けてください。
• タップしやすいタップ領域（最小 44px）を使用してください。
• 横スクロールを避けてください。
• デスクトップブラウザーだけでなく、実機またはデバイスエミュレーションでテストしてください。

ユーザーの言語

Nimiq Pay は、ユーザーが選択した言語を window.nimiqPay.language で公開します。この値は ISO 639-1 の 2 文字コード（例：'en'、'de'）で、ページスクリプトの実行前に挿入され、読み取り専用で、セッション中は固定です。ローカライズや i18n を使うものを構築する場合は、この値を使用してユーザーの Nimiq Pay の言語設定に合わせてください。

Nimiq ネットワーク

Nimiq Pay が実行されている Nimiq ネットワークは window.nimiqPay.network（'mainnet' または 'testnet'）で公開されており、@nimiq/mini-app-sdk 0.2.4 以降では getHostNetwork() からも取得できます。ページスクリプトの実行前に挿入され、読み取り専用で、セッション中は固定です。Nimiq Pay の外部や古いバージョンの Nimiq Pay では undefined になるため、'mainnet' にフォールバックしてください。ミニアプリでネットワークごとに異なるエンドポイント、エクスプローラーリンク、アドレスを使用する場合は、この値に基づいて選択してください。

フルスクリーン

Mini Appでフルスクリーン表示が必要な場合は、フルスクリーンにするなどのわかりやすいユーザー操作を用意し、ユーザーが選択したときにwindow.nimiqPay.requestFullscreen()を呼び出してください。@nimiq/mini-app-sdk 0.2.3以降では、対応するrequestFullscreen()、exitFullscreen()、getFullscreen()、onFullscreenChange()のヘルパーがエクスポートされます。Nimiq Payでは承認プロンプトは表示されません。ネイティブ側からの終了を追跡し、ホストで利用可能か確認して、呼び出しが拒否された場合に対処してください。

外部 API とバックエンド

Mini Appは外部 APIを呼び出したり、サーバー側のバックエンドを利用したりできますし、そうするべきです。これにより、Mini Appをより充実させることができます。唯一の制約は、ウォレット操作（決済、署名、アカウントへのアクセス）は、注入されたプロバイダー経由で行わなければならないことです。

Mini Appが開発者の管理するバックエンドを呼び出す場合、そのバックエンドはレスポンスヘッダーAccess-Control-Allow-OriginにMini Appのオリジンを含める必要があります。オリジンとは、Nimiq PayがMini Appを読み込んだURLです。

開発中、Mini Appはスマートフォン上のNimiq Payで実行されるため、WebView内のlocalhostは開発マシンではなくスマートフォンを指します。開発中にバックエンドもローカルで実行する場合は、fetchのURLにlocalhostではなく、開発マシンのLAN IP（例：http://192.168.x.x:3000）を指定してください。

承認ダイアログの UX

ユーザー確認が必要なプロバイダー呼び出しを、短時間に複数回実行しないでください。確認のたびに、ユーザーが応答する必要のあるネイティブダイアログが表示されます。複数の呼び出しをキューに追加すると、わかりにくい操作体験になります。読み取り専用の呼び出しは自由にまとめて実行できますが、確認が必要な呼び出しは、ユーザーの意図が明確になるよう、間隔を空けて順番に実行してください。

テストネットでのテスト

Nimiq Payには、ネットワークを切り替える隠し開発メニューがあります。設定ボタンを10秒間長押しすると表示されます。選択肢は、Default、Mainnet、Testnetです。

テストネットへの切り替えは、Nimiqプロバイダーの操作にのみ影響します。EVMの操作は、引き続きメインネットのチェーンに対して実行されます。EVMをテストするには、wallet_addEthereumChainを使って、開発者がカスタムチェーン（例：Sepolia）を追加できます。

決済やステーキングを伴うテストフローを提案する場合は、実際の資金を使わないよう、テストネットを推奨してください。

テストネットでは、「無料の NIM を取得」ボタンを押すと、1回のリクエストにつき110'000 NIMがアカウントに付与されます。このボタンは、ホーム画面の空の状態とチャージモーダル内に表示されます。

アンチパターン

次のことは行わないでください。

• 秘密鍵にアクセスしないでください。 アプリはサンドボックス内で実行されます。鍵がウォレットの外に出ることはありません。署名はすべて承認ダイアログを通じて行われます。
• 承認ダイアログを回避しないでください。 アカウントへのアクセス、署名、トランザクションなど、機密性の高い操作にはすべて、ネイティブのNimiq Payダイアログによるユーザーの明示的な確認が必要です。
• 決済にサードパーティーの決済プロバイダー（Stripe、PayPalなど）を使用しないでください。 NimiqおよびEthereumのプロバイダーのみを使用してください。

リファレンス

ドキュメント：

• Mini Appの概要
• 初めてのMini Appを作成する
• デュアルチェーンMini Appを作成する
• ローカルのMini Appを読み込む
• Mini AppでEVMトークンを使用する
• Mini Appのフルスクリーン表示
• Nimiq Provider API
• Ethereum Provider API

リファレンス実装：

• evm-mini-wallet — 対応するすべてのチェーンで、トークンの送受信と残高の追跡ができる、完全なEVMウォレットMini App
• nimiq-mini-app-demo — 対応するすべてのNimiqおよびEthereumプロバイダーメソッドのデモ

Nimiqのビジュアルアセット：

• Nimiq Design Kit