Include Cloudcoin in an Exchange

From CloudCoin Wiki
Jump to: navigation, search

Step 1: Create a Skyvault Account

NOTE: CloudCoin Developers are happy to walk you through the process of integrating CloudCoin onto your exchange including spending weeks over Skype helping you set things up. We estimate that it should take no more than one developer two weeks to implement.

SkyVault is a virtual bank that allows you to store, send, receive and transfer CloudCoins. Each Skyvault account has an address. A sample address would be 'Sean.CloudCoin.global', 'Bill.Skyvault.cc' or 'Payments.BigExchange.com'. You and your customers will need SkyVault Accounts to use as wallets.

  1. Go to https://Skyvault.cc
  2. Click on "Get Skyvault"
  3. Enter a temporary wallet Name for your account. If your exchange is called Foo, you would choose "Foo.Skyvault.cc" as your wallet name and Skyvault Address.
  4. Click the "GET SKYVAULT" button. You will then receive a virtual Skyvault debit card as a PNG. Click on the "DOWNLOAD YOUR SKYVAULT DEBIT CARD" button to download it. Keep this PNG safe. You will need to have it on your web server.
  5. Look at the IP address on the back of the Debit Card. This translates to the decimal serial number of your Skyvault Account. You will need this in the next step.

Step 2. Add Some DNS Records To Your DNS Zone

You will create DNS records so that people can figure out your Skyvault address and find your webhook. This allows them to send you payments and allows them to tell you in real time that their payment was sent.

Example:

cloudcoin.mydomain.com. IN	A	1.63.140.196
cloudcoin.mydomain.com. IN     TXT  "https://host.mydomain.com/verify_payment.php"

1. Create an 'A' record on your DNS server.

  • The type will be 'A',
  • The Name will be 'cloudcoin'
  • The IPv4 Address will be the number on the back of your Skyvault debit card.
  • The TTL with be 'Auto'.*
  • Make sure you do not proxy this 'A' record but use DNS only (only applicable if your DNS supports proxy. Most do not).

2. Create a TXT record calle 'cloudcoin' on your DNS server.

NOTE: The client will send CloudCoins to your account and then tell your server that the coins have been sent. The TXT record allows the user to find your webhook.

3. Test that your DNS records are working by going to a command prompt (Windows) and typing:

nslookup cloudcoin.youdomain.com
where you replace "yourdomain.com" with the name of your domain. You should receive the IP address that is on the back of your Skyvault Debit card. Then do

nslookup set q=TXT cloudcoin.yourdomain.com

. You should see the url of your webhook page at the bottom of the results.

Step 3. Install SkyVault Connect on your Web Server

1. Download the latest version of the skyvault_connect binary https://cloudcoinconsortium.com/zip/skyvault_connect.zip

2. Install it to the bin directory and give it exec permissions

# cp skyvault_connect /usr/local/bin
# chmod +x /usr/local/bin/skyvault_connect

3. Impersonate a web-user on your server (e.g. apache, nginx, www, www-data) and define the home directory (e.g. /var/www).

# mkdir -p /var/www/cloudcoin_manager
# chown www-data:www-data /var/www/cloudcoin_manager
# su -m www-data

4. Run the program and make sure the output ends with a json string

$ /usr/local/bin/skyvault_connect -home /var/www -debug -cli

RESULTS: 
{"code":4189,"message":"Command is missing","details":null}

5. Put your Skyvault debit card png file in to the SkyWallets folder (You got this when you created the account)

$ mkdir /var/www/cloudcoin_manager/SkyWallets/sw.skyvault.cc
$ cp sw.skyvault.cc.png /var/www/cloudcoin_manager/SkyWallets/sw.skyvault.cc/

6. Execute the SkyVault Connect's 'balance' command to make sure the program recognized the Debit Card Account.

$ /usr/local/bin/skyvault_connect -cli skybalance sw.skyvault.cc | jq '.balance'

RESPONSE: 
$ 0

Step 4. Tell Your Customers How To Send You CloudCoins

There are three ways to tell your customers how to send you CloudCoins:

  • 1. Link to the Skyvault.cc payment page.

Your customers need to know your Skyvault address. They also need to know their UserID so they can tell your servers that they made a payment. Their userID is information that you use to identify your customers. This could be an account number, GUID, username, email address, etc. We call this user information "meta" because you may submit a base64 code with lots of information about the user including their name, email, guid, account number and any other information that you would like your client to pass on to your webhook page.

https://skyvault.cc/payment?receiver_address=cloudcoin.exchange.net&amount=100&memo=d4ef39ab1fd746b8aa478e65982952d3

We can make a custom page for you like this:

https://skyvault.cc/bitmart?receiver_address=cloudcoin.exchange.net&amount=100&memo=d4ef39ab1fd746b8aa478e65982952d3

These HTTP GET variables will be used to populate the web form on the Skyvault site.

Merchant Address: Your Skyvault account. It must start with "cloudcoin" an be on your domain.

amount: (Optional) This pre populates the amount that the user will send in the send form. But they can put the amount there themselves or change the amount.

memo: This is information that you would like to include. Generally, you must put the user ID. This can be base64 to allow for lots of information. In that example above, we have the customer's GUID.


  • 2. QR code (This is just Step 1 except it is encoded in a QR for easy use with cell phones)
  • 3. written instructions

You would tell them:

  1. Go to SkyVault.cc and log in.
  2. Then go to Payments.
  3. Enter "cloudcoin.myexchange.net" for the Receiver's SkyVault Address
  4. Enter the Amount you wish to send.
  5. Enter your account number in the memo.
  6. Click "Send and Notify Merchant"
  7. Check to see if the funds are now in your exchange account.

We can setup special payment pages just of your exchange. Users can also use the desktop app called "Coin Manager" to make payments.

Step 5. Program your WebHook Page to Receive Coins

Your Web Hook page allows user software (such as the Skyvault ATM) to tell your server that you have received a payment. You must give your users their unique identifier so that they can pass it to you. That way, you will know who is ending you CloudCoins. See the videos below to see examples of users doing this on the Folgory exchange. https://www.youtube.com/watch?v=0mZ4lbJZL2s&t=85s

1. User software will find your hook page by looking up your TXT record for 'cloudcoin.yourdomain.com'.

2. User's software will use the HTTPS GET Method to call your page. Make sure you have HTTPS enable and that you have Access-Control-Allow-Origin: * configured on your web hook page.

      https://www.yourdomain.com/subfolder/hook.php?guid=4ba87b01d54f4c398a60c14c3e5d6b17&sender_address=john@doe.com
     
  • guid is a random GUID generated by the client that they will put in the transaction records of you Skyvault bank so you can look up their payment.
  • sender_address is the user who sent you the CloudCoins.

3. Program the web hook page. This depends on what your back-end programming language. We have programmers to help and sample pages. See #Sample PHP Web Hook Page below for the most common example.

4. Your hook page will need to call the CLI Skyvault_connect show_payment command with the necessary parameters to find the total that the user sent you.

5. You can test your web hook page by simply putting a GET command into your browser's address bar like this except use your own information: https://www.yourdomain.com/subfolder/hook.php?guid=4ba87b01d54f4c398a60c14c3e5d6b17

6. In order to validate a payment you will want to execute the SkyVault Connect's 'showpayment' command from a webserver code:

$ /usr/local/bin/skyvault_connect -home /var/www -cli showpayment faee40299b9afdb79bf381ec307f202f

RESPONSE: 
{
"guid":"6bf8f1b5c2696e3d8c3c623a9a4c1fa7",
"type":"transfer",
"amount":1,
"balance":0,
"time":"2022-04-18T10:23:37Z",
"memo":"memo=\"44ef39ab1fd746b8aa478e6598295244\"\nsender_address=\"zotest.skyvault.cc\"",
"owner":62144
}

Understand the response:

  • owner: This must be your account represented as a decimal.
  • guid: The transaction's id. A GUID for the transaction is generated by the client when they send coins.
  • amount: This is the verified number of CloudCoins that are part of the transaction. It will always be a GUID.
  • type: This must be set to "sent". You do not care if the user received some CloudCoins, they must have sent them to you.
  • time: Zulu time.
  • memo: The memo is a INI/TOML file that will contain the memo and sender_address parameters that you can parse out. The client sends the sender_address and the memo is that date you sent to the payment page that is basically echoed back. You can put anything in the memo that you like but this is typically the customer's id.

7. Validate that the owner is you. For example, if your Skvault address is sandy.skyvault.cc you will see that the address resolves to 1.0.242.192. Then we need to set the first byte to zero. So then 1.0.242.192 becomes 0.0.242.192. The you can put this into an IP to Decimal converter and see that it is 62144. The owner number must be your number.

8. In your Server code validate the amount and memo. Amount is the number of CloudCoins they sent you and must be equal to the expected amount of coins (if coins were expected). Memo - This is any other data that you would like to have the user include and may be something like user name or customer number.

9. There is a log file can be found in the home folder:

/var/www/cloudcoin_manager/main.log 

Step 6. Program Your Server to Send Coins to Customers when Cashing Out

1. In order to transfer coins from your SkyVault account to a customer's SkyVault account you will want to execute a 'skytransfer' command


/usr/local/bin/skyvault_connect -cli skytransfer <Your Account Name> <Customer Account Name> <amount to send> <memo>


Example:


$ /usr/local/bin/skyvault_connect -cli skytransfer sw.skyvault.cc user120.skyvault.cc 10 "Payment from Bitmart"

RESPONSE: 
{"TotalCoins":1,"TotalAuthentic":0,"TotalFracked":1,"TotalCounterfeit":0,"TotalLimbo":0,"Details":[],"Coins":[{"sn":230035,"pownstring":"fppppppppppppppppppfpppup","result":"Fracked"}]}

You need to check "TotalAuthentic" and "TotalFracked" number. Upon successful operation the sum of these values must be equal to the amount sent.

Step 7. Test The Whole Process

  1. Use the Skyvault ATM to create a second Skyvault account and deposit some CloudCoins in it. Or ask our developers to send CloudCoins to your newly created address.
  2. Using your new Skyvault, log into the ATM and click "Payment". Pay to "cloudcoin.YourDomain.com, Amount of coins that you want to test, memo/meta something like "Test".
  3. Check your webhook to see if it processed the request.
  4. Check the balance of your main Skyvault to see if the payment has been received.

Step 8. Setup a Maintenance Chronjob

With CloudCoin, it is up to the user to synchronize its wallet on all the clouds. This cron-job will synchronize once a day.

0 1 * * * /usr/local/bin/skyvault_connect -cli maintenance sw.skyvault.cc

The line above will launch at 1am at night

(!) The cron job must be launched as the same user as the one that calls 'skyvault_connect skytransfer' Check the main.log and make sure the cronjob is working after the setup.

Step 9. Check your Skyvault Balance (Optional)

1. You may want to check your Skyvault balance sometimes by calling the 'skybalance' command.

$ /usr/local/bin/skyvault_connect -cli skybalance sw.skyvault.cc

The response is a json string holding the balance value and other details about the walle

Sample PHP Web Hook Page

1. Put this PHP file (name it something like verify_payment.php) in your www directory:


<?php

$MySkyVaultDecimalAccount = "62144";
$endPoint = "http://127.0.0.1:8080/gateway/verifyData/foreign";

$skyvault_connect = "/usr/local/bin/skyvault_connect";
if (!file_exists($skyvault_connect))
  die("skyvault_connect not found");

if (!is_executable($skyvault_connect))
  die("skyvault_connect doesn't have exec permissions");

function verify_payment($guid, $amount, $skyvault) {
  global $skyvault_connect;
  global $MySkyVaultDecimalAccount;
  global $endPoint;

  $cmd =  "$skyvault_connect -cli showpayment $guid";

  // Exec the binary
  $json = exec($cmd, $outarray, $error_code);
  if ($error_code != 0) {
    die("Invalid response from skyvault_connect: $error_code, Output $json");
  }

  $arr = json_decode($json, true);
  if (!$arr) {
    die("Failed to decode json: $json");
  }

  if (!isset($arr['amount']) || !isset($arr['memo']) || !isset($arr['owner']) || !isset($arr['guid'])) {
    die("Corrupted response: $json");
  }

  if ($arr['amount'] != $amount) {
    die("Invalid amount in response: $json");
  }

  if ($arr['guid'] != $guid) {
    die("Invalid GUID in response: $json");
  }

  // Get a serial number from skyvault IP address (resolve the DNS name and compose the SN)
  if ($arr['owner'] != $MySkyVaultDecimalAccount) {
    die("Invalid Owner SN in response: $json");
  }

  send_request($endPoint ,$arr);
}

function send_request($url, $data) {
  $query = http_build_query($data); 

  $context = stream_context_create([
    'http' => [
      'method' => 'POST',
      'header' => 'Content-Type: application/x-www-form-urlencoded' . PHP_EOL,
      'content' => $query
    ]
  ]);

  $response = file_get_contents($url, false, $context);
  if ($response === false) {
    die("Failed to make request");
  }

  echo "Server responded\n";
  var_dump($response);
}

isset($_GET['merchant_address'])? $mywallet = $_GET['merchant_address']: $mywallet = '';
isset($_GET['amount'])? $amount = $_GET['amount']: $amount = 0;
isset($_GET['guid'])? $guid = $_GET['guid']: $guid = '';

if (!preg_match("/^[a-zA-Z0-9]{32}$/i", $guid)) {
  die("Invalid GUID parameter");
}

$amount = intval($amount);
if ($amount <= 0) {
  die("Invalid Amount parameter");
}

if (!filter_var(gethostbyname($mywallet), FILTER_VALIDATE_IP)) {
  die("Invalid MerchantSkyvault");
}

verify_payment($guid, $amount, $mywallet);
?>

2. Pick up a domain name that will be used as your Skyvault ID (E.g. myskywallet.mydomain.com) Set up two DNS records for this domain

A must point to the IP address of your previously registered mymerchant.skyvault.cc TXT record must go to the Full URL of verify_payment.php


3. Make sure DNS records are ready

4. Go to skywallet.cc and make a payment to myskywallet.mydomain.com

5. Check the Apache logs and make sure verify_payment.php is hit

6. Make sure ./file.txt is successfully created in the /var/www/raida directory

7. Change verify_payment.php script to meet your requirements

Videos That Show Examples of Depositing and Withdrawing from Existing Exchanges

1. How to deposit CloudCoins into the Foo Exchange: https://www.youtube.com/embed/0mZ4lbJZL2s

2. How to withdraw CloudCoins from the Foo Exchange: https://www.youtube.com/embed/zcuTyZL97bw