Skip to main content

​
1. Distribution Partner Setup & Central Vault Creation

  • Oro whitelists a new Distribution Partner, specifying its kind (Custodial or SelfCustody), and initializes its central infrastructure.
    • For Custodial partners: A central vault PDA is created for USDC deposits and holding locked user gold.
    • For Self-Custody partners: A PDA is initialized to manage KYC approvals and partner-specific configurations. The partner will also have their own operational wallet/vault for their reserves, separate from user funds.
  • The transaction is facilitated through the Oro Rest API, which provides the transaction for OroAdmin to sign and then handles the submission to the blockchain.

​
2. User Creation

  • The Distribution Partner requests user creation via the Oro Rest API.
    • For Custodial Model: The request includes a KYC-hashed identifier. The API creates the transaction to generate a compressed account (User PDA) that will store the user’s gold balances. The partner does not need to provide a wallet address for the user.
    • For Self-Custody Model: The request includes a KYC-hashed identifier and the user’s public wallet address. The API creates the transaction to generate a compressed account (User PDA) that links the KYC hash to the user’s wallet.
  • The API provides the transaction to the Distribution Partner.
  • The Distribution Partner signs the transaction with their Executive Authority Wallet and returns it to the API (along with the user’s wallet signature in the Self-Custody model, if applicable).
  • The API submits the signed transaction(s) to the blockchain.
    • Custodial Model: The compressed account (User PDA) is created to hold balances.
    • Self-Custody Model: The compressed account (User PDA) is created, linking the KYC hash to the user’s specified wallet address.

​
3. Purchase Gold for Users

  • The Distribution Partner (for Custodial users) or the User (via the Distribution Partner’s platform for Self-Custody users) requests gold purchase via the Oro Rest API.
  • The API creates the transaction, tailored for the specific model:
    • Custodial Model: The Distribution Partner signs the transaction with their Executive Authority Wallet. USDC is deducted from the central vault, and gold is locked to the User PDA.
    • Self-Custody Model: The User signs the transaction with their Web3 Wallet. USDC is deducted from the user’s wallet, and gold is sent directly to the user’s wallet. The Distribution Partner’s platform facilitates this, and their signature might be required for orchestrating the transaction.
  • The API handles the submission to the blockchain.

​
4. Gold Purchase Flow

  1. Request:
    • Custodial: The Distribution Partner submits a purchase request (specifying user, USDC amount) to the Oro Rest API.
    • Self-Custody: The User, through the Distribution Partner’s platform, submits a purchase request (USDC amount). The request includes necessary information for the API to identify the user’s KYC-linked wallet.
  2. Transaction Preparation & Signing:
    • The API creates the transaction and returns it (or the necessary data for signing) to the relevant signer(s).
    • Custodial: The Distribution Partner signs the transaction with their Executive Authority Wallet and returns it to the API.
    • Self-Custody: The User signs the transaction with their Web3 Wallet (signature is relayed via the Partner’s platform to the API). The Distribution Partner might also co-sign or provide an approval signature if required by the program logic.
  3. Submission: The API submits the signed transaction(s) to the blockchain.
  4. Execution: Once confirmed on-chain:
    • Custodial: The program deducts USDC from the central vault and mints gold tokens, locking them to the specified User PDA.
    • Self-Custody: The program facilitates the swap/purchase, deducting USDC from the user’s wallet and transferring/minting gold tokens directly to the user’s wallet. The Oro program ensures KYC compliance before tokens are delivered.
  5. Confirmation: The API confirms the purchase status.

​
5. Withdrawal Flow (Partner Operations)

This flow describes how Distribution Partners can withdraw their operational funds. For end-users in a Self-Custody model, transfers of their assets are done directly from their own Web3 wallets using standard blockchain procedures, and are not part of this API-driven withdrawal flow.
  1. Request Initiation (Partner Withdrawal):
    • Custodial Model (Partner Withdrawal from Central Vault): The Distribution Partner requests a withdrawal of their unused USDC or unlocked Gold tokens (not allocated to users) via the Oro Rest API.
    • Self-Custody Model (Partner Withdrawal from Operational Vault): The Distribution Partner requests a withdrawal of their own unused USDC or unlocked Gold tokens from their operational vault/wallet via the Rest API.
  2. Transaction Preparation & Signing (Partner Withdrawal):
    • The API creates the withdrawal transaction for the partner.
    • The Distribution Partner signs it with their Withdrawal Authority Wallet (can be multi-sig) and returns it to the API.
  3. Submission (Partner Withdrawal): The API submits the partner-signed transaction to the blockchain.
  4. Execution (Partner Withdrawal):
    • Custodial Model: The program transfers unused USDC and unlocked (partner-owned) gold tokens from the central vault PDA to the partner’s specified wallet. Locked gold tokens assigned to user PDAs cannot be withdrawn by the partner.
    • Self-Custody Model: The program transfers unused USDC and unlocked gold tokens from the partner’s operational vault/wallet to their specified external wallet.
  5. Confirmation (Partner Withdrawal): The API confirms the transaction status to the partner.