PlaygroundBitpointBank

TODO: intro

The Application Client and Server

TODO: soon

Integrating the Bank API into your code

If you want to get "paid" with bitpoints for a service you provide on the Playground network, you can use an over-the-network API as follows:

1. Assume that your application has a client and a server. The client must prove to the server that it has paid for services
2. The client requests services
3. The server informs the client of a cost, an account name, and a transaction ID
4. The client contacts the bank and transfers bitpoints to the named account (transaction ID in the memo)
5. The bank sends the client a signed receipt
6. The client presents the signed receipt to the server as proof of payment
7. Server verifies that the receipt is authentic and has the transaction ID in the memo

In this document, we will provide example source code for connecting to the bank, transferring money, and receiving a receipt. We will also describe how a server verifies a receipt. The other steps are standard networking communications and are not covered here.

Client Code: Bank Transfer

In this example, we assume that our client has been told by the server three things:

1. An amount
2. An account
3. A transaction ID

The client code to perform this operation can be processed as follows:

from OnlineBank import BankClientProtocol
async def transfer(amount, account, transactionID):
    bank_factory = lambda: BankClientProtocol(cert, login_name, password)
    bank_client = await playground.create_connection(bank_factory, bank_addr, bank_port)
    login_response = await bank_client.loginToServer()
    switch_response = await bank_client.switchAccount(my_account)
    transfer_response = await bank_client.transfer(account, amount, str(transactionID))
    return (transfer_response.receipt, transfer_response.receiptSignature)

This code is not complete, of course. when you write your code, make sure to:

1. Ensure that OnlineBank is in Playground's path.
2. Load the bank's cert from disk and have access to your own login name and password
3. Know your own account name
4. Know the bank's address and port

Server Code: Verify Transaction

Once the server receives the receipt and receipt signature from the bank, the receipt is verified in the following manner:

from BankCore import RSA_SIGNATURE_MAC
def validate(amount, account, transactionID, receipt, receiptSignature, cert):
    verifier = RSA_SIGNATURE_MAC(cert.public_key())
    try:
        verifier.verify(receiptSignature, SHA(receipt).digest())
    except AssertionError:
        # the receipt is forged
        return False
    receiptObj = pickle.loads(receipt)
    if receiptObj.memo() != str(transactionID):
        # memo mismatch. Wrong transaction ID
        return False
    if receiptObj.getTransactionAmount(account) != amount:
        # wrong amount
        return False
    return True

As with the client code, not all elements are shown. Make sure to verify that the receipt is from the bank before unpickling.