WIP: contract-basics

main/guides/getting-started/contract-basics.md

@@ -1,11 +1,14 @@
 # Smart Contract Basics
 
-A contract is a module that exports a `start` function
+Let's see how to make a contract such as the one in [the
+basic dapp](./) in the previous section.
+
+A contract is a JavaScript module that exports a `start` function
 that defines the contract's API.
 
 <<< @/snippets/zoe/src/01-hello.js#start
 
-The API of this contract has a simple `greet` function:
+Let's start with a contract with a simple `greet` function:
 
 <<< @/snippets/zoe/src/01-hello.js#greet
 
@@ -23,7 +26,9 @@ Putting it all together:
 
 <<< @/snippets/zoe/src/01-hello.js#contract
 
-## Testing a contract
+## Using, testing a contract
+
+Let's use some tests to explore how a contract is used.
 
 Agoric contracts are typically tested
 using the [ava](https://github.com/avajs/ava) framework.
@@ -37,23 +42,14 @@ A test that the `greet` method works as expected looks like:
 
 <<< @/snippets/zoe/test/test-zoe-hello.js#test1
 
-Run it following `ava` conventions:
-
-```console
-$ yarn ava test/test-zoe-hello.js -m '*greet*'
-
-  ✔ contract greets by name
-  ─
-
-  1 test passed
-```
-
 ## State
 
 Contracts can use ordinary variables for state.
 
 <<< @/snippets/zoe/src/02-state.js#startfn
 
+Using `set` changes the results of the following call to `get`:
+
 <<< @/snippets/zoe/test/test-zoe-hello.js#test-state
 
 ::: tip Heap state is persistent
@@ -68,16 +64,32 @@ objects that last across upgrades (_durable objects_) later.
 
 ## Access Control with Objects
 
-We can limit the public API to read-only by omitting the `set()` method
+We can limit the `publicFacet` API to read-only by omitting the `set()` method.
 
 The `creatorFacet` is provided only to the caller who creates the contract instance.
 
 <<< @/snippets/zoe/src/03-access.js
 
+Trying to `set` using the `publicFacet` throws, but
+using the `creatorFacet` works:
+
 <<< @/snippets/zoe/test/test-zoe-hello.js#test-access
 
 Note that the `set()` method has no access check inside it.
 Access control is based on separation of powers between
 the `publicFacet`, which is expected to be shared widely,
 and the `creatorFacet`, which is closely held.
 _We'll discuss this [object capabilities](js-programming/hardened-js.html#object-capabilities-ocaps) approach more later._
+
+## Bundling for deployment
+
+Run it following `ava` conventions:
+
+```console
+$ yarn ava test/test-zoe-hello.js -m '*greet*'
+
+  ✔ contract greets by name
+  ─
+
+  1 test passed
+```