Merge pull request #1448 from Concordium/Add-wallet-integration-doc-to-Dev-Doc-site

Add wallet integration doc to dev doc site

Author: TinaKT

source/mainnet/docs/index.rst

@@ -123,6 +123,12 @@ Explore our developer resources, including detailed documentation, tutorials, an
    Run a local chain <network/guides/run-local-chain.rst>
    Indexers <network/indexers/intro.rst>
 
+.. toctree::
+   :caption: Integration
+   :hidden:
+
+   Wallet integration <integration/wallet integration/wallet-integration>
+
 .. toctree::
    :caption: Help & FAQ
    :hidden:

source/mainnet/docs/integration/wallet integration/connecting-wallet-to-network.rst

@@ -0,0 +1,42 @@
+.. include:: ../../../variables.rst
+.. _connecting-wallet-to-network:
+
+=====================================
+Connecting your wallet to the network
+=====================================
+
+A :term:`Concordium node<Node>` is the gateway to the blockchain. For your wallet to perform any :term:`on-chain action<On-chain>`, it must communicate with a node.
+
+Concordium nodes communicate exclusively via gRPC (gRPC Remote Procedure Calls). This framework exposes the blockchain's unique features, including its built-in identity layer and specific data structures for :term:`accounts<Account>` and :term:`smart contracts<Smart contract>`.
+
+This section outlines the recommended architecture for establishing a robust and scalable gRPC connection to your node.
+
+Running a Concordium node
+=========================
+
+The foundation of any reliable wallet service is running your own Concordium node. This is the most direct and secure way to interact with the blockchain, giving you full control over the availability and integrity of your connection.
+
+A self-hosted node provides direct access to the blockchain's raw data and serves as the endpoint for sending transactions. It is the authoritative source of truth for your application.
+
+**Advantages:** You maintain complete control over service uptime and performance, removing any dependency on third-party infrastructure.
+
+**Developer tools:** The primary resource for this step is the official guide on :ref:`running a Concordium node<node-requirements>`, which details all hardware and software requirements, and provides installation and configuration instructions for all supported platforms.
+
+Building a wallet proxy
+=======================
+
+While a direct node connection is essential, the raw data it provides can be complex to work with. To solve this, the recommended best practice is to build an intermediary **wallet proxy**. This is a service that you create and run which sits between your own Concordium node and your wallet application.
+
+The proxy's job is to query your node for raw data, then process, enrich, and index it into a user-friendly format. It then serves this clean data to your wallet through a simple API (e.g., REST).
+
+**Advantages:**
+
+* Simplifies development by handling complex backend tasks like transaction indexing, making it much easier to display user transaction histories.
+
+* Enriches data by adding useful metadata to on-chain information, such as adding logos and display names to the list of validators.
+
+* Provides a clean API that presents a simple, custom-built interface to your wallet, abstracting away the complexities of raw gRPC calls.
+
+**Developer tools:** The `Concordium Wallet Proxy <https://github.com/Concordium/concordium-wallet-proxy>`_ on GitHub serves as a valuable open-source reference implementation to guide you in building your own proxy service. Note that this example is not intended for production use.
+
+

source/mainnet/docs/integration/wallet integration/integrating-identity-layer.rst

@@ -0,0 +1,48 @@
+.. include:: ../../../variables.rst
+.. _integrating-identity-layer:
+
+=================================
+Integrating Concordium's ID layer
+=================================
+
+Every account on Concordium is backed by a verified identity, requiring a balance between compliance and on-chain privacy. The process begins with an off-chain :term:`Identity Provider (IDP)<Identity Provider>` who issues a sensitive :term:`identity object` to the user. This object is the cryptographic root of the user's on-chain presence.
+
+Your wallet's role is to facilitate the use of this identity object to create public on-chain accounts, ensuring privacy by anchoring the user's identity without exposing personal data. This guide outlines the two primary integration paths for managing the identity creation process and its associated data.
+
+
+.. _option-1-direct-idp:
+
+Option 1: direct ID provider integration
+========================================
+
+In this model, your wallet integrates directly with an IDP's API. You can select from a list of :ref:`pre-approved IDPs<key-participants>` already integrated with the network, or you can bring your own preferred provider. If you bring your own, the IDP must work with the Concordium team to complete an onboarding process and become a recognized issuer on the network. Once an IDP is chosen, your application manages the entire verification flow, from generating cryptographic requests to receiving the final identity object.
+
+**Advantage:** You maintain complete control over the entire user journey, allowing for a seamless and fully branded in-app experience.
+
+**Consideration:** This approach requires more development overhead and means your wallet assumes full responsibility for the secure storage and lifecycle management of the user's sensitive identity object.
+
+**Developer Tools:** The :ref:`Concordium SDK<wallet-sdk>` is designed for this path. It provides all the necessary functions to generate keys, create identity requests, and construct on-chain transactions. Alternatively, you can use the the :ref:`Concordium Client CLI<concordium-client>` or interact with the node directly.
+
+
+.. _option-2-id-app:
+
+Option 2: integration via the Concordium ID App
+===============================================
+
+This approach offloads the entire identity lifecycle to the dedicated Concordium ID App. Your wallet uses the WalletConnect protocol to securely connect with the ID App, which manages and stores the identity object. Your wallet simply requests the necessary commitments for account creation, without ever taking custody of the private credential itself.
+
+**Advantage:** This method simplifies integration and removes the significant security burden of storing and managing the user's private identity object.
+
+**Consideration:** The user is temporarily directed outside of your wallet's UI to the Concordium ID App to complete the process.
+
+**Developer Tools:** A dedicated, TypeScript-based SDK is available to easily manage the communication and secure data transfer between your wallet and the Concordium ID App.
+
+Making your decision
+====================
+
+Choosing between these two options is a key architectural decision. The choice involves balancing the level of control you want over the user experience against the development and maintenance resources required.
+
+To help you make an informed choice, we recommend reviewing our :ref:`detailed guide on Concordium's identity layer<reference-identity>`. For a practical example, you can explore the source code of `Concordium Wallet <https://github.com/Concordium/cryptox-android>`_, an open-source reference wallet, which provides a complete implementation of :ref:`option 1<option-1-direct-idp>`.
+
+
+

source/mainnet/docs/integration/wallet integration/supporting-staking.rst

@@ -0,0 +1,24 @@
+.. include:: ../../../variables.rst
+.. _supporting-staking:
+
+==================
+Supporting staking
+==================
+
+Concordium secures its network using a :term:`proof-of-stake` model enabling your users to earn rewards on their CCD holdings. This ecosystem is built on two key roles: :term:`validators<validator>`, who operate the nodes that run the network, and :term:`delegators<delegator>`, who are users that stake their CCD to support these validators.
+
+For the majority of users, the primary way to participate is through :term:`delegation`. This allows them to assign the weight of their CCD to a validator of their choice, earning a share of the rewards without the technical overhead of running their own node.
+
+Your wallet's role is to provide the essential interface for this process, enabling users to discover validators, delegate their funds securely, and manage their staking rewards. This includes handling timing factors such as :term:`pay day` cycles and :term:`cool-down periods<Cool-down period>`, as well as supporting delegation to specific validator pools as well as :term:`passive delegation`.
+
+Integrating these features provides a significant incentive for users to hold and interact with CCD within your application.
+
+Learn more
+==========
+
+For more information about how staking and delegation work on Concordium, see :ref:`Staking<staking>`.
+
+For detailed information on delegation and reward types, see :ref:`Concordium tokenomics system<tokenomics>`.
+
+For a more in-depth explanation of how validation works, see :ref:`Block production and validation<baker-concept>`.
+

source/mainnet/docs/integration/wallet integration/supporting-transactions.rst

@@ -0,0 +1,55 @@
+.. include:: ../../../variables.rst
+.. _supporting-transactions:
+
+=======================
+Supporting transactions
+=======================
+
+A wallet's fundamental purpose is to construct, sign, and broadcast :term:`transactions<transaction>`. Each user-facing feature you implement will require your wallet to generate a specific type of transaction payload.
+
+The following section lists the core transaction types you can support.
+
+Transaction types
+=================
+
+**1. Simple transfer**
+
+This is the most fundamental transaction type, used for sending the native CCD token from one account to another. It is a straightforward value transfer, equivalent to a standard payment on other blockchains.
+
+**2. Smart contract transactions**
+
+This category covers all interactions with :term:`smart contracts<smart contract>`. It enables users to interact with dApps and manage tokens built on the CIS-2 standard (Concordium's universal token standard for Fungible, Non-Fungible, and Semi-Fungible tokens). Common actions include:
+
+* Deploying and initializing contracts
+* Updating contracts (e.g., calling a transfer function on a CIS-2 token)
+
+**3. Staking and delegation transactions**
+
+These transactions are essential for participating in Concordium's :term:`proof-of-stake` network. Key transactions for delegators include:
+
+* Add delegation: Staking CCD with a validator pool
+* Update delegation: Changing the staked amount
+* Remove delegation: Unstaking CCD
+
+**4. Account and identity transactions**
+
+Unique to Concordium's architecture, this category includes the crucial create account transaction. This must be submitted with the cryptographic credential from a user's verified :term:`identity object`, linking the new account to that identity.
+
+Protocol-level tokens
+=====================
+
+Beyond the standard transaction types, Concordium features :term:`protocol-level tokens (PLTs)<protocol-level token (PLT)>`, a unique class of tokens created directly at protocol level.
+
+These tokens are distinct from user-created CIS-2 smart contract tokens. They are typically reserved for foundational assets, such as bridged tokens (e.g., wETH), that require native protocol integration.
+
+Key advantages of PLTs
+----------------------
+
+* **Higher Efficiency** - Because they are native to the protocol, PLT transactions consume significantly less energy, making them cheaper and faster to transfer.
+* **Enhanced Security** - PLT logic is part of the blockchain's core code, subject to the highest levels of scrutiny, which reduces smart contract risks.
+* **Standardized Governance** - Upgrades are managed through Concordium's established on-chain governance process, ensuring stability.
+
+For a wallet, supporting a PLT transfer means constructing a dedicated, protocol-level transaction, which is different from the general-purpose update function used for smart contracts.
+
+For further details on PLTs, refer to our :ref:`PLT<plts>` documentation.
+

source/mainnet/docs/integration/wallet integration/supporting-zero-knowledge-proofs.rst

@@ -0,0 +1,28 @@
+.. include:: ../../../variables.rst
+.. _supporting-zero-knowledge-proofs:
+
+================================
+Supporting zero-knowledge proofs
+================================
+
+Concordium's identity layer uses :term:`zero-knowledge proofs (ZKPs)<zero-knowledge proof>` to ensure user privacy. These cryptographic proofs are a core component of the :term:`identity object`. They enable a user to confirm their verified status on-chain without disclosing personal data. This system also allows for selective disclosure; for instance, a user could generate a proof to confirm a specific attribute (e.g., "is over 18"). A third party can then verify the proof against the user's public commitment on the blockchain, confirming the attribute without revealing other personal data.
+
+Your wallet's responsibility for handling these proofs depends on your chosen integration path:
+
+If you selected :ref:`option 1 (direct IDP integration) <option-1-direct-idp>`, your wallet is responsible for generating the cryptographic requests that produce the final ZKP within the identity object. The Concordium SDK is designed to handle this complex process.
+
+If you selected :ref:`option 2 (ID App integration) <option-2-id-app>`, this responsibility is offloaded entirely to the Concordium ID App.
+
+
+**Advantages:**
+
+* **User privacy** - Users' identity is verified on-chain without exposing personal data.
+* **Regulatory compliance** - Enables access to regulated digital assets and enterprise dApps that require verified identity.
+* **Reduced security liability** - The protocol handles identity proofs, eliminating the need to store sensitive user PII.
+
+**Developer tools:**
+
+* The `Concordium Proof Explorer <https://web3id-proof-explorer.testnet.concordium.com/>`_ is an interactive tool for creating and testing proofs with account credentials and verifiable credentials
+* View the `source code on GitHub <https://github.com/Concordium/concordium-web3id/tree/main/test-tools/proof-explorer>`_
+* For detailed guidance on writing statements that interact with Concordium wallets and creating proofs for dApps and services, refer to :ref:`the Create proofs documentation<create-proofs>`
+

source/mainnet/docs/integration/wallet integration/wallet-integration.rst

@@ -0,0 +1,46 @@
+.. include:: ../../../variables.rst
+.. _wallet-integration:
+
+==================
+Wallet integration
+==================
+
+This guide covers the technical requirements for integrating Concordium blockchain support into a crypto wallet. It walks you through core protocol features and key architectural decisions. Whether you're evaluating Concordium for integration or ready to begin implementation, this guide provides the foundation for making informed decisions.
+
+Integration overview
+====================
+
+Concordium is a Layer-1 :term:`proof-of-stake` blockchain with a built-in :ref:`identity layer<reference-identity>` at protocol level balancing user privacy with regulatory compliance. The platform supports multiple transaction types, offers native staking and :term:`delegation` functionality, and uses an efficient gRPC-based node communication protocol.
+
+Integrating Concordium involves implementing support for several protocol-specific features:
+
+* **Identity layer management:** handling verified on-chain identities
+* **Zero-knowledge proofs (ZKPs):** managing cryptographic proofs for privacy-preserving identity verification
+* **Transaction types:** supporting CCD transfers, smart contracts, staking, and protocol-level tokens
+* **Staking functionality:** enabling users to delegate CCD and earn rewards
+
+In addition to implementing these features, you'll need to establish network connectivity through Concordium's gRPC-based communication protocol. You may consider using a wallet proxy for simplified data handling.
+
+Guide structure
+===============
+
+The following pages provide detailed guidance for each integration area, including technical specifications and links to relevant SDKs and APIs.
+
+* :ref:`Integrating Concordium's ID layer<integrating-identity-layer>`
+* :ref:`Supporting zero-knowledge proofs (ZKPs)<supporting-zero-knowledge-proofs>`
+* :ref:`Supporting transactions<supporting-transactions>`
+* :ref:`Supporting staking<supporting-staking>`
+* :ref:`Connecting your wallet to the network<connecting-wallet-to-network>`
+
+
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+
+   integrating-identity-layer
+   supporting-zero-knowledge-proofs
+   supporting-transactions
+   supporting-staking
+   connecting-wallet-to-network
+
+

source/mainnet/docs/protocol/identity.rst

@@ -51,6 +51,9 @@ While interaction with the Concordium blockchain always requires a Concordium ID
 
 :doc:`Learn more about using Concordium's ID layer <../network/web3-id/index>`.
 
+
+.. _key-participants:
+
 Key participants
 ================
 The identity solution on Concordium involves several key participants, each with specific roles and responsibilities in the process.