LogoLogo
PAO DocsCommunity DocsInfrastructure DocsPeerplays.com
  • Developer Documentation
  • API Reference
    • Peerplays Core API
      • Popular API Calls
      • Account History
      • Asset API
      • Block API
      • Crypto API
      • Database API
      • Network Broadcast API
      • Network Nodes API
      • Orders API
    • Wallet API
      • Account Calls
      • Asset Calls
      • Blockchain Inspection
      • General Calls
      • Governance
      • Privacy Mode
      • Trading Calls
      • Transaction Builder
      • Wallet Calls
    • Bookie API
      • General Calls
      • Listeners
      • Tournaments
  • Peerplays API Libraries
    • Python Peerplays
      • Installation
      • Creating an Account
      • Creating a Peerplays Wallet
      • NFT API
      • Marketplace API
      • Role Based Permissions API
  • Development Guides
    • Creating User Issued Assets
    • Introduction to Permissions
    • NFT Minting
    • Calculating Costs
  • The Cookbook
    • NFTs for Staking Creator Tokens
  • Tools and Integrations
    • PeerID
      • 1.0.0
        • Infrastructure
          • Deployment on a Linux Serve
          • Deployment to AWS ECS
            • Building the Docker Images
            • Storing Secrets in Amazon Parameter Store to use in ECS
            • Creating the Task Definition
            • Creating the Cluster
            • Creating the Service
        • Development
          • How does PeerID work without storing the keys ?
          • Authentication with PeerID
          • Brain Storming
          • Software Requirements
      • Authentication with PeerID
      • Requirements Specification
    • Random Number Generator
      • RNG Technical Summary
      • RNG API
  • Supporting & Reference Docs
    • Peerplays Development FAQs
    • Sidechain Operator Node (SON) Development
      • Generic Sidechain Docs
        • Quick joining GLADIATOR
        • Changes to Peerplaysjs-lib
        • Requirements Specification
        • Low Level Designs
          • bitcoin-deposit-handling-lld
          • bitcoin-operations-draft
          • bitcoin-sidechain-handler-lld
          • bitcoin-sidechain-multisig-bitcoin-wallet-and-bitcoin-addresses-pw
          • bitcoin-withdrawal-handling-lld
          • btc-address-scripting-mechanism
          • comparison-between-scenarios-for-handling-deposits-and-withdrawals
          • exchange-rate-list
          • generic-sidechain-deposit-hld
          • generic-sidechain-high-level-design
          • generic-sidechain-listener-hld
          • generic-sidechain-withdrawal-hld
          • refund-btc-mechanism
          • son-configuration
          • son-consensus-communication-and-transaction-signing-on-chain-lld
          • son-de-register-proposals-lld
          • son-objects-and-operators
          • son-rewards-lld
          • son-voting-lld
          • son-wallet-list_sons-lld
          • creation of a multi-sig bitcoin address lld
          • claiming initial son vesting lld
          • changeover and SON maintenance scenarios lld
          • user-sidechain-addresses-mapping
          • wallet-commands-for-son
        • Functional Specs
          • SON Configuration
          • SON rewards
          • SON Voting and Consensus
          • SONs switchover scenarios
          • SON Status Operations & Monitoring
          • Proposals
          • SON Smart Contracts
      • Bitcoin Sidechain Docs
        • Functional Specs
          • btc-refunds
          • voting-and-consensus
          • son-switchover
          • son-rewards
          • son-proposals
          • son-configuration
          • heartbeat-monitoring
          • BTC Transaction Processing & Signing
          • Bitcoin Withdrawal Handling
          • Bitcoin Deposit Handling
          • SON Multisig Bitcoin Wallet
      • Hive Sidechain Docs
        • Functional Specs
          • HIVE Deposit Handling
          • HIVE Withdrawal Handling
    • Peerplays DEX Development
      • Peerplays NEX
        • Functional Specifications
          • NEX-FS01 Dashboard Page
            • NEX-FS12 ETH-SONs Deposit/Withdraw Functionality
          • NEX-FS02 Login and Account Creation
          • NEX-FS03 Menus and Nav
          • NEX-FS04 Notifications
          • NEX-FS05a Market Page (alpha)
          • NEX-FS05 Market Page
          • NEX-FS06 Profile Page
          • NEX-FS07 Wallet Functions
          • NEX-FS08 App Settings
          • NEX-FS09 Blockchain Page
          • NEX-FS10 GPOS Page
          • NEX-FS11 WhaleVault Integration
      • Requirements Specification
      • Functional Specs
        • Asset Info Page and Asset Lists
        • Dashboard
        • Exchange Page
        • Login and Account Creation
        • User Account Page
        • Voting Page
    • SPK Network
      • Functional Specs
        • Claimdrop Snapshot Functional Specification
        • Initial Claimdrop Functional Specification
    • NFT Development
      • NFT Store
        • NFT Store User Stories
        • NFT Store UI HLD
        • NFT Store Requirements Specification
        • Functional Specifications
          • APP-FS01 App Header
          • APP-FS02 App Body
          • APP-FS03 App Footer
          • APP-FS04 App Navigation
          • APP-FS05 Wallet Functions
          • APP-FS06 App Home Page
          • APP-FS07 Account Page
          • APP-FS08 Browse View
        • App Page List
        • Requirement Traceability Matrix
    • Operation IDs List
    • Sidechain Flow Diagram (HIVE coin)
    • Sidechain Flow Diagram (Bitcoin)
    • Sidechain Flow Diagram (Ethereum coin)
    • TradeHands Explorer
      • User Personas
      • User stories
      • APP-FS01 Detailed View
      • Draft: APP-FS02 Front Page
      • APP-FS03 Collection Details Page
    • Grafana
      • Grafana Installation
      • Install Grafana Behind reverse proxy
      • Loki Installation
      • Promtail agent Installation
      • Grafana Explorer
    • NEX Deployment & Configuration
      • NEX Deployment
      • NEX - Blockchain API configuration
      • Deploying NEX in a HA scenario
    • API Node
      • MarketCap API
    • TOTO Application
      • FS-Subscription Plan
      • FS-Achievements
  • Development Workflow Docs
    • Development Workflow
  • Other Documentation
    • Peerplays Home
    • Community Docs
    • Infrastructure Docs
    • Site Reliability Engineering
Powered by GitBook
On this page
  • 1. Purpose
  • 2. Scope
  • 3. Background
  • 4. Process Overview
  • 5. Context
  • 6. Flow Diagram
  • 7. Requirements
  • 7.1 Listener
  • 7.2 Handler
  • 7.3 Refunds
  • 7.4 Deposit Address - One-or-weighted-multisig
  • 8. Glossary
  • Supporting Information

Was this helpful?

Export as PDF
  1. Supporting & Reference Docs
  2. Sidechain Operator Node (SON) Development
  3. Hive Sidechain Docs
  4. Functional Specs

HIVE Withdrawal Handling

SON-HIVE Functional Specifications - Hive Withdrawal Handling

1. Purpose

The purpose of this document is to outline functional specifications for monitoring Hive network and handling withdrawals. Result of a withdrawal is conversion of Peerplays assets (pHIVE and/or pHBD) to Hive (HIVE and/or HBD) using 1:1 ratio.

2. Scope

Sidechain operating node will monitor Hive network for events of interest, namely transfer of assets to a Peerplays controlled Hive address. When transfer happens, sidechain logic will process it, in order to pick up information needed to handle it. Handling withdrawals will create certain amount of tokens on a Peerplays network. This amount will match the amount of assets on target sidechain by predefined exchange rate ( In this case 1:1).

Specific functions covered include:

  • monitor transactions to a designated sidechain user address

  • handle withdrawal via creation of sidechain event data

  • create & confirm object proposals

  • conversion of pHIVE to HIVE based on defined exchange rate, with applicable fees

  • sign transactions

  • withdraw Hive for conversion into Peerplays tokens

3. Background

Withdrawal handling will consist of listener and handler functionality. Listener can identify and report new blocks, a transaction, or filtered single event (like specific operation involving specific address). Handlers will process the event identified by listener.

Requirements below are describing functional specifications based on using a Multi-signature primary wallet controlled by SON network, holding all the funds. All transfers are made to and from this multi-signature wallet.

4. Process Overview

Described here is the process of monitoring withdrawal address and processing transactions that occur in relation to a target address.

pHIVE token issue is initiated by Sidechain Listener identifying a Hive withdrawal, passing information to Sidechain Handler.

Steps involved:

  1. User initiates withdrawal to convert pHIVE to HIVE (or pHBD to HBD)

  2. Listener identifies withdrawal type change in the blockchain

  3. Listener passes event data to handler

  4. Handler receives event data and creates an object (normally SON Wallet Object, SON Wallet Deposit Object or SON Wallet Withdraw Object)

  5. Object is checked by by all active SONs to compare object data from the chain against data generated by each SON.

    1. If data does not match, transaction is terminated

    2. If data matches, object is deemed 'Confirmed'. Proceed to next step

  6. Handler checks the number of active SONs

    1. If active SONs are > 5, proceed to next step

    2. If active SONs are < 5, store transaction for processing until required number of active SONs is available (this step will be repeated until SON availability requirement is met)

  7. Issue proposal for for sidechain transaction create operation

  8. Active SONs create local copies of transaction data to be verified against proposal

  9. Proposal is verified by active sons by comparing local copies of transaction data to proposal

    1. If data does not match, proposal is not approved and will eventually expire thus terminating the transaction

    2. If data matches, proposal is approved. Proceed to next step

  10. Transaction object containing a list of SONs expected to sign is created and published to the sidechain. List of SONs will be created based on list of active SONs

  11. Expected SON signers initiate parallel processing of transaction. Offline SONs will not participate in signing and only the online SONs (regardless of status) will sign the transaction

  12. Sign transaction

    1. Each signing SON adds its signature

    2. Each signing SON is added to list of received signatures

    3. Operation evaluator checks signatures to determine if latest signature is the last signature required to complete transaction signing

      1. If no, repeat this step after each SON's signature

      2. If yes, mark transaction object as 'Completed' (helper field complete = true)

  13. Scheduled SON detects completed transaction object

  14. Transaction is converted to a readable format and sent to Hive network

  15. User receives HIVE amount

  16. Withdrawal is marked as processed

5. Context

To facilitate conversion of Peerplays tokens into Hive, SON must include an event listener and an event handler mechanisms to identify specific types of transactions and handle them accordingly. Proposed approach uses multi-signature Primary Wallet controlled by SON network, holding all the funds. All transfers are made to and from this multi-signature wallet.

6. Flow Diagram

7. Requirements

Refer to Hive-SON Functional Specifications - Hive Deposit Handling for wallet information

NOTE: Current deposit address implementation is Timelocked-one-or-weighted-multisig for BTC-SON.

7.1 Listener

SON must include a Hive event listener which monitors a designated Hive address registered as a sidechain user address for withdrawals specifically, listener uses Hive node interface for monitoring changes in the block changes.

Listener must be able to recognize a change that signifies a withdrawal event and capture the following data associated with each transaction of this type:

  • Transaction unique identifier

  • Transfer operation's source address

  • Transfer operation's target address

  • Transfer amount

7.2 Handler

SON must include a Hive event handler which uses information supplied by the Listener to perform a specific operation that's based on transaction type submitted by listener. When handler receives notification of Withdrawal transaction from the Listener, sidechain_event_data must be received and passed to sidechain_event_data_received. Received sidechain event data must then be used to create proposal for a withdrawal descriptor object son_wallet_withdrawal_object.

System must then create a SON Wallet Deposit Object, which upon creation will be processed by all available SONs to verify its data. To verify object, system must check local data of each SON against object data on the side chain. Object must be deemed valid when its data is confirmed, and rejected when its data cannot be confirmed. Transaction terminates if object data is not confirmed during this check.

Successful object verification results in issuance of transaction create proposal that is based on confirmed object and includes some of its data (specifically, a reference to the object). Created sidechain transaction object must contain reference to the sidechain where it should be processed, reference to the object it is created for, sidechain transaction body, list of expected signers, list of received signatures, and the helper fields for calculating signature weights.

This proposal must be verified by SONs, which is performed by verifying referred object against locally recreated transaction data. If data does not match, proposal will be deleted from proposal list and transaction won't be completed. If data matches, system must approve the proposal. Approved proposals must result in object being published on the chain.

When the object is published on the chain, SONs specified on the list of expected signers must begin processing it in parallel. Note that SONs specified as signers must sign the transaction as long as they are online, disregarding their status (thus SON in any status must sign the transaction). Once enough signatures hve been collected, transaction is marked as 'Completed'.

When scheduled SON detects that a sidechain transaction object has been completed, it must collect all data from the sidechain transaction object, compile it, convert to a format that is ready for transmission to Hive network, and send this transaction to the Hive network.

SON must start conversion of withdrawal amount from Peerplays tokens into Hive following withdrawal confirmation. Conversion operation must calculate pHIVE to HIVE conversion using 1:1 rate. Conversion is completed by sending funds from Hive address (sidechain user address for withdrawals) to primary wallet (Hive multisig address).

User will receive Hive corresponding to amount of converted pHIVE. Lastly, scheduled SON must mark son_wallet_withdrawal_object as processed

7.3 Refunds

In some cases a transaction will not be processed by SONs (such as when active SONs threshold is not met), which will cause funds to wait until required number of active SONs become available. System must allow users to initiate refunds of their transactions.

Refund scenario must adhere to same rules as regular Hive transaction:

  1. User needs transaction id for the transaction they wish to refund

  2. User creates another transaction using transaction id of transaction they want to refund to move funds to their own address

  3. User signs the transaction using a private key that matches the public key he provided in sidechain address mapping

  4. Transaction is pushed to Hive network and user is refunded once transaction is processed

7.4 Deposit Address - One-or-weighted-multisig

This deposit address implementation type allows to send funds from this address with 2/3 weights of SON votes (like in Primary Wallet) or with single user signature. To create such address we need:

1) user public key

2) all SONs public keys

3) every SON weight

When funds are being sent from this address, system must first check if user signature is correct. When signature is correct, system completes the transaction. Otherwise, when signature is incorrect, system checks for 2/3 weights of SON votes to complete the transaction.

Note: This is the current implementation of the Deposit address for BTC-SON.

This address type is implemented by HIVE_one_or_weighted_multisig_address class.

8. Glossary

pHIVE​ is a Peerplays Blockchain Asset, which represents users' balances in Hive on Peerplays blockchain. Having a balance of 1 pHIVE would mean having it backed by the same amount of Hive on a Witness-controlled Multisig Wallet. New pHIVE are NOT ISSUED by OWNER with ​issue ​operation. New pHIVE are issued strictly in relation with ​Deposit​ operations.

pHBD, like pHIVE, is a Peerplays Blockchain Asset which represents a users' HBD balance on the Peerplays blockchain. HBD (Hive Backed Dollar) is a stable-coin on the Hive network that aims to be pegged to the United States Dollar. So 1 HBD should equal 1 USD.

PW (Primary Wallet) ​is the main Multisig Hive Wallet.

Multi-signature (multisig) refers to requiring more than one key to authorize a Hive transaction. It is generally used to divide up responsibility for possession of Hive.

Supporting Information

PreviousHIVE Deposit HandlingNextPeerplays DEX Development

Last updated 3 years ago

Was this helpful?

for creating a Hive node with the lowest possible required resources to support getting transactions.

to stream and detect transactions on the Hive blockchain.

for Hive transactions (with multisig).

for information on Hive multisig accounts.

for a list of Broadcast operations available in the APIs.

Hive Node - Get Transaction Node
Hive - Stream Blockchain Transactions
How to serialize and sign Hive transactions using Javascript
Using Multisignature Accounts
Broadcast Ops
3KB
hive-withdrawal.xml
HIVE Withdrawal XML