|
| 1 | +# Payments Pallet |
| 2 | + |
| 3 | +This pallet allows users to create secure reversible payments that keep funds locked in a merchant's account until the off-chain goods are confirmed to be received. Each payment gets assigned its own *judge* that can help resolve any disputes between the two parties. |
| 4 | + |
| 5 | +## Terminology |
| 6 | + |
| 7 | +- Created: A payment has been created and the amount arrived to its destination but it's locked. |
| 8 | +- NeedsReview: The payment has bee disputed and is awaiting settlement by a judge. |
| 9 | +- IncentivePercentage: A small share of the payment amount is held in escrow until a payment is completed/cancelled. The Incentive Percentage represents this value. |
| 10 | +- Resolver Account: A resolver account is assigned to every payment created, this account has the privilege to cancel/release a payment that has been disputed. |
| 11 | +- Remark: The pallet allows to create payments by optionally providing some extra(limited) amount of bytes, this is reffered to as Remark. This can be used by a marketplace to seperate/tag payments. |
| 12 | +- CancelBufferBlockLength: This is the time window where the recipient can dispute a cancellation request from the payment creator. |
| 13 | + |
| 14 | +## Interface |
| 15 | + |
| 16 | +#### Events |
| 17 | + |
| 18 | +- `PaymentCreated { from: T::AccountId, asset: AssetIdOf<T>, amount: BalanceOf<T> },`, |
| 19 | +- `PaymentReleased { from: T::AccountId, to: T::AccountId }`, |
| 20 | +- `PaymentCancelled { from: T::AccountId, to: T::AccountId }`, |
| 21 | +- `PaymentCreatorRequestedRefund { from: T::AccountId, to: T::AccountId, expiry: T::BlockNumber}` |
| 22 | +- `PaymentRefundDisputed { from: T::AccountId, to: T::AccountId }` |
| 23 | +- `PaymentRequestCreated { from: T::AccountId, to: T::AccountId }` |
| 24 | +- `PaymentRequestCompleted { from: T::AccountId, to: T::AccountId }` |
| 25 | + |
| 26 | +#### Extrinsics |
| 27 | + |
| 28 | +- `pay` - Create an payment for the given currencyid/amount |
| 29 | +- `pay_with_remark` - Create a payment with a remark, can be used to tag payments |
| 30 | +- `release` - Release the payment amount to recipent |
| 31 | +- `cancel` - Allows the recipient to cancel the payment and release the payment amount to creator |
| 32 | +- `resolve_release_payment` - Allows assigned judge to release a payment |
| 33 | +- `resolve_cancel_payment` - Allows assigned judge to cancel a payment |
| 34 | +- `request_refund` - Allows the creator of the payment to trigger cancel with a buffer time. |
| 35 | +- `claim_refund` - Allows the creator to claim payment refund after buffer time |
| 36 | +- `dispute_refund` - Allows the recipient to dispute the payment request of sender |
| 37 | +- `request_payment` - Create a payment that can be completed by the sender using the `accept_and_pay` extrinsic. |
| 38 | +- `accept_and_pay` - Allows the sender to fulfill a payment request created by a recipient |
| 39 | + |
| 40 | +## Implementations |
| 41 | + |
| 42 | +The RatesProvider module provides implementations for the following traits. |
| 43 | +- [`PaymentHandler`](./src/types.rs) |
| 44 | + |
| 45 | +## Types |
| 46 | + |
| 47 | +The `PaymentDetail` struct stores information about the payment/escrow. A "payment" in virto network is similar to an escrow, it is used to guarantee proof of funds and can be released once an agreed upon condition has reached between the payment creator and recipient. The payment lifecycle is tracked using the state field. |
| 48 | + |
| 49 | +```rust |
| 50 | +pub struct PaymentDetail<T: pallet::Config> { |
| 51 | + /// type of asset used for payment |
| 52 | + pub asset: AssetIdOf<T>, |
| 53 | + /// amount of asset used for payment |
| 54 | + pub amount: BalanceOf<T>, |
| 55 | + /// incentive amount that is credited to creator for resolving |
| 56 | + pub incentive_amount: BalanceOf<T>, |
| 57 | + /// enum to track payment lifecycle [Created, NeedsReview] |
| 58 | + pub state: PaymentState<T::BlockNumber>, |
| 59 | + /// account that can settle any disputes created in the payment |
| 60 | + pub resolver_account: T::AccountId, |
| 61 | + /// fee charged and recipient account details |
| 62 | + pub fee_detail: Option<(T::AccountId, BalanceOf<T>)>, |
| 63 | + /// remarks to give context to payment |
| 64 | + pub remark: Option<BoundedDataOf<T>>, |
| 65 | +} |
| 66 | +``` |
| 67 | + |
| 68 | +The `PaymentState` enum tracks the possible states that a payment can be in. When a payment is 'completed' or 'cancelled' it is removed from storage and hence not tracked by a state. |
| 69 | + |
| 70 | +```rust |
| 71 | +pub enum PaymentState<BlockNumber> { |
| 72 | + /// Amounts have been reserved and waiting for release/cancel |
| 73 | + Created, |
| 74 | + /// A judge needs to review and release manually |
| 75 | + NeedsReview, |
| 76 | + /// The user has requested refund and will be processed by `BlockNumber` |
| 77 | + RefundRequested(BlockNumber), |
| 78 | +} |
| 79 | +``` |
| 80 | + |
| 81 | +## GenesisConfig |
| 82 | + |
| 83 | +The rates_provider pallet does not depend on the `GenesisConfig` |
| 84 | + |
| 85 | +License: Apache-2.0 |
0 commit comments