Architecture

Institutional Host are entities that people trust to hold their deposits and issue credits into the HC Net for those deposits. All money transactions in the HC Net (except HCX) occur in the form of credit issued by Institutional Hosts, so Institutional Hosts act as a bridge between existing currencies and the HC Net. Most Institutional Hosts are organizations like banks, savings institutions, farmers’ co-ops, central banks, and remittance companies.

Before continuing, you should be familiar with:

• Issuing assets, the most basic activity of an Institutional Host.
• Mapping, which allows a single HC Net account to represent multiple people.
• Regulation, if you are subject to any financial regulation.

Account Structure

As an Institutional Host, you should maintain at least two accounts:

• An issuing account used only for issuing and destroying assets.
• A base account used to transact with other HC Net accounts. It holds a balance of assets issued by the issuing account.

Create them on the test network using the laboratory or the steps from the “get started” guide.

For this guide, we’ll use the following keys:

Issuing Account ID

GAPJN32J7O6EXXWNZ2P5VIMT7KFETQMZN27IILUSW7KZDZKCNRLQFON

Issuing Seed

S6EXXWNZ7J7EXXWNZ2P5VIMT7KAPJNMZN27MTLUSW7KZW7KCN2P5VIM

Base Account ID

GAKO2Y56HOH44EWUP5C4BEQKLLION2TPJX4JQONZX7XOVJNMY5LG7UWWO

Base Seed

SDRZNLEYULLLVYHJV9TRPQAPY7KQF5WIME52OMLKVQXNKIVX3FLGMPVBZ

Customer Accounts

There are two simple ways to account for your customers’ funds:

• 1. Maintain a HC Net account for each customer. When a customer deposits money with your institution, you should pay an equivalent amount of your custom asset into the customer’s HC Net account from your base account. When a customer needs to obtain physical currency from you, deduct the equivalent amount of your custom asset from their HC Net account.
• 2. This approach simplifies bookkeeping by utilizing the HC Net instead of your own internal systems. It can also allow your customers a little bit more control over how their account works in HC Net.
• 3. Use Mapping and the memo field in transactions to send and receive payments on behalf of your customers. In this approach, transactions intended for your customers are all made using your base account. The memo field of the transaction is used to identify the actual customer a payment is intended for.
• 4. Using a single account requires you to do additional bookkeeping, but means you have fewer keys to manage and more control over accounts. If you already have existing banking systems, this is the simplest way to integrate HC Net with them.

Using a single account requires you to do additional bookkeeping, but means you have fewer keys to manage and more control over accounts. If you already have existing banking systems, this is the simplest way to integrate HC Net with them.

Data Flow

In order to act as an Institutional Host, your infrastructure will need to:

• Make payments.
• Monitor a HC Net account and update customer accounts when payments are received.
• Look up and respond to requests for federated addresses.
• Comply with Anti-Money Laundering (AML) regulations.

Hc Net provides a prebuilt mapping server and regulation server designed for you to install and integrate with your existing infrastructure. The communication server coordinates them and simplifies interacting with the HC Net. This guide demonstrates how to integrate them with your infrastructure, but you can also write your own customized versions.

Making Payments

When using the above services, a complex payment using mapping and regulation works as follows:

• 1. A customer using your organization’s app or web site sends a payment using your services.
• 2. Your internal services send a payment using the communication server.
• 3. The communication server determines whether regulation checks are needed and forwards transaction information to the regulation server.
• 4. The regulation server determines the receiving account ID by looking up the mapping address.
• 5. The regulation server contacts your internal services to get information about the customer sending the payment in order to provide it to the receiving organization’s regulation systems.
• 6. If the result is successful, the communication server creates a transaction, signs it, and sends it to the HC Net.
• 7. Once the transaction is confirmed on the network, the communication server returns the result to your services, which should update your customer’s account.

Receiving Payments:

When someone is sending a transaction to you, the flow is slightly different:

• 1. The sender looks up the HC Net account ID to send the payment to based on your customer’s mapped address from your mapping server.
• 2. The sender contacts your regulation server with information about the person sending the payment.
• 3. Your regulation server contacts three services you implement:
  • 1. A sanctions callback to determine whether the sender is permitted to pay your customer.
  • 2. If the sender wants to check your customer’s information, a callback is used to determine whether you are willing to share your customer’s information.
  • 3. The same callback used when sending a payment (above) is used to actually get your customer’s information.
• 4. The sender submits the transaction to the Hc Net.
• 5. The communication server monitors the HC Net for the transaction and sends it to your regulation server to verify that it was the same transaction you approved in step 3.1.
• 6. The communication server contacts a service you implement to notify you about the transaction. You can use this step to update your customer’s account balances.

While these steps can seem complicated, HC Net’s communication, mapping, and regulation services do most of the work. You only need to implement four callbacks and create a HCNet.toml file where others can find the URL of your services.

In the rest of this guide, we’ll walk through setting up each part of this infrastructure step by step.