CoKeeps Docs

Appearance

Integration Strategy ​

This section provides a practical, end-to-end view of how to integrate your platform with the CoKeeps Hot Wallet and CKSDK. It is intended for developers, solution architects, and integrators who need to understand what to build, where responsibilities sit, and how to make secure design choices.

Where relevant, this section will reference other parts of the documentation instead of repeating details.

1. Architectural Overview ​

CoKeeps Hot Wallet is designed as a set of modular building blocks - much like puzzle pieces that you can compose into almost any use case:

  • Retail exchanges and brokerages
  • Custodial platforms and omnibus ledger setups
  • Token issuance, smart-contract interactions, and staking workflows
  • Any non-fintech application that needs secure digital asset capabilities without managing wallets and keys directly

At a high level, your integration consists of:

  1. Your front-end (web / mobile / admin UI)
  2. Your back-end service (business logic, user and risk decisions)
  3. CoKeeps Hot Wallet (wallet engine, orchestration, on-chain execution)
  4. CKSDK (cryptographic client - front-end, back-end with bridge, or back-end only)

The Hot Wallet handles digital asset management and security; you stay focused on your product logic, compliance, and user experience.

2. Security Model - How Responsibilities Are Split ​

Several key principles underpin the Hot Wallet security model:

  • Per-user cryptographic keypairs
    Each end user is represented by a cryptographic keypair handled by CKSDK, not by a shared API key or bearer token. This enforces:

    • Non-repudiation and accountability
    • Reduced risk of developer spoofing transactions on behalf of users
    • Fine-grained traceability at the user level

  • No conventional API keys for user authority
    REST calls between your back-end and the Hot Wallet are authenticated and encrypted, but user authority is derived from their keypair, not from a static shared secret.

  • Encrypted transport & payloads

    • All communication with CoKeeps services uses TLS over HTTPS.
    • Request/response payloads between your back-end and the Hot Wallet are additionally encrypted using AES with a shared secret (see Preparations → Data Encryption and Secret and Salt Management).
    • CoKeeps provides the encryption secret during onboarding; you are responsible for storing it securely.

  • Signature Based Data Verification (SBDV)
    CKSDK signs key payloads, and those signatures are stored and later verified when the Hot Wallet system consumes data from the database. This provides:

  • No PII stored in the Hot Wallet

You should also apply your own security controls, including MFA, strict access control for admin functions, secure secret management, and hardened hosting for administration tools.

3. Integration Flow - From Zero to Production ​

At a high level, the integration lifecycle looks like this:

  1. Onboard with CoKeeps

    • Obtain:
      • Hot Wallet URL (<ck_hotwallet_url>)
      • Hot Wallet public key (hostSignPublicKey)
      • AES secret for payload encryption
      • CKSDK (frontend and/or NodeJS variant)
    • See Rest API and Preparations.

  2. Prepare your infrastructure

    • Set up network protections (VPN or TLS + IP restrictions).
    • Decide your environments (e.g. staging, production) and which chain IDs (testnet / mainnet) to enable.
    • Ask your Authoriser to enable networks via the CoKeeps Client Administration platform.
      See Networks and Get Available Chains.

  3. Implement the four back-end endpoints

  4. Integrate CKSDK

  5. Design database and user model

    • Persist CKSDK-compatible values (hashedUsername and hashedPassword).
    • Implement an internal UUID (uid) as the stable user reference that CoKeeps uses.
      See User Verify and Secret and Salt Management.

  6. Wire business flows

  7. Test on testnet

    • Use test networks for all business flows until you're comfortable with:
      • Address creation and mapping
      • Sweep and rebalancing procedures
      • Ledger and withdrawal reconciliation
    • See Networks and Gas Station.

  8. Promote to mainnet

    • Coordinate with CoKeeps to provision mainnet networks and funding strategy (Gas Station, omnibus accounts, etc.).
    • Confirm operational processes: approvals, rebalancing, monitoring, and incident response.

4. Choosing Your CKSDK Integration Strategy ​

CKSDK can be implemented in three ways. All options use the same core cryptography and protocol but differ in who holds operational power and how much trust you place in your own back-end.

4.1 Frontend CKSDK (Highest Security) ​

Where: Runs on the user's device (browser / webview).
Who controls authority: The end user via their device-local keypair.

Characteristics:

  • Authentication keypair is generated and stored (encrypted) on the user's device.
  • Front-end signs and encrypts all requests directly with CKSDK.
  • Your back-end is mostly a policy oracle (via /read) and notification sink (via /update), not an execution authority.

Pros:

  • Maximum user-level security and accountability.
  • Minimises risk of internal misuse by developers / operators.
  • Strong alignment with user-centric security models.

Cons:

  • More complex to implement and maintain on front-end.
  • Requires careful handling of session storage, device trust, and MFA.
  • Harder to use for purely machine-driven workflows.

See CKSDK - Overview and Frontend Implementation for a full code example.

4.2 Backend CKSDK with Bridge (Balanced) ​

Where:

  • CKSDK runs on your back-end.
  • A small bridge component runs on the front-end and passes a sealed (encrypted) payload (sealed) to your back-end.

Characteristics:

  • Front-end obtains a bridge public key and produces a sealed payload using CKSDK (in browser / Dart / Flutter, etc.).
  • Back-end CKSDK uses the sealed value to derive per-user cryptographic context and then performs actions (generate deposit, transfers, etc.).
  • User secrets never need to be stored on the front-end beyond session scope.

Pros:

  • Good balance between security and operational convenience.
  • Developers have less direct power than a pure back-end implementation, as they rely on the bridge for user-level cryptography.
  • Easier to integrate with mobile apps that aren't JavaScript-based.

Cons:

  • More moving parts (front-end bridge + back-end CKSDK).
  • Still requires secure session and secret handling in your back-end.

See Backend Implementation using Bridge for a complete walkthrough and TypeScript integration notes.

4.3 Backend CKSDK Only (No Bridge - Simplest, Lowest Accountability) ​

Where: CKSDK runs only on your back-end.

Characteristics:

  • No CKSDK on the front-end.
  • The back-end calls auth.login() directly with a synthetically constructed username and password (derived from your own secret algorithms).
  • You may store and reuse sessions using self_store / self_load so you don't have to re-authenticate on every call.

Pros:

  • Simplest integration path.
  • Useful when your platform is purely API-driven or when user interaction is primarily server-side.

Cons:

  • Your back-end effectively controls all user actions.
  • Accountability is reduced: this model is closer to a "per-user API key" pattern.
  • You must design very strong internal controls to prevent misuse by developers/operations.

See Backend No Bridge Implementation for detailed examples and caveats.

Recommendation:

  • If you are a regulated custodian or exchange with strong internal controls, the Bridge model is usually the best balance.
  • For high-assurance, user-centric platforms, use Frontend CKSDK.
  • Use Backend Only only when you fully understand and accept the operational risk and have robust governance in place.

5. Your Back-End: The Four Required Endpoints ​

Your back-end exposes four REST endpoints that CoKeeps Hot Wallet calls for every security-sensitive operation. These endpoints must accept encrypted payloads, decrypt them using the shared AES secret, and return encrypted responses.
See Preparations → Data Encryption and Rest API for payload format and encryption examples.

5.1 /user_verify ​

  • Purpose: verify end user credentials and map them to your internal uid.
  • Request (decrypted):
    • hashedUsername: SHA-256 of username/email/identifier.
    • hashedPassword: SHA-256 of the user's password or secret (never store raw passwords).
    • x: arbitrary value from CoKeeps, used by you to compute a deterministic key using your salt.
  • Response:
    • uid: your platform's user UUID.
    • key: SHA-256(salt + x), deterministic for that user.

See User Verify for full JSON and code examples.

5.2 /machine_verify ​

  • Purpose: verify machine identities (e.g. signers or system jobs).
  • Request:
    • machine_id: static ID managed by CoKeeps Hot Wallet.
    • x: arbitrary value from CoKeeps.
  • Response:
    • key: hashed value derived from x and your machine salt.

See Machine Verify for details.

5.3 /read ​

  • Purpose: provide roles and limits for a user and a given reference_id.

  • Request:

    • uid: your user UUID.
    • reference_id: reference passed through from CKSDK (e.g. ticket / order ID).

  • Response (minimal):

    • role: "signer" or "admin".

  • Response (for transfers / withdrawals):

    • limits: per-chain transfer limits, including current balances.
    • destinations: whitelisted destinations for consistency checks.

See Read for the full schema and notes on advanced policy logic.

5.4 /update ​

  • Purpose: receive notifications from the Hot Wallet about events such as:

    • Omnibus destination set / withdrawal request / approval / rejection / completion
    • Failed transaction attempts (e.g. sweep, gas station, transfer)

  • Request (example):

    • uid
    • destination or other event-specific payload

  • Response:

    • {} (empty object), encrypted.

You should log all /update calls for auditing and debugging. See Update for details and retry behaviour.

6. Database Design & Credential Handling ​

To support CKSDK and Hot Wallet semantics, your database should be designed with the following principles:

6.1 Stable User Identity (uid) ​

  • Introduce a stable UUID (uid) per user.
  • This uid:
    • Is returned in /user_verify responses.
    • Is referenced throughout the Hot Wallet (deposits, destinations, reviews, ledger, etc.).
    • Must remain valid for the lifetime of the user's relationship with your platform.

6.2 Handling hashedUsername and hashedPassword ​

From the Hot Wallet's perspective:

  • hashedUsername and hashedPassword are SHA-256 digests supplied in /user_verify.
  • Do not discard or delete these mappings when a user resets their credentials.

Recommended pattern:

  • Store your own password hash (e.g. bcrypt / Argon2) for login.

  • Separately, maintain a mapping table such as:

    iduidhashed_usernamehashed_passwordactivecreated_at

  • When credentials rotate:

    • Insert a new row with the new hashed_password.
    • Optionally mark previous rows as active = false, but keep them for history and to avoid collisions.

  • /user_verify finds the matching row by hashedUsername + hashedPassword and returns the associated uid.

This ensures:

  • CoKeeps can continue to identify the user correctly across credential changes.
  • You maintain an auditable trail of credential transitions without storing raw passwords.

6.3 Salt and Key Management ​

  • You maintain the salts used to generate the key in /user_verify and /machine_verify.
  • CoKeeps must never know these salt values.
  • Consider optional Shamir Secret Sharing if you want to shard these secrets across multiple stores.
    See Secret and Salt Management for full recommendations.

7. Best Practices & Recommendations ​

To make the most of CoKeeps Hot Wallet while minimising operational risk, consider the following:

  • Start with testnet

    • Run end-to-end flows on test networks before touching mainnet.
    • Validate monitoring, sweeping, Dynamic Ledger reconciliation, and Omnibus withdrawal approvals.

  • Separate duties and roles

    • Use separate users for Authoriser, Signer, Payer, and Hot Wallet admin wherever possible.
    • Avoid giving a single user full control across roles.
    • This aligns with the recommendation in Roles & Permissions to reduce concentration of power.

  • Enforce admin review where appropriate

    • Use Pending Review for Signer Wallet transfers where policy requires maker-checker.
    • Use admin decide.* actions for destination, Travel Rule, transaction requests, and omnibus withdrawals.
      See Decisions and List Pending Reviews.

  • Control sweep and rebalancing procedures

    • Clearly define operational runbooks for:
      • sweep_deposits
      • sweep_withdrawal
      • sweep_gas_station
      • sweep_signer_wallet_bases
      • rebalance

  • Harden your front-end and admin tools

    • Use MFA and strict RBAC for all admin/front-office tools.
    • Ensure front-end frameworks are protected against XSS and injection that could tamper with CKSDK calls.
    • For high-value operations, consider out-of-band or multi-admin approval on your side.

  • Log and monitor aggressively

    • Store logs for /update and relevant "information" REST API responses.
    • Correlate reference_id, uid, and tid / rid for investigations.
    • Periodically compare on-chain state via Lookup Address / Lookup Transaction with internal ledger state.

  • Document your own policies

    • Clearly document how your /read endpoint enforces limits and destinations.
    • Make sure your compliance/risk team understands how Travel Rule, destination approval, and Dynamic Ledger interact.

8. Where to Go Next ​

Use this Integration Strategy as a roadmap and then dive into the detailed sections as needed:

By following this strategy and the referenced sections, your team can move from initial design to a secure, robust, and auditable integration with CoKeeps Hot Wallet.

Copyright © 2025 CoKeeps Sdn Bhd