diff --git a/book/src/programs.md b/book/src/programs.md index da06cc59e2..7ad3797ca9 100644 --- a/book/src/programs.md +++ b/book/src/programs.md @@ -1,9 +1,9 @@ # Programming Model -A client interacts with a Solana cluster by sending it *transactions* with one -or more *instructions*. The Solana *runtime* passes those instructions to -user-contributed *programs*. An instruction might, for example, tell a program -to move *tokens* from one *account* to another or create an interactive +A client *app* interacts with a Solana cluster by sending it *transactions* +with one or more *instructions*. The Solana *runtime* passes those instructions +to user-contributed *programs*. An instruction might, for example, tell a +program to move *tokens* from one *account* to another or create an interactive contract that governs how tokens are moved. Instructions are executed atomically. If any instruction is invalid, any changes made within the transaction are discarded. @@ -64,3 +64,4 @@ account metadata and transaction signatures to verify that none of the access rules were violated. If a program violates an access rule, the runtime discards all account changes made by all instructions and marks the transaction as failed. + diff --git a/book/src/terminology.md b/book/src/terminology.md index cf4bcfd1ab..1e841167bc 100644 --- a/book/src/terminology.md +++ b/book/src/terminology.md @@ -10,6 +10,10 @@ architecture. A persistent file addressed by [public key](#public-key) and with [lamports](#lamport) tracking its lifetime. +#### app + +A front-end application that interacts with a Solana cluster. + #### block A contiguous set of [entries](#entry) on the ledger covered by a [vote](#ledger-vote). @@ -37,6 +41,11 @@ A gossip network connecting all [nodes](#node) of a [cluster](#cluster). A multicast network used to efficiently validate [entries](#entry) and gain consensus. +#### drone + +An off-chain service that acts as a custodian for a user's private key. It +typically serves to validate and sign transactions. + #### entry An entry on the [ledger](#ledger) either a [tick](#tick) or a [transactions diff --git a/book/src/tictactoe.md b/book/src/tictactoe.md index e568e44b1e..89a41e4733 100644 --- a/book/src/tictactoe.md +++ b/book/src/tictactoe.md @@ -1,95 +1,31 @@ -# Example program: Tic-Tac-Toe +# Example app: Tic-Tac-Toe -This project demonstrates how to use the [Solana Javascript API](https://github.com/solana-labs/solana-web3.js) -to build, deploy, and interact with programs on the Solana blockchain, implementing an interactive tic-tac-toe game between two users. -To see the final product, go to https://solana-example-tictactoe.herokuapp.com/ and wait for another player to join. -(Simply direct a second browser window to the web app to play against yourself.) +[Click here to play +Tic-Tac-Toe](https://solana-example-tictactoe.herokuapp.com/) on the Solana +testnet. Open the link and wait for another player to join, or open the link +in a second browser tab to play against yourself. You will see that every +move a player makes stores a transaction on the ledger. -The project comprises: -* The on-chain Tic-Tac-Toe program, a BPF program written in C: `program-bpf/` -* Easy program build and deployment using the `@solana/web3.js` library -* Command-line and web front-end: `src/` - -## Getting Started +## Build and run Tic-Tac-Toe locally First fetch the latest release of the example code: -```sh -$ git clone https://github.com/solana-labs/example-tictactoe.git -$ cd example-tictactoe -$ TAG=$(git describe --tags $(git rev-list --tags --max-count=1)) -$ git checkout $TAG -``` +```sh $ git clone https://github.com/solana-labs/example-tictactoe.git $ cd +example-tictactoe $ TAG=$(git describe --tags $(git rev-list --tags +--max-count=1)) $ git checkout $TAG ``` -Then fetch the npm dependencies, including `@solana/web3.js`, by running: +Next, follow the steps in the git repository's +[README](https://github.com/solana-labs/example-tictactoe/blob/master/README.md). -```sh -$ npm install -``` -### Select a Network -The example connects to a local Solana network by default. - -To start a local Solana network run: -```bash -$ npx solana-localnet update -$ npm run localnet:up -``` - -Solana network logs are available with: -```bash -$ npx solana-localnet logs -f -``` - -For more details on working with a local network, see the [full instructions](https://github.com/solana-labs/solana-web3.js#local-network). - -Alternatively to connect to the public testnet, `export LIVE=1` in your environment before running a front-end. - -### Build the BPF C program -```sh -$ V=1 make -C program-bpf -``` -or -```sh -$ npm run build:bpf -``` - -Compiled files can be found in `dist/program`. Compiler settings are configured in the [Solana SDK](https://github.com/solana-labs/solana/tree/master/sdk/bpf/bpf.mk) - -### Run the Command-Line Front End -After building the program, - -```sh -$ npm run start -``` - -This script uses the Solana Javascript API `BpfLoader` to deploy your Tic-Tac-Toe program to the blockchain. -Once the deploy transaction is confirmed on the chain, the script calls the program to instantiate a new dashboard -to track your open and completed games (`findDashboard`), and starts a new game (`dashboard.startGame`), waiting for an opponent. - -To play the game, open a second terminal and again run the `npm run start` script. - -To see the program or game state on the blockchain, send a `getAccountInfo` [JSON-RPC request](https://solana-labs.github.io/solana/jsonrpc-api.html#getaccountinfo) to the cluster, using the id printed by the script, eg.: -* `Dashboard programId: HFA4x4oZKWeGcRVbUYaCHM59i5AFfP3nCfc4NkrBvVtP` -* `Dashboard: HmAEDrGpsRK2PkR51E9mQrKQG7Qa3iyv4SvZND9uEkdR` -* `Advertising our game (Gx1kjBieYgaPgDhaovzvvZapUTg5Mz6nhXTLWSQJpNMv)` - -### Run the WebApp Front End -After building the program, - -```sh -$ npm run dev -``` - -This script deploys the program to the blockchain, and also boots up a local webserver -for game play. - -To instantiate a dashboard and game, open your browser to http://localhost:8080/. - -## Customizing the Program -To customize Tic-Tac-Toe, make changes to the program in `program-bpf/src` and rebuild. -Now when you run `npm run start`, you should see your changes. - -To deploy a program with a different name, edit `src/server/config.js`. +## Getting tokens to users +You may have noticed you interacted with the Solana cluster without first +needing to aquire tokens to pay transaction fees. Under the hood, the web +app creates a new ephemeral identity and sends a request to an off-chain +service for a signed transation authorizes a user to start a new game. +The service is called a *drone*. When the app sends the signed transaction +to the Solana cluster, the drone's tokens are spent to pay the transaction +fee and start the game. In a real world app, the drone might request the user +watch an ad or pass a CAPTCHA before signing over its tokens.