CoKeeps Docs

Appearance

Back-End ​

Overview ​

Your back-end plays a critical role all actions conducted via the CoKeeps Hot Wallet. It serves as the bridge between the CoKeeps platform and your own system, ensuring seamless integration and synchronised communication.

When it comes to end user access, the CoKeeps Hot Wallet relies on your system to determine user existence, roles, and other limitations you have set. This ensures that the CoKeeps Hot Wallet operates within the bounds of your organisational policies and security measures.

To facilitate this communication, only four REST API endpoints need to be set up on your back-end service. These endpoints enable the exchange of necessary data and validation checks between your system and the CoKeeps platform.

IMPORTANT

The availability of your back-end service is paramount. Any downtime or disruption in service could impact the functionality of the CoKeeps Hot Wallet and hinder transaction processing. It's essential to maintain uptime and reliability to ensure uninterrupted service for your users.

Preparations ​

Network ​

For secure communication between your back-end and the CoKeeps Hot Wallet, it's ideal to establish a Virtual Private Network (VPN). This ensures that data transmission occurs within a protected network environment, safeguarding sensitive information from unauthorised access.

During the onboarding session between your technical team and ours, further details regarding VPN configuration and setup can be discussed to ensure seamless integration.

Alternatively, if a VPN setup is not feasible, the minimum requirement is to implement Transport Layer Security (TLS) over HTTPS. This protocol encrypts data transmission over the internet, providing a level of security against interception and tampering.

Regardless of the network infrastructure deployed, it's imperative to restrict incoming requests to your back-end service only from authorised sources, specifically the CoKeeps Hot Wallet server. This helps prevent unauthorised access and ensures that communication channels remain secure.

Overall, maintaining encryption for all communication channels is essential to protect sensitive data and uphold the integrity of your system.

Data Encryption ​

All request and response payloads are encrypted using the Advanced Encryption Standard (AES). AES is selected for its widespread support and compatibility with various back-end services. Both the CoKeeps Hot Wallet and your back-end service will utilise the same secret key for encryption and decryption.

Below is an example demonstrating encryption in JavaScript:

javascript
const AES = require("crypto-js/aes");

const payload = "some_arbitrary_string";
const secret = "shared_secret";
const ciphertext = AES.encrypt(payload, secret).toString();

console.log(ciphertext)

The code snippet provided above produces a ciphertext represented as U2FsdGVkX18fBdZ7xNi0aOX9b5M97C7+N2m2ZBx2/dzEal6SuHse8NOkbCV7kJ54. This ciphertext is the encrypted version of the payload using the shared secret key. To verify your implementation, attempt to decrypt the ciphertext provided above.

Receiving Endpoints ​

All requests to your backend will contain the following format:

JSON
{
    ciphertext: AES.encrypt(JSON.stringify({
        // Payload
    }))
}

All responses from your backend payload should conform to the following format:

Success:

JSON
{
    success: true,
    message: "OK",
    ciphertext: AES.encrypt(JSON.stringify({
        // Payload
    }))
}

Error:

JSON
{
    success: false,
    message: "Error message..",
    ciphertext: AES.encrypt(JSON.stringify({}))
}

User Verify ​

Incoming request payload: https://<your-backend-url>/user_verify

JSON
{
	"hashedUsername": "string",
	"hashedPassword": "string",
	"x": "string"
}

Both hashedUsername and hashedPassword are hashed using the SHA-256 algorithm. This request allows the CoKeeps Hot Wallet to verify with your system whether the provided information corresponds to an existing user with permission to access and whether the account is active.

  • hashedUsername: Hashed representation of the user's username, email, or other unique identifier used for login. Do not remove on user credential reset.

  • hashedPassword: Hashed representation of the user's password, using a secure hashing algorithm. Do not remove on user credential reset.

  • x: Arbitrary value passed by the CoKeeps Hot Wallet, which your system must hash with a salt to produce a key value. Do not remove on user credential reset.

Warning: It is imperative that your user management system does not store raw passwords in the database. Storing passwords in plaintext poses a significant security risk, as it exposes sensitive user information to potential breaches. Instead, utilize secure hashing algorithms to hash and store password hashes, ensuring that even if the database is compromised, the passwords remain protected. This security measure is essential for safeguarding user accounts and maintaining trust in your platform's security practices.

Response payload:

JSON
{
	"uid": "string",
	"key": "string"
}

  • uid: Universally Unique Identifier (UUID) of the user in your system identified by hashedUsername and hashedPassword.

  • key: A hashed value derived from the x value and a salt, ensuring consistency and integrity of the communication. This key is crucial for maintaining the security of the CoKeeps Hot Wallet integration.

The key value is generated as follows:

javascript
const SHA256 = require("crypto-js/sha256");

// You can use a dedicated salt based on the UID,
// provided it remains consistently associated with that UID.
const salt = "super_secret_uid_salt";
const x = "arbitrary_value_passed_by_cokeeps_hot_wallet";

const key = SHA256(salt + x).toString();

console.log(key);

Which will produce a key value of 85121f6138cdc292b8f483bba88779df53c74ef3df47c5b318c111f8d4d78479 at any time.

IMPORTANT

Ensure that the key value remains deterministic and consistent to prevent any loss of digital assets.

Machine Verify ​

Incoming request payload: https://<your-backend-url>/machine_verify

JSON
{
	"machine_id": "string",
	"x": "string"
}

Serves a similar purpose as User Verify but is specifically designed for machines. Your back-end service should maintain a static list of Machine IDs, as this list will remain unchanged after the initial integration setup is complete.

  • machine_id: Denotes the ID of the machine generated by CoKeeps Cold Wallet.

  • x: Arbitrary value passed by the CoKeeps Hot Wallet, which your system must hash with a salt to produce a key value.

Response payload:

JSON
{
	"key": "string"
}
  • key: A hashed value derived from the x value and a salt, ensuring consistency and integrity of the communication. This key is crucial for maintaining the security of the CoKeeps Hot Wallet integration.

The key value is generated as follows:

javascript
const SHA256 = require("crypto-js/sha256");

// You can use a dedicated salt based on the Machine ID,
// provided it remains consistently associated with that Machine ID.
const salt = "super_secret_machine_salt";
const x = "arbitrary_value_passed_by_cokeeps_hot_wallet";

const key = SHA256(salt + x).toString();

console.log(key);

Which will produce a key value of 7097937d1a6d41c3a727ed8ac6d5d6af479b8d53ba74ae324ec2de34f80fc283 at any time.

IMPORTANT

Ensure that the key value remains consistent to prevent any loss of digital assets.

Read ​

This endpoint is designed to provide CoKeeps Hot Wallet with information about your user using UUID as a reference.

Your Back-End Service is expected to assign two roles for all write operations in the CoKeeps Hot Wallet:

  • signer: Assigned to end users, this role has limited functionality.

  • admin: Reserved for administrators, this role encompasses all signer functionalities and additional privileges.

Incoming request payload: https://<your-backend-url>/read

JSON
{
	"uid": "string",
    "reference_id": "string" // Passed along
}

reference_id is a value that is passed along during a Transfer Transaction, Smart Contract Transaction, or Omnibus Withdrawal.

IMPORTANT

Use reference_id to safeguard against unauthorized API usage from the front-end.

Response payload example:

JSON
{
	"role": "signer", // or "admin"
    "limits": [
        {
           "chain_id": "bitcoin",
           "balance": "0.1",
           "limit": "0.005"
        },
        {
           "chain_id": "solana",
           "balance": "20.113",
           "limit": "5.0"
        }
    ],
	"destinations": [
        {
            "chain_id": "bitcoin",
            "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
        },
        {
            "chain_id": "solana",
            "address": "2wmVCSfPxGPjrnMMn7rchp4uaeoTqN39mXFC2zhPdri9"
        }
    ]
}

  • The role field indicates whether the user is a signer or an admin.

  • The limits field, while optional for Omnibus setups, can be used to specify maximum transfer values for the user's chain ID in decimal string format. This allows for control over the maximum amount that the user can transfer on each supported blockchain network (Chain ID). More sophisticated controls, such as daily limits or per-transaction limits, can be implemented on your back-end service. CoKeeps Hot Wallet will adhere to these specified limits. However, if the limit specified exceeds the user's balance in the Signer Wallet or the balance recorded in the Dynamic Ledger, the request will not go through and an error will be returned.

    • limits[i].balance represents the user's current balance with respect to the chain_id.
    • limits[i].limit is the maximum amount the user is allowed to transfer. This limit cannot exceed the user's balance.

  • The destinations field is optional and represents the address of the coin or token. If a value is provided, it will be used to check against the value that is stored by the CoKeeps Hot Wallet for consistency purposes.

NOTE

Additional fields may be included if there are more complex preferences required on your end.

Update ​

The CoKeeps Hot Wallet sends direct notifications for the following events:

Omnibus notifications:

  • Destination address set
  • Withdrawal request
  • Approval or rejection decision
  • Completion of transaction process

Alerts for failed transactions:

  • Transfer
  • Gas Station funding
  • Sweeping

NOTE

Additional events may be included if there are more complex preferences required on your end.

Incoming request payload: https://<your-backend-url>/update

JSON
{
	"uid": "string",
	"destination": {
		"address": "string",
		"chain_id": "string",
		"signature": "string",
		"id": "string"
	}
}

Response payload:

JSON
{} // Empty object

The CoKeeps Hot Wallet will attempt to resend notifications a maximum of three times within a 5-minute interval if your back-end service fails to respond accordingly.

Secret and Salt Management ​

Secret ​

The secret refers to the value used in AES encryption and decryption of payload data exchanged between the CoKeeps Hot Wallet and your back-end service. If this secret is compromised, it should be replaced immediately.

It's crucial to ensure that the secret value is not stored within your source code or a distributed version control system. Ideally, the value should be stored in a separate configuration file and shared with the back-end service via a restricted environment variable.

Salt ​

The salt is used to generate the key mentioned in the User Verify and Machine Verify receiving endpoint section previously. CoKeeps should not have knowledge of this value, and it should remain consistent throughout the usage of the CoKeeps Hot Wallet.

The salt value can be arbitrary, but it's recommended to use a longer value with higher entropy. You can generate the salt value by hashing a password with SHA-512, for example. As long as the salt remains deterministic, it can be reliably used.

Similar to the secret value, the salt value should not be distributed and should remain isolated from irrelevant parties.

Sharding Strategy ​

To enhance security and avoid storing the secret or salt in a single location, you can distribute the value across multiple locations using Shamir Secret Sharing. In this strategy, the back-end service combines the shards to reconstruct the original value.

bash
                                   ┌──────────────────┐
                               ┌───┤ Shard 1 Location │
                               │   └──────────────────┘
	┌──────────────────────┐   │                       
	│   Back-end Service   │   │   ┌──────────────────┐
	│                      ├───┼───┤ Shard 2 Location │
	│    Combine 2 of 3    │   │   └──────────────────┘
	└──────────────────────┘   │                       
                               │   ┌──────────────────┐
                               └───┤ Shard 3 Location │
                                   └──────────────────┘

You can employ as many shards and threshold configurations as necessary, providing redundancy and eliminating single points of failure.

NOTE

This strategy is optional and should only be implemented after a full understanding of how to efficiently perform redundancy infrastructure and how Shamir Secret Sharding works.

Copyright © 2024 CoKeeps Sdn Bhd