From 7bfec27ad82927af1c2ed9a82d472d7e1b5eefa6 Mon Sep 17 00:00:00 2001
From: Adam Avramov <adam@hack.bg>
Date: Wed, 18 Oct 2023 15:40:57 +0300
Subject: [PATCH] docs: move Contract and Template sections to Agent docs

---
 README.md       |   4 +-
 agent/README.md | 131 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 133 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 2b02ae6a29f..2d37084a990 100644
--- a/README.md
+++ b/README.md
@@ -41,7 +41,7 @@ $ npx @hackbg/fadroma@1.5.6 create
 $ npm exec fadroma add
 ```
 
-## Deploying a project
+## Deploying your project
 
 ```shell
 # Deploy the project, or update the current deployment:
@@ -172,7 +172,7 @@ corresponding to the contract crates of your project. You can
 Fadroma implements **reproducible compilation** of contracts.
 What to compile is specified using the primitives defined in [Fadroma Core](../client/README.md).
 
-## Uploading contracts
+## Uploading individual contracts
 
 ```shell
 # Upload a contract:
diff --git a/agent/README.md b/agent/README.md
index d14859a4d58..22ad962b4c2 100644
--- a/agent/README.md
+++ b/agent/README.md
@@ -549,3 +549,134 @@ class DeploymentB extends Deployment {
   }
 }
 ```
+
+## Contract
+
+The `Contract` class describes an individual smart contract instance and uniquely identifies it
+within the `Deployment`.
+
+```typescript
+import { Contract } from '@fadroma/agent'
+
+new Contract({
+  repository: 'REPO',
+  revision:   'REF',
+  workspace:  'WORKSPACE'
+  crate:      'CRATE',
+  artifact:   'ARTIFACT',
+  chain:      { /* ... */ },
+  agent:      { /* ... */ },
+  deployment: { /* ... */ },
+  codeId:     0,
+  codeHash:   'CODEHASH'
+  client:     Client,
+  name:       'NAME',
+  initMsg:    async () => ({})
+})
+```
+
+### Naming and labels
+
+The chain requires labels to be unique.
+Labels generated by Fadroma are of the format `${deployment.name}/${contract.name}`.
+
+### Lazy init
+
+The `initMsg` property of `Contract` can be a function returning the actual message.
+This function is only called during instantiation, and can be used to generate init
+messages on the fly, such as when passing the address of one contract to another.
+
+### Deploying contract instances
+
+To instantiate a `Contract`, its `agent` property must be set to a valid `Agent`.
+When obtaining instances from a `Deployment`, their `agent` property is provided
+from `deployment.agent`.
+
+```typescript
+import { Agent } from '@fadroma/agent'
+assert(deployment.a.agent instanceof Agent)
+assert.equal(deployment.a.agent, deployment.agent)
+```
+
+You can instantiate a `Contract` by awaiting the `deployed` property or the return value of the
+`deploy()` method. Since distributed ledgers are append-only, deployment is an idempotent operation,
+so the deploy will run only once and subsequent calls will return the same `Contract` with the
+same `address`.
+
+```typescript
+await deployment.a.deploy()
+await deployment.a.deployed
+```
+
+If `contract.codeId` is not set but either source code or a WASM binary is present,
+this will try to upload and build the code first.
+
+```typescript
+await deployment.a.uploaded
+await deployment.a.upload()
+
+await deployment.a.built
+await deployment.a.build()
+```
+
+## Template
+
+The `Template` class represents a smart contract's source, compilation,
+binary, and upload. It can have a `codeHash` and `codeId` but not an
+`address`.
+
+**Instantiating a template** refers to calling the `template.instance`
+method (or its plural, `template.instances`), which returns `Contract`,
+which represents a particular smart contract instance, which can have
+an `address`.
+
+### Deploying multiple contracts from a template
+
+The `deployment.template` method adds a `Template` to the `Deployment`.
+
+```typescript
+// TODO
+```
+
+You can pass either an array or an object to `template.instances`.
+
+```typescript
+// TODO
+```
+
+### Building from source code
+
+To build, the `builder` property must be set to a valid `Builder`.
+When obtaining instances from a `Deployment`, the `builder` property
+is provided automatically from `deployment.builder`.
+
+```typescript
+// TODO
+```
+
+You can build a `Template` (or its subclass, `Contract`) by awaiting the
+`built` property or the return value of the `build()` method.
+
+```typescript
+// TODO
+```
+
+### Uploading binaries
+
+To upload, the `uploader` property must be set to a valid `Uploader`.
+When obtaining instances from a `Deployment`, the `uploader` property
+is provided automatically from `deployment.uploader`.
+
+```typescript
+// TODO
+```
+
+You can upload a `Template` (or its subclass, `Contract`) by awaiting the
+`uploaded` property or the return value of the `upload()` method.
+
+If a WASM binary is not present (`template.artifact` is empty),
+but a source and a builder are present, this will also try to build the contract.
+
+```typescript
+// TODO
+```