Add token docs (#158)

README.md

@@ -1,20 +1,25 @@
 [![Build status][travis-image]][travis-url]
 
-[travis-image]: https://travis-ci.org/solana-labs/solana-program-library.svg?branch=master
+[travis-image]:
+https://travis-ci.org/solana-labs/solana-program-library.svg?branch=master
 [travis-url]: https://travis-ci.org/solana-labs/solana-program-library
 
 # Solana Program Library
 
 The Solana Program Library (SPL) is a collection of on-chain programs targeting
-the [Sealevel parallel runtime](https://medium.com/solana-labs/sealevel-parallel-processing-thousands-of-smart-contracts-d814b378192).
-These programs are tested against Solana's implementation
-of Sealevel, solana-runtime, and deployed to its mainnet.  As others implement
-Sealevel, we will graciously accept patches to ensure the programs here are
-portable across all implementations.
+the [Sealevel parallel
+runtime](https://medium.com/solana-labs/sealevel-parallel-processing-thousands-of-smart-contracts-d814b378192).
+These programs are tested against Solana's implementation of Sealevel,
+solana-runtime, and deployed to its mainnet.  As others implement Sealevel, we
+will graciously accept patches to ensure the programs here are portable across
+all implementations.
+
+Full documentation is available at https://spl.solana.com
 
 ## Building
 
-These programs cannot be built directly via cargo and instead require the build scripts located in Solana's BPF-SDK.
+These programs cannot be built directly via cargo and instead require the build
+scripts located in Solana's BPF-SDK.
 
 Download or update the BPF-SDK by running:
 ```bash
@@ -43,7 +48,8 @@ Or:
 $ ./do.sh test <program>
 ```
 
-End-to-end testing may be performed via the per-project .js bindings.  See the [token program's js project](token/js) for an example.
+End-to-end testing may be performed via the per-project .js bindings.  See the
+[token program's js project](token/js) for an example.
 
 ## Clippy
 

docs/src/token.md

@@ -2,9 +2,130 @@
 title: Token Program
 ---
 
-An ERC20-like Token program on the Solana blockchain.
+A Fungible Token program on the Solana blockchain.
 
-The project comprises:
+This program provides an interface and implementation that third parties can
+utilize to create and use their tokens.
 
-* The Rust on-chain program
-* A JavaScript library to interact with the on-chain program
+## Background
+
+Solana's programming model and the definitions of the Solana terms used in this
+document are available at:
+- https://docs.solana.com/apps
+- https://docs.solana.com/terminology
+
+## Source
+
+The Token Program's source is available on
+[github](https://github.com/solana-labs/solana-program-library)
+
+## Interface
+
+The on-chain Token Program is written in Rust and available on crates.io as
+[spl-token](https://docs.rs/spl-token/1.0.2/spl_token/). The program's
+[instruction interface]
+documentation](https://docs.rs/spl-token/1.0.2/spl_token/instruction/enum.TokenInstruction.html)
+can also be found there.
+
+Auto-generated C bindings are also available for the on-chain Token Program and
+available
+[here](https://github.com/solana-labs/solana-program-library/blob/master/token/inc/token.h)
+
+[Javascript
+bindings](https://github.com/solana-labs/solana-program-library/blob/master/token/js/client/token.js)
+are available that support loading the Token Program on to a chain and issuing
+instructions.
+
+## Operational overview
+
+### Creating a new token type
+
+A new token type can be created by initializing a new Mint with the
+`InitializeMint` instruction.  The Mint is used to create or "Mint" new tokens,
+and these tokens are stored in Accounts.  A Mint is associated with each
+Account, which means that the total supply of a particular token type is equal
+to the balances of all the associated Accounts.
+
+A Mint can either be configured with a fixed-supply or non-fixed supply.  The
+total supply of a fixed-supply Mint is determined during initialization and
+deposited into a provided destination account.  A non-fixed-supply Mint also has
+an owner associated with it who has the authority to create new tokens in the
+future with the `MintTo` instruction.  Both types of Mints can `Burn` tokens to
+decrease supply.ß
+
+It's important to note that the `InitializeMint` instruction does not require
+the Solana account being initialized also be a signer.  The `InitializeMint`
+instruction should be atomically processed with the system instruction that
+creates the Solana account by including both instructions in the same
+transaction.
+
+### Creating accounts
+
+Accounts hold token balances and are created using the `InitializeAccount`
+instruction.  Each Account has an owner who must be present as a signer in some
+instructions.
+
+Balances can be transferred between Accounts using the `Transfer` instruction.
+The owner of the source Account must be present as a signer in the `Transfer`
+instruction.
+
+An Account's owner may transfer ownership of an account to another using the
+`SetOwner` instruction.
+
+It's important to note that the `InitializeAccount` instruction does not require
+the Solana account being initialized also be a signer.  The `InitializeAccount`
+instruction should be atomically processed with the system instruction that
+creates the Solana account by including both instructions in the same
+transaction.
+
+### Burning
+
+The `Burn` instruction decreases an Account's token balance without transferring
+to another Account, effectively removing the token from circulation permanently.
+
+### Authority delegation
+
+Account owners may delegate authority over some or all of their token balance
+using the `Approve` instruction.  Delegated authorities may transfer or burn up
+to the amount they've been delegated.  Authority delegation may be revoked by
+the Account's owner via the `Revoke` instruction.
+
+### Multisignatures
+
+M of N multisignatures are supported and can be used in place of Mint owners, or
+Account owners or delegates.  Multisignature owners or delegates must be
+initialized with the `InitializeMultisig` instruction. Initialization specifies
+the set of N public keys that are valid and the number M of those N that must be
+present as instruction signers for the authority to be legitimate.
+
+It's important to note that the `InitializeMultisig` instruction does not
+require the Solana account being initialized also be a signer.  The
+`InitializeMultisig` instruction should be atomically processed with the system
+instruction that creates the Solana account by including both instructions in
+the same transaction.
+
+### Wrapping SOL
+
+The Token Program can be used to wrap native SOL.  Doing so allows native SOL to
+be treated like any other Token program token type and can be useful when being
+called from other programs that interact with the Token Program's interface.
+
+Accounts containing wrapped SOL are associated with a specific Mint called the
+"Native Mint"  using the public key
+`So11111111111111111111111111111111111111111`.  
+
+These accounts have a few unique behaviors
+- `InitializeAccount` sets the balance of the initialized Account to the SOL
+  balance of the Solana account being initialized, resulting in a token balance
+  equal to the SOL balance.
+- Transfers to and from not only modify the token balance but also transfer an
+  equal amount of SOL from the source account to the destination account.
+- Burning is not supported
+- When closing an Account the balance may be non-zero.
+
+### Closing accounts
+
+An account may be closed using the `CloseAccount` instruction.  When closing an
+Account, all remaining SOL will be transferred to another Solana account
+(doesn't have to be associated with the Token Program).  Non-native accounts
+must have a balance of zero to be closed.

token/README.md

@@ -1,8 +1,10 @@
 # Token program
 
-An ERC20-like Token program on the Solana blockchain.
+A Fungible Token program on the Solana blockchain.
 
-The project comprises:
+This program provides an interface and implementation that third parties can
+utilize to create and use their tokens.
 
-* The Rust on-chain program
-* A JavaScript library to interact with the on-chain program
+Full documentation is available at https://spl.solana.com
+
+Javascript binding are available in the ./js directory

token/js/README.md

@@ -9,7 +9,7 @@ The Token JavaScript library comprises:
 ## Getting Started
 
 First fetch the npm dependencies, including `@solana/web3.js`, by running:
-```sh
+```bash
 $ npm install
 ```
 
@@ -34,11 +34,18 @@ Solana cluster logs are available with:
 $ npm run localnet:logs
 ```
 
-For more details on working with a local cluster, see the [full instructions](https://github.com/solana-labs/solana-web3.js#local-network).
+For more details on working with a local cluster, see the [full
+instructions](https://github.com/solana-labs/solana-web3.js#local-network).
+
+### Build the on-chain program
+
+```bash
+$ npm run build:program
+```
 
 ### Run the test client
 
-```sh
+```bash
 $ npm run start
 ```
 

token/js/package.json

@@ -14,6 +14,7 @@
     "flow": "flow",
     "flow:watch": "watch 'flow' . --wait=1 --ignoreDirectoryPattern=/doc/",
     "lint:watch": "watch 'npm run lint:fix' . --wait=1",
+    "build:program": "rm client/util/store/config.json; ../../do.sh build token",
     "cluster:localnet": "rm -f .env",
     "cluster:devnet": "cp cluster-devnet.env .env",
     "cluster:testnet": "cp cluster-testnet.env .env",