Issuer

Learn how to perform the tasks of an Issuer.

Integrate with the DRM platform

Overview

This playbook outlines the process of creating a service to integrate a banking system with the DRM ledger system. The service receives messages or webhooks from the internal banking system, then creates and/or updates DRM resources. The service also has an interface for client applications such as a mobile app or web portal. This interface is used to request user onboarding, deposits and withdrawals, and other resource handling.

Integration tools

The DRM Client SDK is the main integration tool used to connect internal banking systems with the DRM ledger system. The SDKs currently supported are:

[DRM Rust SDK](https://crates.io/crates/DRM-sdk) [DRM Dart SDK](https://pub.dev/packages/DRM_sdk) [DRM Node.js SDK](https://www.npmjs.com/package/DRM-sdk)

Code examples

Examples throughout this document will use the DRM Dart SDK. The same methods are implemented in the Node.js SDK.

Understanding the account structure

Understanding the account structure of the DRM ledger is important. If you've read the Overview, here follows another level of detail:

The hierarchical DRM ledger has two types of accounts:

Type	Description
issuance accounts	An issuance account can not have a balance higher than zero (0). When an issuance account transfers funds ("issues" funds) to a holding account, the issuance account balance goes negative and the holding account balance increases.
holding accounts	Holding accounts are children of issuance accounts.

An entity (such as a bank) on the DRM ledger can have both a holding account and an issuance account.

Transfers between two accounts traverse the account hierarchy to find the path between two accounts. For more details, see Transfers.

An issuance account with child accounts (holding accounts) can obtain a recursive sum of all the child accounts balances in the issuance.issued_balance field. This is useful for a bank or central bank to query all the money issued to its child accounts.

note

There is a system limit of 256 root accounts. Plan your issuance hierarchy accordingly.

The diagram below outlines the basic account structure of the hierarchical DRM ledger. The USD root account, which is provided by the currency sponsor (central bank, or one or more appointed commercial banks), has no balance because it's at the root of the hierarchy but is negative 200 in issuance, meaning it has issued a total of 200 to child accounts:

• Tungsten Bank has a balance of 90.
• Iron Bank has balances of 110
• The sum of 90 + 110 being 200, which matches the negative issuing balance of the root account.

Tungsten Bank has issued 500 to its child accounts, which include its own holding account and the holding accounts of Alice and Bob. Likewise, Iron Bank issued 100 to Chris (30) and Diego (70).

For Iron Bank to create a new ledger account for one of its customers, it would create it under its issuance account. To fund the new account, Iron Bank would create a transfer from its issuance account to the user's holding account (from parent account to child account).

In this example, the hierarchical ledger has three levels. However, the number of levels is technically unlimited.

Main Issuer activities

As an Issuer, you typically perform the following activities:

1. Onboard customer
2. Offboard customer
3. Issue digital money to a customer
4. Redeem digital money for a customer
5. Freeze a customer account
6. Facilitate an account recovery request by a customer

Below we'll explain each activity and provide data flows and example code.

Onboard customers

Onboarding data flow

In this example we assume that the user's Issuer, or PSP requests KYC of the user. However, other scenarios are also possible.

Onboarding a customer to the DRM Platform means creating an account for the customer on the ledger and assign the apropriate permissions (which may be changed later). Optionally, a directory alias can be added to make it easier to address the user when transfering digital money. The party onboarding the user (e.g. PSP) is responsible for complying with local KYC/KYB regulations.

The steps to onboard a user include:

• Have the user generate a cryptographic key pair
• Create a ledger account
• Create a role binding (optional)
• Create alias (optional) (see section Managing user aliases).

Each user with their own ledger account, should have a cryptographic key pair that is generated by the account holder. The resulting private key must be stored securely with the account holder and the public key is used during the account creation process.

warning

Why Users Should Generate Their Own Cryptographic Keys

To ensure the highest level of security and control over API interactions, it is strongly recommend that users generate their own cryptographic key pairs. This key pair consists of a public key and a private key.

Why Self-Generated Keys Matter:

• Reduced Risk of Compromise: By generating their own keys, users minimize the risk of the keys falling into the wrong hands.
• Stronger Authentication: Using a self-generated private key for digital signatures strengthens the authentication process.
• Full Ownership: Complete ownership and control over keys, ensuring data remains secure.
• Flexibility: Manage and rotate keys as needed, adapting to evolving security best practices.

How to Generate Keys

The DRM SDKs and CLI provide functions for key generation. The DRM mobile SDK stores the private key in the mobile device's secure element, or trusted execution environment (TEE).

The key pair should be in the PKCS8 format. If Alice were to generate a key pair, she would enter the following command:

• CLI
• TypeScript
• Rust

M10 REPLFOO

Output

The output would be something like:

created key pair file: "alice.pkcs8"
public key is:
"hOJIkyqJ7/dUStWzcgj+afT1dBvJKczPvl5q70MpMaY="

Create ledger account

Now that the user who should get a ledger account has a key pair, the bank can create the account.

To create an account on the ledger:

• Rust
• TypeScript
• Dart
• CLI

M10 REPLFOO

Create AccountSet

Optionally...

"[insert code sample]"

Create role binding

We will assume that the issuer already has created a role for its customers called customer-role. This role gives associated subjects permissions to their accounts. In this case, the permissions of the customer-role is READ, TRANSACT, and UPDATE. See the documentation about Roles for more information.

To bind the role customer-role to Alice, we perform the following command:

• Rust
• TypeScript
• Dart
• CLI

M10 REPLFOO

Create alias

Now that we've created the user Alice with an account and permissions to access her account, we can create an alias, so she's easier to find the DRM Directory. We will use Alice's phone number, +1 555-555-5555.

"[insert code sample]"

Onboarding code example

Let's put all the onboarding code together. In this code example we focus on the interactions between the PSP and the DRM platform and KYC partner.

• CLI
• TypeScript
• Rust

M10 REPLFOO

Offboard customers

Offboarding a customer means disabling the DRM account from receiving, or sending funds transfer, or perform any action on the account and deactivate the alias entry. For compliance reasons, an account isn't deleted, but rather made unavailable. Before disabling an account, the balance must be zero.

Steps to offboard a user:

• Disable user's ledger account
• Deactivate alias registry

Offboarding data flow

Offboarding code example

• CLI
• TypeScript
• Rust

M10 REPLFOO

Issue digital money

Issuing money (or digital asset) means transferring funds from an issuing account to a holding account. The starting point is that issuing account has a balance of zero (0). When issuing funds to a holding account, the balance of the issuing account goes negative and the balance of the holding account goes positive. To illustrate, we have three issuing transactions in the amounts 100 (to Alice), 50 (to Bob) and 40 (10 to Alice and 30 to Bob).

Transaction	Amount	Issuing account	Alice's holding account	Bob's holding account
0	0	0	0	0
1	100	-100	100	0
2	50	- 150	100	50
3	40	- 190	110	80

An issuer can issue funds to its own holding account, or a customer's holding account.

Assumptions:

• Issuer is a bank, or PSP issuing deposit tokens or stablecoins.
• The user has been onboarded
• The user holds deposits with the issuer (the issuer is the user's bank)

Issuing data flow

Issuing code example

• CLI
• TypeScript
• Rust

M10 REPLFOO

Redeem digital money

Redeeming digital money (or digital asset) is the reverse of issuing digital money — a holder of digital money requests the exchange of digital money for bank deposits. The request may come from the user directly, or through a PSP serving the user.

Assumption: Issuer is a bank, or PSP redeeming deposit tokens or stablecoins.

Redemption data flow

Redemption code example

• CLI
• TypeScript
• Rust

M10 REPLFOO

Freeze ledger account

An account that has been frozen can no longer send, or receive funds. The balance of the account is not changed while the account is frozen.

Freeze ledger account code example

• CLI
• TypeScript
• Rust

M10 REPLFOO

Managing user aliases

This is text for managing aliases

(Imported from ../partials/_aliases.mdx. REMOVE WHEN COMPLETED)

Facilitate an account recovery request by a customer

This is text for account recovery

(Imported from ../partials/_account-recovery-request.mdx. REMOVE WHEN COMPLETED)

Manage private keys

On the DRM platform, private keys are used to generate digital signatures, which are required to authenticate and authorize transactions on the blockchain.

Each participant has at least one private key.

Banks, Payment Service Providers (PSPs) and developers must implement the utmost security measures to protect their private keys, which are critical for maintaining the integrity and confidentiality of their API communications. Here are some best practices:

Key Generation and Storage

• Hardware Security Modules (HSMs): The most secure way to generate, store, and use private keys is within specialized hardware devices called HSMs. HSMs are designed to be tamper-resistant and offer robust cryptographic capabilities.
• Key Management Systems (KMS): Implement a KMS to manage the lifecycle of the private keys. This includes key generation, storage, rotation, and revocation. The KMS should enforce strict access controls and audit trails.
• Secure Enclaves: If HSMs are not feasible, consider using secure enclaves (e.g., Trusted Platform Modules or Intel SGX) within servers to provide an isolated and protected environment for key storage.

Access Controls and Authorization

• Least Privilege: Employ the principle of least privilege, granting only the minimum necessary access to the private keys to authorized personnel and systems. Role-Based Access Control (RBAC): Implement RBAC to define and enforce different access levels for various roles involved in key management and API operations.
• Strong Authentication: Enforce strong multi-factor authentication (MFA) for any personnel accessing or managing private keys.

Key Rotation and Revocation

• Regular Rotation: Rotate private keys at regular intervals to minimize the impact of a potential key compromise. Establish a clear key rotation policy and schedule.
• Revocation Mechanism: Implement a robust mechanism to revoke compromised or expired private keys immediately.

Monitoring and Auditing

• Logging and Monitoring: Maintain comprehensive logs of all key-related activities, including access attempts, usage, and changes. Continuously monitor these logs for any suspicious activity.
• Regular Audits: Conduct regular audits of the key management system and processes to ensure compliance with security policies and identify any potential weaknesses.

Additional Considerations

• Secure Communication: Ensure that all API communication channels are encrypted using strong protocols (e.g., TLS 1.3) to prevent eavesdropping or tampering. Incident Response Plan: Develop and regularly test an incident response plan to address any potential security breaches or key compromises promptly.
• Compliance: Adhere to relevant industry standards and regulations (e.g., PCI DSS, PSD2) for private key management and API security.

Generate reports