Welcome to Drachma! Drachma is a set of DAML Modules for interfacing between the Dwolla ACH Payment Platform and the DAML Ledger. It also includes a reference application which drives the DAML Templates. The App is implemented in Python using the rich Ledger API bindings by dazl, the DwollaV2 Python client for calling the Dwolla APIs and the Flask microframework for listening to Dwolla's Webhooks.
The DAML Dwolla Library assumes a single operator party and multiple user parties. Users send requests to the operator in order to create Customers, attach and verify Funding Sources and eventually issue ACH Transfers between them. The library is organized in a set of modules with distinct functionality that loosely mimics the Dwolla API resources. I strongly recommend that you become familiar with the Dwolla API before using this library. The modules are the following:
The Onboarding module is used for bootstrapping the DAML Ledger. The party which assumes the operator role creates an instance of the Operator template and invites users by exercising the Operator_InviteUser choice. The UserInvitation contract is accepted by the user party through the UserInvitation_Accept choice and the User role contract is created. The user can now request the creation of Verified or Unverified Dwolla API Customers.
The Customers module contains all the DAML templates necessary for the Customer creation workflows as well as the Customer template itself. Via the Customer contract, a party can exercise the Customer_UnverifiedFundingSourceRequest choice to create a Funding Source (which they can later verify), as well as send an ACH transfer to another customer through the Customer_SendFunds choice.
Currently Drachma supports the creation of an Unverified Customer (by creating an UnverifiedCustomerRequest contract) and that of a Personal verified Customer (VerifiedCustomerRequest contract). The type of information required for each customer type as well as the different state transitions of the creation workflow are dictated by the Dwolla API. You can refer to Dwolla's Customer types for more information.
A Dwolla funding source is used to hold ACH bank account information. Currently Drachma supports the creation of the bank funding source type which can be attached to a customer resource. The Funding Sources module includes the UnverifiedFundingSourceRequest template which asks the operator to create and attach a FundingSource to the requesting customer.
Upon creation, the FundingSource is unverified but can be verified through Dwolla's Micro-deposit verification workflow. To execute this workflow, the user initiates two micro deposits by exercising the FundingSource_InitiateMicroDeposits on the FundingSource contract. This will instruct Dwolla to transfer two random deposits of less than $0.10 to the bank account associated with the funding source. Once the micro deposits post to the customer's bank account, the user can verify the amounts by exercising the MicroDeposits_Verify choice on the MicroDeposits contract and create a FundingSourceVerificationRequest. The operator will finally process the request and if the amounts match the ones posted, a FundingSourceVerification contract will be created and provided as proof to verify the funding source.
For transferring funds between customer bank accounts, the Transfers module is used. A user who wants to send funds exercises the non-consuming Customer_SendFunds choice on the Customer contract and creates a ReceiveFundsRequest addressed to the receiver party. The sender specifies the source of the funds, the amount that they want to remit and optionally any clearing instructions for their bank as well as any metadata that will be present in the transfer. The receiver party can exercise ReceiveFundsRequest_AcceptFunds and specify their preferred bank account that will accept the funds along with any optional receiving-side clearing instructions. This Initiate and Accept DAML pattern leads to the creation of a TransferAgreement result contract which is subsequently validated for correct information through the TransferAgreement_Validate choice. Successful validation of the agreement creates a TransferRequest which in turn instructs the operator to call the Dwolla API and initiate a transfer. Finally a Transfer contract is created which holds the details of the fund transfer. This contract bears the signatures of all three parties (sender, receiver and operator) and its status gets updated by the operator via Dwolla's webhooks.
This is a helper module specifying the various data types and statuses allowed in the Dwolla resources as well as the functions that validate them.
To run Drachma, the DAML SDK must be installed on your system. Click here for the official installation instructions. You must also have Python 3.6 or higher and PIP.
git clone git@github.com:liakakos/drachma.git
cd drachma
pip install -r src/python/requirements.txt
If you don't have access to the Dwolla API you can sign up here and use their Sandbox environment before you decide to go to production.
For the DAML sandbox to run, you first need to compile the DAML Dwolla Library to a dar. To do this run
daml build -o target/daml/drachma.dar
from the parent drachma directory. After the dar is built, run the sandbox by issuing
daml sandbox target/daml/drachma.dar
At a minimum the Operator needs the Dwolla App Key, App Secret and the Operator party name. Open another terminal window and run src/python/operator.py. Use --help for more information on its configuration.
The navigator is a web app shipped with the DAML SDK. It allows you to view DAML contracts and exercise choices acting as any party you choose. On yet another terminal tab, navigate to the parent drachma directory and run:
daml navigator server
You are now ready to create the Operator role contract invite users and start using the Dwolla ACH Payment Platform!
As the License states I assume no liability for any damages or losses arising from the use of this Work. Please proceed at your own risk!