v.2.0.0
Marionette’s Payment Interface (PI) serves as the middleware connecting third-party financial services, including banks, payment processing services, liquidity providers, market makers, blockchains, and Marionette’s accounting engine. The Payment Interface simplifies interaction with these external sources by integrating with their individual APIs. It interprets inbound financial information to update Marionette’s internal ledger records. Similarly, when connecting to the API source, it retrieves updated information and communicates it back to the connected third-party services.
In our example, we review how PIs communicate with specifically with blockchain nodes. Marionette treats blockchains as an external third-party financial service (bank, payment gateway, payment processor, etc.), but with extended capabilities applicable to each individual node and its unique parameters.
Marionette’s Payment Interfaces request real-time updates from individual blockchain nodes and uses this data to update internal accounting ledger records, including end-user and system wallet addresses.
Marionette’s PIs are responsible for:
Transaction Execution:
- Facilitating currency transfers between addresses.
Transaction Handling:
- Receiving transactions from blockchains (banks, etc.).
- Processing the received data.
- Sending transaction information to the backend for further processing.
Data Integrity and Accuracy:
- Ensuring correctness and completeness of recipient data.
Proxy Wallet Management:
- Generating new addresses for users’ proxy wallets (when users make deposits to proxy wallets).
Balance Management:
- Accepting deposits.
- Updating user balances for addresses associated with the platform.
Backend interaction with paymentInterface goes through following backend services:
paymentGateway - main tasks
blockchainRegistry - in the framework of saving the data of the system's hot wallet and reading blocks
Therefore, when the payment interface is starting, it must register with the relevant services
Examples:
await broker.call('blockchainRegistry.registerBlockchain', {
id: config.id,
title: config.title,
subtitle: config.subtitle,
description: config.subtitle,
explorer_address: config.explorer_address,
explorer_transaction: config.explorer_transaction,
minConfirmations: config.minConfirmations,
chainId: config.chainId
});
await broker.call('paymentGateway.registerPaymentInterface', {
id: config.id,
title: config.title,
subtitle: config.subtitle,
invoiceBased: false,
multiCurrency: true,
isCollectabled: true
});
Carrying out transactions for the transfer of currency from address to address.
When the backend calls for transactions:
when a user requests a withdrawal
when transferring currency from a hot wallet to a user's proxy wallet. Happens before collection tokens to hot system wallet when there is not enough coin for transaction commission.
when collecting currency from the user's proxy wallet
Action: transfer
Required parameters:
addressFrom - sender address
address - recipient's address
amount - amount to transfer
Optional parameters (particularly evm-based blockchains):
privateKey - for sender address
contractAddress - when sending a token
gasPrice - if it is necessary that the token transfer transaction be carried out with a fixed gasPrice in advance
subtractFeeFromAmount - specified only for transfers in the base currency of the blockchain. if the value is true, then the amount minus the blockchain fee should be sent to the recipient's address.
If transaction succeed should be returned JSON with fields:
txid - transaction hash
transferAmount - amount which received on recipient’s address
fee - transaction commission
feeCurrency - commission’s currency id
If transaction failed should be returned JSON with field:
error - error text which should be written to description of operation.
Receiving transactions from blockchain (bank, etc.), processing the received data and sending information about transactions to the backend for following processing
Operations must be parsed sequentially block by block, it is also possible to move parsed blocks back and forth from the admin panel.
How it must be work:
get the block
select from it transactions related to the currencies that are registered in this payment interface
convert the data to JSON with the following fields and call action “paymentGateway.processTransaction”:
txid - transaction hash
amount - transaction amount
paymentInterfaceId
currencyId
address
addressFrom
Informing and monitoring the correctness and completeness of recipient’s data
Actions: recipientSchema, initialDepositData, validateRecipient
recipientSchema
returns the JSON schema for the form to be filled in by the user
initialDepositData
returns JSON with fields:
address - how address would be show to users
encodedAddress - address as it is (frontend shows QR-Code based on this field)
redirectUrl - if frontend must be show redirect url (usually for fiat-based payment interfaces)
validateRecipient
Checks if the frontend received the recipient data correctly.
In the case of a blockchain:
turn the received text into JSON
find the address in it
check the address for validity in our blockchain
Generation of new addresses for proxy wallets of users. If users make deposits to proxy wallets
Action: getNewAddress
Generate new address for user’s proxy wallet and returns it (with secret for evm-based blockchains).
Receiving currency balance for address
Action: balance
Receive currency balance for address (if contractAddress does not exist - receive coin balance)
Parameters:
address - compulsory
contractAddress - optional