Exchange Guide for Exporting Peercoin Addresses Paired With User's NuShares Addresses

exportprocess.md

DOCUMENT STATUS: DRAFT

This document is going to cover a number of scenarios that can assist exchanges with setting up their own procedures for distributing Nu dividend payments to their users. Consider it a very rough draft at this time. Please include comments if you have specific scenarios you would like to see discussed.

Here are the details for how dividends work:

1. Dividends are not paid out on a set schedule, but are released when based on each dividend-paying custodian's proposal / performance / activity. For instance, if a trade goal is met, that may trigger a dividend payment.

2. A dividend address is a peercoin addresses that uniquely maps to one NSR address. By transforming the NSR address into a PPC address, it allows the private key to be exported from the Nu wallet to a Peercoin wallet.

Use Case

For ease of explanation, each user has a separate NSR address in the exchange's wallet. It is also assumed, for this example, that the exchange is running on a Linux-based system. Other OSs will work fine, but for the sake of these examples, the Linux default paths are used.

Initial State
The Exchange is actively running the Nu daemon (nud) and the Peercoin daemon (ppcoind or peerunityd), and each running on the best chain for each network, respectively. Each running daemon will have a configuration file (~/.nu/nu.conf and ~/.nu/ppcoin.conf) that has the rpcuser and rpcpassword parameters set.

Exporting Paired Peercoin Addresses

The Exchange writes a script that interacts with a running copy of the Nu daemon (nud). A sample shell script with a simple interaction:

#!/bin/bash
# START export of peercoin keys

PPCOIND=/path_to/ppcoind
NUD=/path_to/nud

# 1. unlock the exchange's Peercoin wallet, temporarily 
# ('600' seconds; 10 minutes is used here, but it 
# will depend on the number of keys being exported)
# if the RPC password contains special characters or spaces, 
# makes sure to wrap it in quotes
.$PPCOIND walletpassphrase "{rpcpassword}" 600

# 2. generate a file with a list of NSR addresses and their paired PPC address
# because the `getpeercoinaddresses` method only accepts one parameter
# you will want to iterate over the available accounts in the wallet and put the results
# into an array that is then piped to a temporary file to be read by the next function.
# there are lots of ways to do this, so pick the one that works best for you.

.$NUD getpeercoinaddresses "{account_name}"

# `getpeercoinaddresses` returns a JSON response that looks like this:
# { "NSRaddress1","PPCaddress1", "NSRaddress2","PPCaddress2" }

# 3. export peercoin address keys from Nu wallet to Peercoin wallet
.$NUD exportpeercoinkeys

# exportpeercoinkeys returns a JSON response that looks like this:
# { "exported": 4, "failed": 27 }

# keys listed as "exported" were successfully moved, and appear in the
# Peercoin debug.log file as 'AddToWallet {hash}';
# "failed" keys are those that have previously existed in the wallet,
# these attempts show up in Peercoin's debug.log as
# 'ThreadRPCServer method=importprivkey'.

# BR: I'm working on a way to identify which addresses were exported 
# and which failed using the hash of a successful import.

# 4. lock the peercoin wallet after keys have been exported
.$PPCOIND walletlock

# END export of peercoin keys

A Dividend Payment Is Made

Note: In almost all cases, the Exchange will be the recipient of peercoins sent to shareholder addresses and will not have anything to do with the dividend distribution process. If your use case is different, please contact the Nu Development team to discuss your specific need.

First, the full amount of Peercoins sent out by a custodian to satisfy a dividend payment need to be placed in the custodian's Peercoin wallet. This wallet is then unlocked (temporarily) to make it possible for the Nu client to interact with it via RPC.

When a custodian (or anyone, for that matter) makes a dividend payment to the Nu shareholders, they enter in the timestamp for when "ownership" of NSR should be calculated, and the amount of peercoins to be distributed.

Their client or daemon will generate a list of the "shareholders" (NSR addresses with a positive balance at the timestamp) and then divide the peercoin distribution amount proportionately amongst them. Once confirmed their Nu client will interact with their Peercoin wallet and generate a set of Peercoin output transactions to each of the Nu shareholder's NSR paired peercoin addresses.

A portion of these addresses will be the ones that were imported by the Exchange in the previous step.

Crediting Dividends To A User's Peercoin Balances (unique addresses)

For most exchanges, user balances aren't tied to a particular coin address (because they are "active" on the exchange). Exchanges will need to independently calculate a user's "live" balance at the time that a dividend payment is made to credit the balance appropriately.

If the Exchange maintains a unique NSR address for each user, it would be straight forward to map this NSR address to it's shared Peercoin address. When the dividend was paid, the funds would appear in the NSR holder's PPC balance on the Exchange.