Examples: Fluent Transactions

This example demonstrates how to use the Quicksilver SDK's fluent Domain-Specific Language (DSL) to create, execute, and manage different types of transactions: basic payments, scheduled transactions, and streaming payments. It highlights the elegance and type-safety of the SDK's approach to programmable money, moving away from generic REST wrappers to active record models with intuitive methods.

The example covers:

• Initializing the Quicksilver client.
• Creating active Account models.
• Defining and executing a standard Payment transaction.
• Creating a Scheduled transaction and then canceling it.
• Setting up and initiating a Streaming transaction, simulating its progress, and refreshing its state.
• Utilizing the active Transaction model to access properties, check status, and retrieve costs.

Code Example

Explanation

1. Client Initialization:

   The example starts by initializing the QuicksilverClient. For local development and testing, env: 'sandbox' directs the SDK to a local sandbox instance of the Quicksilver Engine. Learn more in the Getting Started guide.

2. Account Creation:

   Two Account models, sender and recipient, are created using client.accounts.create(). These returned objects are active models, meaning they come with built-in methods for interaction.

3. Creating a Payment Transaction:

   A basic Payment transaction is created directly from the sender account object using sender.transaction(). This fluent interface allows for a readable and type-safe definition. The execute() method on the returned paymentTx active model processes the payment.

4. Inspecting Transaction State:

   The paymentTx object allows direct access to its underlying data (which mirrors the API response structure). Methods like getCost() (documented in API Reference: Transaction Model) provide insights into the transaction's financial impact.

5. Creating a Scheduled Transaction:

   A Scheduled transaction is defined, specifying a future schedule in its meta data. Later in the demo, scheduledTx.cancel() is called to demonstrate how to halt a transaction before its scheduled execution, illustrating the control offered by the active Transaction model.

6. Creating a Streaming Transaction:

   A Stream transaction is created, which will continuously transfer funds at a defined rate and rate_unit (e.g., 0.01 USD per_second). After execution, the streamingTx.refresh() method is used to fetch the latest state from the server, including the accumulated amount, without needing to re-fetch the entire transaction list.

This example clearly showcases the benefits of Quicksilver's fluent DSL and active models, enabling developers to define and manage complex monetary interactions with intuitive, type-safe code.