Using OISY Wallet in Your ICP dApp

This section seeks to help you connect the OISY Wallet to your dApp running on the Internet Computer (ICP). We'll start by explaining how dApps typically communicate with the Internet Computer and then explore how wallet integration, specifically with OISY, enhances this by enabling user-controlled actions.

Interacting with Canisters on ICP

The Standard Way: HttpAgent

Typically, dApps on the Internet Computer interact with canisters (smart contracts) using the HttpAgent provided by the @dfinity/agent-js library. This agent allows your frontend to call canister functions directly from the browser. For dApps that don't require users to sign transactions with a personal wallet (e.g., for read-only operations or when using Internet Identity for session-based authentication where the dApp might hold a temporary delegation), HttpAgent is the standard approach. It handles the low-level details of message encoding, signing (with an anonymous or delegated identity), and communication with IC replicas.

You can learn more about agent-js and HttpAgent in the Internet Computer developer documentation.

Integrating Wallets for User-Controlled Actions

When your dApp needs to perform actions on behalf of a user—like transferring tokens, voting, or making significant state changes that require the user's explicit approval and cryptographic signature from their own wallet—integrating a wallet like OISY becomes essential.

Instead of your dApp managing private keys or signing messages directly with a session identity that might have broad permissions, it delegates these sensitive operations to the user's wallet. The wallet then acts as a signer, prompting the user for consent before any action is taken, thus ensuring the user is always in control of their assets and identity.

The libraries discussed in this guide offer ways to create an agent or interact with wallet interfaces that route signing requests through the user's chosen wallet. This enables secure, user-authorized interactions with your dApp's canisters.

Why Different Integration Approaches?

Before diving into the specific methods to integrate OISY, it's helpful to understand why there are different options and their trade-offs. The best choice for your dApp depends on several factors:

• Development Framework: Are you building your dApp with React, or using another JavaScript framework, or perhaps vanilla JavaScript?

• User Interface (UI) Requirements: Do you prefer a pre-built, ready-to-use UI component for connecting wallets, or do you need to design and implement a custom UI to match your dApp's branding?

• Wallet Ecosystem Support: Do you plan to support only OISY, or do you want to offer users a choice of multiple wallets (e.g., Plug, NFID, Internet Identity) through a single integration?

• Control vs. Simplicity: Do you need fine-grained, low-level control over the wallet interaction process, or are you looking for the quickest and simplest way to enable basic wallet functionalities?

• Specific Features & Standards Adherence: Some libraries might offer more convenience for certain tasks, while others might focus on strict adherence to underlying ICRC standards for maximum interoperability.

Integration Options: Choose Your Way

Here are three primary ways to integrate OISY into your dApp:

1. IdentityKit: A comprehensive SDK, particularly well-suited for React applications. It provides UI components and makes it easy to support multiple wallets, including OISY. This is often the easiest way if you're using React.

2. signer-js: A lower-level TypeScript library that offers more control and flexibility. It's a good choice if you're not using React, need to build a custom UI, or want a standards-based approach that can work with any wallet following the relevant ICRC specifications.

3. @dfinity/oisy-wallet-signer: A lightweight, OISY-specific library developed by DFINITY. It's designed for straightforward integration if OISY is your primary or only wallet target and you need basic functionalities like connecting and requesting transfers.

Technical Deep Dive: Understanding the dApp <-> Wallet Connection on ICP

With the above integration options considered, let's explore the underlying mechanisms and standards that make these interactions possible. This section is for developers interested in the technical details behind wallet communication on the Internet Computer.

When we say "connect to a wallet" on ICP, it means your dApp (running in the user's browser) establishes a communication channel with the user's wallet application (like OISY, which also runs in the browser, often in a separate tab or popup). The primary goal is for your dApp to request actions (like signing transactions or messages) that the wallet will perform on behalf of the user, but only with their explicit permission.

Here is a typical sequence of events when a user connects OISY (or a similar ICRC-compliant wallet) to your dApp:

1. Initiate Connection & Get Identity: The dApp requests a connection. The wallet asks the user for permission to connect to the dApp. If granted, the wallet shares the user's unique ICP identity (Principal) and potentially Account Identifiers (addresses for ICP tokens or other ICRC-1 tokens) with the dApp.

2. Display User Context: Your dApp can now recognize the connected user. You might display their Principal, token balances, or other user-specific information.

3. Request Actions: When the user wants to perform a protected action (e.g., send tokens), your dApp constructs a request for this action and sends it to the wallet.

4. User Approval in Wallet: This is a critical step. The wallet receives the request from the dApp and displays a confirmation prompt to the user. This prompt clearly describes the action the dApp wants to perform (e.g., "Allow this dApp to send 1.0 ICP to address X?"). The user must explicitly approve this request within the wallet interface. The user is always in control and can reject any request.

5. Action Execution & Result: If the user approves, the wallet signs the transaction using the user's private keys (which are securely managed by the wallet) and sends it to the appropriate canister on the IC. The result of the transaction (success or failure) is then relayed back to the dApp.

ICP Wallet Signer Standards (The Rules): To ensure interoperability between various dApps and wallets in the ICP ecosystem, the community has developed a set of rules and protocols, primarily through ICRC Standards. OISY Wallet is designed to follow these standards. Here are some of the key ones involved in dApp-wallet interaction:

• ICRC-25: Signer Interaction Standard: Defines the initial handshake protocol. When your dApp wants to connect to a wallet, it uses ICRC-25 to request a session. The wallet then asks the user for permission to interact with the dApp and specifies the scope of permissions (e.g., which methods the dApp can request).

• ICRC-27: Signer Accounts Standard: Once a connection is established via ICRC-25, this standard allows the dApp to request the user's account information from the wallet. This typically includes the user's Principal and associated account identifiers (e.g., for ICRC-1 tokens). OISY uses this to share the user's main ICP account details.

• ICRC-49: Call Canister Standard: This standard defines how a dApp requests the wallet to make an update or query call to a canister on the user's behalf. The dApp specifies the target canister, method name, and arguments. The wallet, after user approval, signs and sends the call.

• ICRC-21: Consent Message Standard: This standard aims to ensure that the wallet displays a human-readable and understandable message to the user before they approve an action requested via ICRC-49. Instead of just showing raw transaction data, the user sees a clear description of what the transaction will do (e.g., "Allow this dApp to send 1.0 ICP to address X?"). This is crucial for security and user trust.

• ICRC-29: Signer Transport Standard: This standard specifies how the dApp (client) and the wallet (signer, potentially in another browser window/tab or extension) communicate with each other. For web-based wallets like OISY, this often involves using browser postMessage APIs for cross-window communication.

• Delegation (ICRC-34 & ICRC-28): These standards (ICRC-34 for Delegation and ICRC-28 for CertifiedQueryResponse) would allow a wallet to grant temporary, limited permissions to a dApp. This could enable the dApp to make certain calls on the user's behalf without requiring approval for every single action, potentially for a specific time or for specific canister methods.

VERY IMPORTANT NOTE Regarding OISY: As of the current understanding and common implementations, OISY Wallet does not broadly support delegation via ICRC-34 / ICRC-28 for dApp interactions. This means that every significant action that modifies state or transfers assets (typically update calls) must be explicitly approved by the user in OISY via a popup confirmation. While this enhances security by ensuring user oversight for each sensitive operation, it can lead to more clicks for the user compared to wallets that might use delegation for session-like behavior. This is a key consideration when designing user flows and choosing integration methods (e.g., why IdentityKit's ACCOUNTS mode is necessary for OISY).

In Simple Words: When your dApp connects to OISY, they start talking using a method defined by ICRC-29. Your dApp asks for permission to interact (ICRC-25). If granted, OISY provides the user's identity details (ICRC-27). When your dApp wants to perform an action like a transfer, it sends a request to OISY (ICRC-49). OISY then shows a clear, human-readable confirmation message to the user (ICRC-21) asking for their approval before proceeding.

How the Process Works: dApp -> OISY -> ICP Ledger

Let's visualize the flow for a common scenario: a user wants to send ICP tokens using your dApp, with OISY as their connected wallet. Both your dApp and OISY are running in the user's web browser. The ICP Ledger (the canister that manages ICP tokens) runs on the Internet Computer blockchain.

Figure: How dApp, OISY, and ICP Ledger talk together.

1. Connect Request (dApp to OISY):

   • The user clicks a "Connect OISY" button in your dApp.

   • Your dApp (using one of the integration libraries) initiates a connection request. This typically opens the OISY website/interface in a new tab or popup.

   • The dApp sends a connection request message using ICRC-29 (transport) and following ICRC-25 rules (signer interaction).

   • OISY receives this request and prompts the user: "dApp X wants to connect. Allow?" The user clicks "Allow" in the OISY interface. The connection is now established.

2. Share Identity (OISY to dApp):

   • OISY sends the user's Principal ID and relevant Account Identifier(s) back to your dApp, using the established ICRC-29 channel and following ICRC-27 rules (accounts).

   • Your dApp now knows the user's ICP identity and address. (If the user wasn't already logged into OISY, OISY would first ask them to log in, typically using their passkey/Internet Identity).

3. Request to Send ICP (dApp to OISY):

   • The user interacts with your dApp (e.g., fills a form and clicks "Send 1 ICP").

   • Your dApp constructs a canister call request message according to ICRC-49 rules. This message essentially says: "Please ask the user to approve a call to the transfer function on the ICP Ledger canister, to send 1 ICP from their account to recipient Y's account, with these parameters."

   • The dApp sends this ICRC-49 request message to OISY via the ICRC-29 transport.

4. User Approval in OISY (OISY internal, then prompts User):

   • OISY receives the ICRC-49 request from your dApp.

   • OISY validates the request and prepares a user-friendly consent message based on ICRC-21 rules. For example: "Confirm Transaction: Send 1.0 ICP to [Recipient Address] from your account?"

   • OISY displays this message prominently in its interface, requiring explicit user action.

   • The user reviews the details and must click "Approve" (or a similar confirmation button). (Remember: OISY requires this approval for every such transaction due to the current lack of delegation support for dApps).

5. Signing and Sending the Transaction (OISY to ICP Ledger):

   • Once the user approves, OISY proceeds to sign the transaction. OISY utilizes ICP's chain-key cryptography (specifically, threshold ECDSA). The user's actual private signing key material is not directly held or exposed in the browser in a traditional sense; it's managed by the IC network itself through canister smart contracts and threshold cryptography. OISY coordinates with its backend canister (which is part of the OISY wallet system on the IC) and the IC's threshold ECDSA signing mechanism to produce a valid signature for the transaction.

   • OISY (or its backend canister infrastructure) then sends the signed transaction to the target canister (in this case, the ICP Ledger canister) on the Internet Computer.

6. Get Result and Inform dApp (ICP Ledger to OISY, then OISY to dApp):

   • The ICP Ledger canister processes the transfer. It then sends back a result (e.g., "Success, transaction included in block number 12345" or an error message).

   • OISY receives this result from the ICP Ledger.

   • OISY relays this result back to your dApp through the established ICRC-29 communication channel.

   • Your dApp can now parse this result and update its UI accordingly (e.g., show "Transfer successful!" or an error message to the user).

Through this entire process, your dApp initiated the request for a transfer, but OISY (with the user's explicit consent) securely handled the signing and submission of the transaction, ensuring the user remained in full control of their funds and actions.

More Tips

• Testing Environments: OISY typically provides a staging or test environment (e.g., staging.oisy.com or similar). Use this for testing your dApp integration before pointing to the production OISY URL (oisy.com). Ensure your dApp's network configuration (local replica, testnet, or mainnet) is compatible with the OISY environment you are targeting.

• User Experience with Approvals: Since OISY requires user approval for every sensitive action (due to no dApp delegation), be mindful of the user experience. If your dApp involves many transactions, this could lead to many popups. Where possible, design user flows that achieve goals with a minimal number of distinct on-chain actions. Future ICRC standards (like batch transaction proposals) might help streamline this.

• Error Handling: Implement robust error handling for all stages of wallet interaction: connection failures, user rejections, transaction failures, network issues, etc. Provide clear feedback to the user.

• Stay Updated with Standards: The ICP wallet ecosystem and ICRC standards are continually evolving. Keep an eye on official DFINITY communications, developer forums, and the GitHub repositories for the standards and libraries you use.

• Learn More from Official Sources:

  • ICP Wallet Standards (ICRCs): The DFINITY WG Identity & Authentication GitHub repository is the primary source for ICRC specifications related to wallets and authentication (ICRC-21, ICRC-25, ICRC-27, ICRC-29, ICRC-49, etc.).

  • IdentityKit Documentation: Visit identitykit.xyz/docs for detailed guides, API references, and examples for integrating IdentityKit.

  • Signer JS (@slide-computer/signer): Check the Slide Computer GitHub repositories for signer, signer-web, and signer-agent documentation.

  • @dfinity/oisy-wallet-signer Repository: The official GitHub repository for this library will have the most current README, API details, and usage examples.

  • DFINITY Developer Forum: The forum.dfinity.org is a valuable resource for discussions, questions, and community support regarding OISY integration, ICRC standards, and general ICP development.

Conclusion

Integrating the OISY wallet into your ICP dApp empowers users with a seamless, secure, and modern way to manage their identity and assets. Users can connect with just a few clicks, leveraging a web-based wallet that is itself a canister system secured by the Internet Computer's advanced chain-key cryptography. They retain full control by approving transactions through clear, human-readable prompts.

By utilizing the ICP signer standards (such as ICRC-21, ICRC-25, ICRC-27, and ICRC-49), your dApp's wallet integration will not only work smoothly with OISY but also maintain interoperability with other wallets in the growing ICP ecosystem that adopt these standards.

Whether you choose the convenience and multi-wallet support of IdentityKit for React, the fine-grained control offered by signer-js, or the OISY-focused simplicity of the @dfinity/oisy-wallet-signer library, the core capability remains the same: your dApp can securely connect to the user's OISY wallet, obtain their principal and account information, and request the signing of transactions or canister calls, all contingent on the user's explicit consent. This unlocks essential Web3 functionality like enabling users to pay with ICP or other tokens, viewing their asset balances within your dApp, or participating in governance by signing messages – all through a standardized and user-friendly wallet interaction flow.

As the Internet Computer platform and its surrounding ecosystem continue to mature, adherence to these open standards will be key to ensuring your dApp remains compatible, secure, and accessible. OISY, in particular, exemplifies the innovative potential of the IC by running entirely on-chain and aiming to bridge multiple blockchain networks within a single, user-friendly wallet interface. By integrating OISY, you offer your users a cutting-edge custody and interaction solution that requires no browser extensions or separately installed applications.

We hope this guide has provided a clear path for integrating OISY Wallet into your dApp. Happy coding, and welcome to building the next generation of decentralized applications on the Internet Computer!

Sources:

(Sources from the original document are generally still relevant but should be cross-checked if specific claims were altered. The new structure emphasizes the ICRC standards more directly, so links to those are very pertinent.)

1. DFINITY Support – "How to set up a web-based crypto wallet (Oisy wallet tutorial)" (How to set up a web-based crypto wallet – DFINITY) – Explains OISY's on-chain nature and use of chain-key cryptography.

2. DFINITY Medium – "The Internet Computer Roadmap" (relevant to Chain Fusion / Toroidal Milestone for OISY's multi-chain aspects) (The Internet Computer Roadmap. Key development areas with pivotal… | by DFINITY | The Internet Computer Review | Medium) – Describes OISY's key properties (passkey auth, no seed phrase, ICP dApp support).

3. NFID IdentityKit Documentation (NFID IdentityKit | Docs) – Details on IdentityKit usage and supported ICRC standards.

4. DFINITY Forum – "ICRC-21 Consent Messages" (ICRC-21+ (or 22) - Tokenization - Internet Computer Developer Forum) – Context on the importance of human-readable consent messages.

5. OISY Wallet Signer README – OISY Wallet Signer Introduction (GitHub - dfinity/oisy-wallet-signer) – Official source for the OISY-specific library.

6. Internet Computer Agent Library (agent-js) Documentation (Internet Computer Developer Docs - Agents) - For understanding HttpAgent.

7. ICRC Standards Repository (WG Identity & Authentication) (GitHub - dfinity/wg-identity-authentication) - For specifications of ICRC-21, 25, 27, 29, 49 etc.