| xip | title | description | author | status | created | last update |
|---|---|---|---|---|---|---|
1 |
Payment Cycle Standard |
A payment system standard for applications. |
Abdul Moiz (@abdulmoiz251), Chris Priest (@taxa-chris), Henry Zhang (@henrytaxa), TF Guo (@tf-taxa) |
Draft |
2022-03-29 |
2023-07-17 |
A standard for layer-1 transactions authorization and execution in applications using Taxa Tokens (TXT). Managing the whole process of deposits, token locks and token withdrawls.
This standard allows the implementation of payment cycle within smart contract (on-chain) and tService (off-chain). It provides functionality for:
- Depositing tokens to the smart contract.
- Commiting and locking tokens on behalf of public key returned from application (tService).
- Verifying counter-parties commit and lock-up status.
- After successfull execution of application's logic, money receiver parties (winners) will be able to unlock or withdraw tokens using signature provided by tService.
Some applications require multiple parties to deposit and lock tokens in order to perform certain actions or engage in a competion. For example a card game, where competitors will be required to deposit and lock tokens. And after the game is finished the winners can unlock their tokens and are free to withdraw the reward.
This XIP helps to standardize the interactions of this type of payment systems.
Note: XIP-1 requires the existence of at least 1 counter-party with conflicting interests for every participant. To ensure that all participants lock-up enough tokens in the smart contract before the tService's main business logic starts, everyone needs to verify the information of their counter-parties on the blockchain. This makes XIP-1 particularly suitable for use in gaming applications.
Deposits amount of tokens to the smart contract and add to wallet's total balance.
The amount of tokens first need to be approved to smart contract before calling deposit function.
function deposit(uint256 amount) externalMaps publicKey to the callers address and locks the amount of tokens w.r.t. passed publicKey, with tokenLockDuration defined in contract. Also verifies signature to check if publicKey was generated from taxa tservice or not.
function commitAndJoin(bytes memory taxaPublicKey, uint256 amountToLock, bytes memory signature) externalAfter keys commited tokens and match found, startGame function is called. This function validates pubKeys, update the application(i.e. a game) information and start the tService's main business logics for the publicKeys provided. Signature contains signed keccak256 hash of concatenated pubkeys (with just initial 0x), by signingService's secret key.
function startGame(bytes[] memory pubKeys, bytes memory signature) externalUpdates results for given public key from signature signed by opponent's secret key. Signature contains signed keccak256 hash of concatenated results (without ",").
function submitResult(bytes memory opponentPublicKey, string[] memory results, bytes memory signature) externalAfter submitting result, player can claim tokens by passing taxaPublicKey.
function claimToken(bytes memory taxaPublicKey) externalIf a player was disconnected, he/she can claim tokens by passing taxaPublicKey after lock time.
function claimDisconnectedUserToken(bytes memory taxaPublicKey) externalWithdraws caller's unlocked tokens from contract.
function withdrawFromOwner() externalSet signingService public key.
function setSigningServicePublicKey(bytes memory _signingServicePubKey) external onlyOwnerVerify if peer has locked tokens for game.
function verifyPeer(bytes memory taxaPublicKey, uint amountToLock) public view returns(bool)Check if given taxaPublicKey already exists in game.
function checkIfPubKeyExists(bytes memory taxaPublicKey) public view returns(bool)Recovers and returns signer address from provided signature and message hash message using ecrecover(msgHash, v, r, s).
function recoverSigner(bytes32 message, bytes memory signature) private pure returns (address signerAddress)Notify the tService the current user's Ethereum wallet address and max amount of TXT allowed to spend in the payment cycle
eth_wallet: the current user's Ethereum wallet address which will deposit the payment into the smart contract max_allowance: the max amount of TXT the user authorized to spend in the payment cycle return: a new payment public key for the current Taxa user
List the Ethereum wallet addresses, and the associated payment public keys for the participants of the tSertice
return: a list of wallet and payment public keys binded with them. JSON format
Note: the tService will store 4 mappings in the tServices session: taxa_pubkey->eth_wallet eth_wallet->payment_public_key eth_wallet->payment_private_key eth_wallet->max_allowance
Confirms the on-chain status of all participants is correct - each user has deposited and locked an amount of TXT greater or equal to their max_alloance submitted to the tService. return: None
This function is used to join game by the player (off-chain) to proceed towards playing game with other joined player. return: None
This function provides data and details for the player's opponent. return: opponent's payment public key, wallet address, max allowance
After all players of the game have submitted their moves, this function will be used to get the results (with signature). The result and signature can then be submitted to the on-chain smart contract to claim the tokens.
return: result in string format, signature signed by opponent's secret key
Link to example code.
The content is licensed under CC0.