diff --git a/source/mainnet/docs/index.rst b/source/mainnet/docs/index.rst index f7814056de..2d46b2e4c9 100644 --- a/source/mainnet/docs/index.rst +++ b/source/mainnet/docs/index.rst @@ -116,6 +116,7 @@ Explore our developer resources, including detailed documentation, tutorials, an FAQs Concordium Standards Glossary of Concordium terms + Exchange Onboarding Guide .. toctree:: diff --git a/source/mainnet/docs/protocol/manage-accounts.rst b/source/mainnet/docs/protocol/manage-accounts.rst index 317f9b074d..d0c8a26bc3 100644 --- a/source/mainnet/docs/protocol/manage-accounts.rst +++ b/source/mainnet/docs/protocol/manage-accounts.rst @@ -141,6 +141,8 @@ The |cryptox| keeps track of the sequence number and assigns the correct one whe ``concordium-client`` tracks the sequence number automatically, but it can also be set manually. +.. _account-aliasses: + Account aliases --------------- diff --git a/source/mainnet/docs/resources/exchangeOnBoarding.rst b/source/mainnet/docs/resources/exchangeOnBoarding.rst new file mode 100644 index 0000000000..d50a4d1c1c --- /dev/null +++ b/source/mainnet/docs/resources/exchangeOnBoarding.rst @@ -0,0 +1,177 @@ +.. _exchangeOnBoarding: + +========================= +Exchange Onboarding Guide +========================= + +This guide will help you add Concordium's native token (CCD) to your cryptocurrency exchange. + +Before you start, it is a good idea to read about the core concepts of the Concordium blockchain, +particularly :ref:`identities ` and :ref:`accounts `. The `Concordium Whitepaper `_ provides a comprehensive overview of these concepts. + +Identity creation +================= + +Concordium requires identity verification before account creation, which is a fundamental part of its regulatory compliance framework. + +Mainnet identity creation +------------------------- + +**For Individual Identities:** + +* You can use any of the Concordium wallets by following the documentation at :ref:`Create an identity ` + +**For Company Identities:** + +- Follow the documentation at :ref:`Company Identity Creation ` +- This process involves identity verification through Concordium's approved identity providers + +Testnet identity creation +------------------------- + +**For Both Individual and Company Identities:** + +* No formal verification is required +* For individual identities, use :ref:`any of the Concordium wallets ` +* For company identities, follow the documentation at :ref:`Company Identity Creation ` + +Account creation +================ + +Once you have a verified identity, you can create multiple accounts from it. + +* Up to 25 initial accounts can be created from a single identity +* Accounts can be created using any Concordium wallet, follow the documentation at :ref:`create an account ` for more information + +Node setup +========== + +Running your own node is essential for exchange integration. + +Hardware requirements +--------------------- + +Before setting up a node, ensure your hardware meets the :ref:`requirements for running a node `. + +Node distributions +------------------ + +Node distributions for different platforms are available at the :ref:`Downloads page `. + +Platform-specific setup instructions +------------------------------------ + +* :ref:`Ubuntu Node ` +* :ref:`Docker Node ` +* :ref:`Windows Node ` +* :ref:`MacOS Node ` +* :ref:`AWS Node ` + +For custom node setups, contact `Concordium Support `_. + +Integration methods +=================== + +Concordium offers several methods for integrating with the blockchain: + +SDKs +---- + +You can use one of the official Concordium :ref:`SDKs `: + +* `Node.js SDK `_ +* `Rust SDK `_ +* `.NET (C#) SDK `_ +* `Java SDK `_ +* `Go SDK `_ + +Rosetta API +----------- + +Concordium provides an adapter to expose the `Rosetta API `_, which is useful for exchanges already supporting this standard. + +gRPC V2 interface +----------------- + +Concordium provides a gRPC V2 interface as well, details can be found in this :ref:`documentation article `. + +Transactions +============ + +Checking for incoming transactions +---------------------------------- + +**Node Query Method** + +* The most reliable method is to :ref:`query your node ` directly + +**Transaction Logger** + +- Alternatively, you can run a `transaction logging service `_ +- This service logs transactions to a database where you can efficiently lookup the transaction for a specific account + +Transfer CCD on withdrawal request +---------------------------------- + +- Use the :ref:`SDK ` of your choice to implement CCD transfers. +- Transfer of CCD is also possible with :ref:`gRPC `. + +FAQ +=== + +Account aliases +--------------- + +**Q: Do we have to create a company identity for each account?** + + * No, one identity can have multiple accounts. Once you have a verified identity object, you can generate as many accounts as you need from it. It should not be necessary for you to have several identities, one will suffice. + For your users, the recommended setup is to use :ref:`account aliases `: + + * This means that you create one or more omnibus accounts and generate aliases/subaccounts for individual user transfers + * Subaccounts share the same private key but have different addresses, making it easy to organize user deposits and withdrawals + * Each account can have up to 2^24 aliases (approximately 16 million) + +Transfer with MEMO +------------------ + +**Q: How can we include additional data with transactions?** + + * Concordium supports memo transfers, which allow you to attach additional data to a transaction. This is useful for exchange integrations to track user deposits: + + * Memo transfers can be implemented through any of the Concordium :ref:`SDKs ` or through :ref:`gRPC ` + +Transaction confirmation +------------------------ + +**Q: When is a transaction considered confirmed?** + + * Concordium has explicit finalization: + + * Once a block is created, it usually takes 1-2 seconds to be finalized + * Average block time is about 2 seconds + * The node will report a transaction as finalized once it's in a finalized block + * Finalization is not based on the number of successor blocks + +Getting testnet CCDs +-------------------- + +**Q: How do I get CCDs for testing on testnet?** + + * For individual accounts: + + * Request a CCD drop directly through the :ref:`Concordium wallets ` + + * For company accounts: + + .. code-block:: console + + $ curl -X PUT https://wallet-proxy.testnet.concordium.com/v0/testnetGTUDrop/YOUR_ACCOUNT_ADDRESS + + * Replace ``YOUR_ACCOUNT_ADDRESS`` with your account address. You can only request one CCD drop per account. + +Additional support +================== + +For specific help to integrate your exchange with the Concordium blockchain, contact support@concordium.software. + +Please start your subject line with "Approved Exchange" to prioritize your support request. diff --git a/source/mainnet/tutorials/company-identity/company-identities.rst b/source/mainnet/tutorials/company-identity/company-identities.rst index bcf4edcb97..a6175f7ee8 100644 --- a/source/mainnet/tutorials/company-identity/company-identities.rst +++ b/source/mainnet/tutorials/company-identity/company-identities.rst @@ -3,147 +3,80 @@ .. _port number: https://en.wikipedia.org/wiki/Port_(computer_networking) .. _company-identities: -============================ +========================= Company identity creation -============================ +========================= A company identity is for companies that need an identity and accounts on the Concordium blockchain, but don't want that identity to belong to a specific person. Company identities are therefore issued with documents that identify the company and not an individual. Company identities are only relevant for a few companies, such as crypto exchanges. -You can't use the Desktop Wallet, |bw|, |mw-gen2|, or |mw-gen1| to create a company identity. You need to use the Concordium Company ID tool, and you need to communicate directly with the identity provider (currently Notabene). `This page `_ describes Notabene's process, including recovery of company identities. +Company identities can only be created through the |bw| or |cryptox| using Global FinReg as the identity provider. You cannot use the Desktop Wallet for this purpose. -The information below describes how to create a company identity, how to create accounts with a company identity, and how to recover a company identity. If you experience issues with the Concordium Company ID tool, please contact Concordium’s technical support via support@concordium.software. - -Using the Concordium Company ID tool -==================================== +.. note:: + Please be advised that Global FinReg identity verification is currently only supported on |cryptox| for Android devices. This service is not yet available for iOS users. -Once you have dowloaded the Concordium Company ID tool for your platform and installed it, you should choose your network, either Mainnet or Testnet. A default Concordium node URL is used, but you can enter your node URL, if desired. +The information below describes how to create a company identity, how to create accounts with a company identity, and how to recover a company identity. If you experience issues, please contact Concordium’s technical support via support@concordium.software. Request identity ----------------- - -#. Click **Request identity**. +================ -#. Read the information and click **Proceed**. +To create a company identity using Global FinReg, first :ref:`download ` the |bw| or the |cryptox|, then follow the steps outlined below. -#. Write down or save your seedphrase by clicking the copy button to copy your seedphrase to the clipboard and remember to go to the clipboard and save the file. Keep your seedphrase secure as you will need it to create accounts or recover the identity. Click **Proceed**. +Initiate the request from a Concordium wallet +--------------------------------------------- - .. image:: images/company-id-request.png - :alt: company id tool screen showing identities related to seedphrase and option to select +* Open the |bw| or |cryptox| -#. Enter your seedphrase to verify that you have recorded it correctly. Click **Proceed**. +* In the main menu, click on **Identities**. -#. Click **Generate request.json**. The command outputs the ``request.json`` file. The request should be sent to the identity provider through a trusted channel. Store the auxiliary output securely. + .. image:: images/wallet-globalfinreg-identities-menu.png + :alt: Concordium wallet screen showing the Identities option in the main menu - - For **Mainnet** requests: Send the file to ania@notabene.id together with any other required identity data as described in the `entity verification instructions `_. +* Click on the plus sign (+) to request a new identity. - - For **Testnet** requests: Send the file to support@concordium.software with the subject line "Test company identity". + .. image:: images/wallet-globalfinreg-add-identity.png + :alt: Concordium wallet screen showing the plus sign to add a new identity -When the identity has been verified successfully, you will receive an email with an identity object file named ``id-object.json``. Store this file securely as you need it to create accounts and regenerate account keys. +* Select **Global FinReg** from the identity provider options. This initiates a request and opens a new webpage on the Global FinReg platform. -Create account --------------- + .. image:: images/walllet-globalfinreg-provider-selection.png + :alt: Concordium wallet screen showing the Global FinReg option selection -After obtaining the ``id-object.json`` identity object from the identity provider you can create accounts on the chain. The Concordium Company ID tool requires the identity object returned by the identity provider to create accounts on chain. +Complete verification +--------------------- -**Create account** can also be used to regenerate the keys for an old account. In this case, you would need ``id-object.json`` file again. If you have lost that file, use :ref:`Identity Recovery` to retrieve it so you can recover your accounts and save the account keys. After selecting Identity Recovery, enter your seed phrase. If there are accounts on chain related to the seed phrase, you will be able to store the keys of those accounts. +* Log in to your existing Global FinReg account or sign up for a new account. -#. Click **Create Account**. +* Enter your company's `Legal Entity Identifier (LEI code) `_. Alternatively, you can enter the entity details of the company. -#. Enter your seedphrase in the Enter seedphrase field. In the Identity object file field click to navigate to the location of the stored ``id-object.json`` file. Click **Get Accounts**. +* Upload entity documents from a primary source that are no older than three months. Acceptable documents include: - .. image:: images/company-id-create-acct.png - :alt: company id tool screen showing seedphrase field and file selection box + * Business registry documents + * Documents from a financial supervisory authority (FSA) -#. On the next screen, click **Create Account** to create an account with this company identity. When prompted, save the ``account-keys.json`` in a secure location as you will need them to interact with the account on-chain. You can click **Create account** again to create another account. +* Provide information about the company's Ultimate Beneficial Owner (UBO) or Authorized Signatory. .. note:: - If you are trying to recover the ``account-keys.json`` file(s), you can also use **Create Account**. After entering your seedphrase and selecting your ``id-object.json`` file you will see a list of account associated with this seedphrase and ID object. Click **Save** to save the ``account-keys.json`` for that account. - - .. image:: images/company-id-acct-keys.png - :alt: company id tool screen showing seedphrase field and file selection box - -.. dropdown:: Format of the key files - - Both initial account keys and subsequent account keys are stored in JSON files. The unencrypted data is a JSON record with a number of fields. This is the same format as exported by the other Concordium wallets (except Desktop Wallet). For sending transactions the fields that are relevant are: - - - ``accountKeys`` contains the account keys. It has the following format: - - .. code-block:: json - - { - "environment": "testnet", - "type": "concordium-browser-wallet-account", - "v": 0, - "value": { - "accountKeys": { - "keys": { - "0": { - "keys": { - "0": { - "signKey": "81e7d8e625a00b6f5b97dd8b0a97807212e6b0ceb4fd206e715b97536c83caea", - "verifyKey": "03164c9e6654c1544a0e7d33780df425c695f6222fda75c047aea5186680e491" - } - }, - "threshold": 1 - } - }, - "threshold": 1 - }, - "address": "3LfTBXYtc6TEjuJiKgLpFGEtGRMPhBsKRB76Q4x91LZPWSmQ9Z", - "credentials": { - "0": "843785aef9446c8e5b2c6922863e49231b93fb9950909c3166e7c287357a1a495ecfbdcb6ca36ea5998fef2c9dee91f8" - } - } - } - - In this example the account has a single credential with index 0, and that credential has a single key with index 0. The private key is 03164c9e6654c1544a0e7d33780df425c695f6222fda75c047aea5186680e491 and its public key is 81e7d8e625a00b6f5b97dd8b0a97807212e6b0ceb4fd206e715b97536c83caea. - - - ``address`` is the address of the account, e.g., - - .. code-block:: json + A UBO is generally defined as an individual who holds a minimum of 10-25% (depending on jurisdiction) of capital or voting rights in the underlying entity. - "address": "3LfTBXYtc6TEjuJiKgLpFGEtGRMPhBsKRB76Q4x91LZPWSmQ9Z" +* Verify the UBO or Authorized Signatory through the online verification tool using a passport or driver's license. -Import created accounts into ``concordium-client`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Finalize validation and create accounts +--------------------------------------- -To use the accounts created in the Concordium Company ID tool, you must use Concordium Client. You can download it :ref:`here`. For information about how to use it, see :ref:`concordium-client`. +* Navigate to the account management tab in Global FinReg. -The account keys are primarily meant for clients to integrate into their key management solution and their software, e.g., an exchange integrating their trading platform with the Concordium chain. +* Review all submitted documents and information for accuracy. -However, if the ``account-keys.json`` file is not encrypted it can be imported into ``concordium-client`` with the command: +* If all information is correct, click **Approve** to finalize the verification process. -.. code-block:: console +* Upon approval, your wallet ID will be validated and ready for use on the Concordium blockchain. - concordium-client config account import account-keys.json --name my-account - -``--name`` is mandatory and will name the account according to the given value ("my-account" in the example above). - -The initial account keys cannot be directly imported into ``concordium-client``. - -Once you have created accounts, you can request CCDs for testing. To request CCDs for testing, run the following command: - -``curl -X PUT https://wallet-proxy.testnet.concordium.com/v0/testnetGTUDrop/3GXM6cEuAwEA47EEtFpax9PLhMWchWmkaPmNZmW1kbDaWaKBxV`` where you replace 3GXM6cEuAwEA47EEtFpax9PLhMWchWmkaPmNZmW1kbDaWaKBxV with the account address that should receive the CCDs. - -.. _id-recovery: +After completing these steps, you can use your company identity to create accounts on the Concordium blockchain as described in the :ref:`Create account` guide. Identity recovery ------------------ - -If the identity object used to create credentials is lost, it can be recovered from the identity provider by generating a recovery request using the 24 words used when the identity was originally created. Recover identity generates an identity recovery request to be sent to the identity provider. - -#. Click **Identity Recovery**. - -#. Enter your seedphrase in the Enter seedphrase field. And click **Find identities**. - -#. You see a list of accounts associated with the seedphrase. It is possible to save the account keys that can be ussed to interact with the account on the chain. Indices that are to the left of the account address are pointing to the identity index, being the first value and the account index being the second value (0,0). In the Identities to recover drop-down, select the identity you want to recover. There will always be one additional index on the list for selection to be sure that request can be generated for more than one identity. This is mainly useful in cases where first identity object was lost or unused to create accounts. Click **Generate recovery request**. The command outputs the ``recovery-request.json`` file. The request should be sent to the identity provider through a trusted channel. When the request has been verified successfully, you will receive an email with an identity object. Store this file securely as you need it to create accounts on the chain. - - .. image:: images/account-creation.png - :alt: company id tool screen showing identities related to seedphrase and option to select - -- For Mainnet requests: Send the file to ania@notabene.id together with any other required identity data as described in the `entity verification instructions `_. +================= -- For Testnet requests: Send the file to support@concordium.software with the subject line "Recover company identity". +Since identities are created directly through the |bw| or |cryptox|, identity recovery is performed through the wallet recovery process. -When the recovery request has been verified successfully, you will receive an email with the identity object file named ``id-object.json`` that you lost. Store this file securely as you need it to create accounts. +For detailed instructions on wallet recovery, please refer to the :ref:`recover your wallet ` guide. diff --git a/source/mainnet/tutorials/company-identity/images/wallet-globalfinreg-add-identity.png b/source/mainnet/tutorials/company-identity/images/wallet-globalfinreg-add-identity.png new file mode 100644 index 0000000000..17fd8aa696 Binary files /dev/null and b/source/mainnet/tutorials/company-identity/images/wallet-globalfinreg-add-identity.png differ diff --git a/source/mainnet/tutorials/company-identity/images/wallet-globalfinreg-identities-menu.png b/source/mainnet/tutorials/company-identity/images/wallet-globalfinreg-identities-menu.png new file mode 100644 index 0000000000..859541524e Binary files /dev/null and b/source/mainnet/tutorials/company-identity/images/wallet-globalfinreg-identities-menu.png differ diff --git a/source/mainnet/tutorials/company-identity/images/walllet-globalfinreg-provider-selection.png b/source/mainnet/tutorials/company-identity/images/walllet-globalfinreg-provider-selection.png new file mode 100644 index 0000000000..a4bcf0e497 Binary files /dev/null and b/source/mainnet/tutorials/company-identity/images/walllet-globalfinreg-provider-selection.png differ