Skip to content

Commit 79ea539

Browse files
robert-zarembarobert-zaremba
committed
docs: add more information about testing and ASA template
1 parent 6dcdb75 commit 79ea539

File tree

5 files changed

+122
-12
lines changed

5 files changed

+122
-12
lines changed

‎docs/auditing.html

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
---
3+
4+
<!DOCTYPE html>
5+
<html lang="en">
6+
<head>
7+
<!-- Required meta tags -->
8+
<meta charset="utf-8" />
9+
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
10+
<title>Algo Builder</title>
11+
<meta
12+
name="description"
13+
content="Framework to automate development of Algorand Assets and Smart Contracts."
14+
/>
15+
16+
<!--Google font-->
17+
<link
18+
href="https://fonts.googleapis.com/css?family=K2D:300,400,500,700,800"
19+
rel="stylesheet"
20+
/>
21+
22+
<link rel="stylesheet" href="_css/bootstrap.css" />
23+
<link rel="stylesheet" href="_css/main.css" />
24+
<link rel="shortcut icon" type="image/png" href="media/logo-icon.png" />
25+
26+
<script
27+
src="https://cdn.jsdelivr.net/npm/[email protected]/dist/jquery.slim.min.js"
28+
integrity="sha384-DfXdz2htPH0lsSSs5nCTpuj/zy4C+OGpamoFVy38MVBnE+IbbVYUew+OrCXaRkfj"
29+
crossorigin="anonymous"
30+
></script>
31+
32+
<script
33+
src="https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.bundle.min.js"
34+
integrity="sha384-fQybjgWLrvvRgtW6bFlB7jaZrFsaBXjsOMm/tB9LTS58ONXgqbR9W8oWht/amnpF"
35+
crossorigin="anonymous"
36+
></script>
37+
</head>
38+
<body>
39+
<!--Header Section-->
40+
<section class="bg-gradient pt-4 pb-6">
41+
<div class="container">
42+
43+
Auditing
44+
45+
</div>
46+
</section>
47+
48+
<!--footer-->
49+
<footer class="py-5 bg-light">
50+
<div class="container">
51+
<div class="row">
52+
<div class="col-12 text-center">
53+
<ul class="list-inline">
54+
<li class="list-inline-item">
55+
<a href="https://github.com/scale-it/algo-builder/issues">Contact Us</a>
56+
</li>
57+
<li class="list-inline-item"><a href="./api/algob/index.html">API Docs</a></li>
58+
<li class="list-inline-item">
59+
<a href="https://github.com/scale-it/algo-builder">GitHub repository</a>
60+
</li>
61+
</ul>
62+
</div>
63+
</div>
64+
<div class="row my-2">
65+
<div class="col-md-4 mx-auto text-muted text-center small-xl">
66+
&copy;
67+
<script>
68+
document.write(new Date().getFullYear());
69+
</script>
70+
Algo Builder - All Rights Reserved
71+
</div>
72+
</div>
73+
</div>
74+
</footer>
75+
76+
<!-- jQuery first, then Popper.js, then Bootstrap JS -->
77+
<script src="https://code.jquery.com/jquery-3.2.1.min.js"></script>
78+
<script src="https://cdnjs.cloudflare.com/ajax/libs/feather-icons/4.28.0/feather.min.js"></script>
79+
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.17.0/prism.min.js"></script>
80+
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.17.0/plugins/line-numbers/prism-line-numbers.min.js"></script>
81+
<script src="_js/scripts.js"></script>
82+
</body>
83+
</html>

‎docs/guide/deployer.md

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,10 +15,16 @@ It will protect you from deploying same ASA or stateful smart contract twice. It
1515
Deployer class has the following modes:
1616

1717
- Deploy Mode: In deploy mode user can write or read the checkpoints, create transaction logs. Files that are directly placed in `scripts/` folder are considered to be run in this mode. Ex: `scripts/deploy.js`
18+
To run a script in the _deploy_ mode (the script will receive deployer instance in _deploy_ mode\_):
1819

19-
- Run Mode: In run mode user can access/read checkpoints, create logs but cannot write(create) checkpoints. Files placed in nested folders (non-direct children) of `scripts/` folder are considered to be run in this mode. Ex: `scripts/transfer/run-script.js`.
20+
yarn run algob deploy scripts/script_name.js
2021

21-
**Note:** In run mode user can `deploy`, `update`, `delete` or perform all these operations in a group transaction using [`executeTx`](https://algobuilder.dev/api/algob/modules.html#executetransaction) function but the `checkpoints will not be created when using run mode.`
22+
- Run Mode: In run mode user can access/read checkpoints, create logs but cannot write(create) checkpoints. Files placed in nested folders (non-direct children, eg: `scripts/transfer/run-script.js`) of `scripts/` folder are considered to be run in this mode.
23+
To run a script in the _run_ mode (the script will receive deployer instance in _run_ mode\_):
24+
25+
yarn run algob run scripts/transfer/run-script.js
26+
27+
**Note:** In run mode user can `deploy`, `update`, `delete` or perform all these operations in a group transaction using [`executeTx`](https://algobuilder.dev/api/algob/modules.html#executetransaction) function but the `checkpoints will not be created when using run mode.`
2228

2329
Read more about deployment and scripts in our [spec](https://paper.dropbox.com/doc/Algorand-builder-specs--A_yfjbGmtkx5BYMOy8Ha50~uAg-Vcdp0XNngizChyUWvFXfs#:uid=213683005476107006060621&h2=Scripts).
2430

@@ -27,8 +33,9 @@ Read more about deployment and scripts in our [spec](https://paper.dropbox.com/d
2733
When you initiate a new project, it will create a `sample-project` with the deployment script `scripts/0-sampleScript.js`,
2834

2935
You can write deployment tasks synchronously and they'll be executed in the correct order.
36+
Below we will guide you how to use the deployer to create ASA and smart contracts. Please look at our [templates](https://github.com/scale-it/algo-builder/tree/master/examples) for more more details how to create to organize files in scripts directory. The [asa example](https://github.com/scale-it/algo-builder/tree/master/examples/asa) the best one to start.
3037

31-
### ASA
38+
### Deploying ASA
3239

3340
// ASA-1 will be deployed before ASA-2
3441
await deployer.deployASA("ASA-1", {...});

‎docs/guide/testing-teal.md

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,13 @@ layout: splash
66

77
[TEAL](https://developer.algorand.org/docs/reference/teal/specification/) is a stack based language that executes inside Algorand transactions to program logic signatures and smart contracts. `@algo-builder/runtime` provides a TypeScript and JavaScript, lightweight runtime and TEAL interpreter to test Algorand transactions, ASA and Smart Contracts.
88

9+
You can test your smart contracts and flows by starting a local node (see our [infrastructure](https://github.com/scale-it/algo-builder/tree/master/infrastructure/README.md) guide) and creating [_deploy_ and _run_](<(./deployer.md)>) scripts to automate the process of creating dapps and running them against the official Algorand implementation.
10+
11+
However, this is not efficient for sustainable development. You need a proper automated test process, we strongly advice you to use our `@algo-builder/runtime` package and the testing framework. It essentially brings the unit and integration testing experience form traditional software development to Algorand smart contracts development.
12+
13+
We strongly advice to always test your smart contract, and try to get 100% test coverage. The last thing you want is to get your contract _hacked_ and your _user assets stolen_.
14+
Note: 100% test coverage is strongly recommended, but it doesn't guarantee that your smart contracts are safe. For complex flow we still recommend you to [audit](https://algobuilder.dev/auditing.html) your solution.
15+
916
## How it works
1017

1118
The `@algo-builder/runtime` (TypeScript Algorand runtime) package has 4 major components:
@@ -421,7 +428,8 @@ TEAL files used for the below tests can be found in `/test/fixtures` in [runtime
421428
- [Boilerplate Stateless Teal](https://github.com/scale-it/algo-builder/blob/master/packages/runtime/test/integration/basic-teal.ts)
422429
- [Escrow Account Test](https://github.com/scale-it/algo-builder/blob/master/packages/runtime/test/integration/escrow-account.ts)
423430
- [Boilerplate Stateful Teal](https://github.com/scale-it/algo-builder/blob/master/packages/runtime/test/integration/stateful-counter.ts)
424-
- Complex TEAL test suite (Stateless + Stateful + Atomic transactions) - [Crowdfunding application](https://github.com/scale-it/algo-builder/tree/master/examples/crowdfunding/test)
425-
- [DAO Tests](https://github.com/scale-it/algo-builder/tree/master/examples/dao/test)
426431

427-
See our [examples](https://github.com/scale-it/algo-builder/tree/master/examples) and [Interesting Test Suites](https://github.com/scale-it/algo-builder/blob/master/examples/README.md#interesting-test-suites) for more interesting test suites.
432+
In our [templates](https://github.com/scale-it/algo-builder/blob/master/examples/README.md#interesting-test-suites) you will find dapps with test suites, which serves as a good examples and place to learn. Notable mentions:
433+
434+
- [DAO Tests](https://github.com/scale-it/algo-builder/tree/master/examples/dao/test)
435+
- Complex TEAL test suite (Stateless + Stateful + Atomic transactions) - [Crowdfunding application](https://github.com/scale-it/algo-builder/tree/master/examples/crowdfunding/test)

‎docs/index.html

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -42,9 +42,9 @@
4242
<div class="row" id="header">
4343
<div class="col-12 align-items-center">
4444
<div class="heading-brand"><img src="media/logo-website.png" /></div>
45-
<a href="https://github.com/scale-it/algo-builder" class="btn btn-success svg-icon">
46-
<em class="mr-2" data-feather="github"></em>
47-
Github
45+
<a href="https://algobuilder.dev/auditing.html" class="btn btn-secondary svg-icon">
46+
<em class="mr-2" data-feather="cpu"></em>
47+
Auditing
4848
</a>
4949
</div>
5050
</div>

‎examples/asa/README.md

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,23 @@
11
# ASA deployment using [Algo Builder](https://github.com/scale-it/algo-builder/)
22

3-
This project shows how to create Algorand Standard Asset (ASA).
4-
We will create gold and tesla assets. In algob, we recommend to
3+
This project shows how to use Algo Builder to:
4+
5+
- organize your project
6+
- define Algorand Standard Asset (ASA)
7+
- create scripts and use `deployer` object to deploy assets and run transactions
8+
For a template with test suite, browse the following [examples with tests](https://github.com/scale-it/algo-builder/blob/master/examples/README.md#interesting-test-suites) list.
9+
10+
We will create gold and tesla assets. We recommend to
511
create assets using a specification file, as provided in `assets/asa.yaml`.
612

713
Each of these assets are owned by their specific owner accounts.
8-
After the creation, a third account is opted-in in order to receive the assets.
14+
After the creation, we opt-in accounts in order to receive the assets.
15+
16+
To deploy all assets simply run:
17+
18+
algob deploy
19+
20+
It will go through all files in directly placed in the `scripts/` directory (so, it doesn't go recursively into the subdirectories) and run them in the _deploy_ mode. For more information about the deployer read the [deployer guide](https://algobuilder.dev/guide/deployer.html).
921

1022
Transfers can be executed by executing `algob run scripts/transfer/gold-to-john.js` and other scripts in `scripts/transfer/`.
1123
These scripts contain logic to transfer assets to `john-account` but other accounts can be configured as well.

0 commit comments

Comments
 (0)