From 86554c4945de3d5bb761acfad15bd0a79b42bd8d Mon Sep 17 00:00:00 2001 From: Trent Nelson Date: Wed, 16 Sep 2020 20:34:43 -0600 Subject: [PATCH] Docs: Add SPL Token exchange integration (bp #12303) --- docs/src/integrations/exchange.md | 143 ++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) diff --git a/docs/src/integrations/exchange.md b/docs/src/integrations/exchange.md index 811748b5b14e50..b6aa93f2290922 100644 --- a/docs/src/integrations/exchange.md +++ b/docs/src/integrations/exchange.md @@ -486,6 +486,149 @@ public class PubkeyValidator } ``` +## Supporting the SPL Token Standard + +[SPL Token](https://spl.solana.com/token) is the standard for wrapped/synthetic +token creation and exchange on the Solana blockchain. + +The SPL Token workflow is similar to that of native SOL tokens, but there are a +few differences which will be discussed in this section. + +### Token Mints + +Each *type* of SPL Token is declared by creating a *mint* account. This account +stores metadata describing token features like the supply, number of decimals, and +various authorities with control over the mint. Each SPL Token account references +its associated mint and may only interact with SPL Tokens of that type. + +### Installing the `spl-token` CLI Tool + +SPL Token accounts are queried and modified using the `spl-token` command line +utility. The examples provided in this section depend upon having it installed +on the local system. + +`spl-token` is distributed from Rust [crates.io](https://crates.io) via the Rust +`cargo` command line utility. The latest version of `cargo` can be installed +using a handy one-liner for your platform at [rustup.rs](https://rustup.rs). Once +`cargo` is installed, `spl-token` can be obtained with the following command: + +``` +cargo install spl-token-cli +``` + +You can then check the installed version to verify + +``` +spl-token --version +``` + +Which should result in something like + +```text +spl-token-cli 2.0.1 +``` + +### Account Creation + +SPL Token accounts carry additional requirements that native System Program +accounts do not: + +1. SPL Token accounts are not implicitly created, so must be created explicitly +before an SPL Token balance can be deposited +1. SPL Token accounts must remain [rent-exempt](https://docs.solana.com/apps/rent#rent-exemption) +for the duration of their existence and therefore require a small amount of +native SOL tokens be deposited at account creation. For SPL Token v2 accounts, +this amount is 0.00203928 SOL (2,039,280 lamports). + +#### Command Line +To create an SPL Token account with the following properties: +1. At a random address +1. Associated with the given mint +1. Owned by the funding account's keypair + +``` +spl-token create-account +``` + +#### Example +``` +$ spl-token create-account AkUFCWTXb3w9nY2n6SFJvBV6VwvFUCe4KBMCcgLsa2ir +Creating account 6VzWGL51jLebvnDifvcuEDec17sK6Wupi4gYhm5RzfkV +Signature: 4JsqZEPra2eDTHtHpB4FMWSfk3UgcCVmkKkP7zESZeMrKmFFkDkNd91pKP3vPVVZZPiu5XxyJwS73Vi5WsZL88D7 +``` + +### Checking an Account's Balance + +#### Command Line +``` +spl-token balance +``` + +#### Example +``` +$ solana balance 6VzWGL51jLebvnDifvcuEDec17sK6Wupi4gYhm5RzfkV +0 +``` + +### Token Transfers + +For SPL Token transfers to succeed, a few prerequisite conditions must be met: +1. The recipient account must exist before the transfer is executed. As described +in [account creation](#account-creation), SPL Token accounts are *not* explicitly +created. +1. Both the sender and recipient accounts must belong to the same mint. SPL Token +accounts can only hold one type of SPL token. + +#### Command Line +``` +spl-token transfer +``` + +#### Example +``` +$ spl-token transfer 6B199xxzw3PkAm25hGJpjj3Wj3WNYNHzDAnt1tEqg5BN 1 6VzWGL51jLebvnDifvcuEDec17sK6Wupi4gYhm5RzfkV +Transfer 1 tokens + Sender: 6B199xxzw3PkAm25hGJpjj3Wj3WNYNHzDAnt1tEqg5BN + Recipient: 6VzWGL51jLebvnDifvcuEDec17sK6Wupi4gYhm5RzfkV +Signature: 3R6tsog17QM8KfzbcbdP4aoMfwgo6hBggJDVy7dZPVmH2xbCWjEj31JKD53NzMrf25ChFjY7Uv2dfCDq4mGFFyAj +``` + +### Depositing +Since each `(user, mint)` pair requires a separate account on chain, it is +recommended that an exchange create batches of token accounts in advance and assign them +to users on request. These accounts should all be owned by exchange-controlled +keypairs. + +Monitoring for deposit transactions should follow the [block polling](#poll-for-blocks) +method described above. Each new block should be scanned for successful transactions +issuing SPL Token [Transfer](https://github.com/solana-labs/solana-program-library/blob/096d3d4da51a8f63db5160b126ebc56b26346fc8/token/program/src/instruction.rs#L92) +or [Transfer2](https://github.com/solana-labs/solana-program-library/blob/096d3d4da51a8f63db5160b126ebc56b26346fc8/token/program/src/instruction.rs#L252) +instructions referencing user accounts, then querying the +[token account balance](https://docs.solana.com/apps/jsonrpc-api#gettokenaccountbalance) +updates. + +[Considerations](https://github.com/solana-labs/solana/issues/12318) are being +made to exend the `preBalance` and `postBalance` transaction status metadata +fields to include SPL Token balance transfers. + +### Withdrawing +The withdrawal address a user provides must point to an initialized SPL Token account +of the correct mint. Before executing a withdrawal [transfer](#token-transfers), +it is recommended that the exchange check the address as +[described above](#validating-user-supplied-account-addresses-for-withdrawals) +as well as query the account to verify its existence and that it belongs to the +correct mint. + +### Other Considerations + +#### Freeze Authority +For regulatory compliance reasons, an SPL Token issuing entity may optionally +choose to hold "Freeze Authority" over all accounts created in association with + its mint. This allows them to [freeze](https://spl.solana.com/token#freezing-accounts) +the assets in a given account at will, rendering the account unusable until thawed. +If this feature is in use, the freeze authority's pubkey will be registered in +the SPL Token's mint account. + ## Testing the Integration Be sure to test your complete workflow on Solana devnet and testnet