Skip to content

Commit 70d84b5

Browse files
gregnazariogregnazario
authored
[move] Add documentation on Move scripts in more detail (#207)
Move scripts only had a single tutorial for usage, which was a bit confusing. This format goes into more detail, and allows for explaining limitations on Move scripts, compilation, and how to run across different platforms.
1 parent 5de6efe commit 70d84b5

File tree

15 files changed

+334
-10
lines changed

15 files changed

+334
-10
lines changed

‎apps/docusaurus/docs/concepts/txns-states.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ A signed transaction on the blockchain contains the following information:
6060
Within a given transaction, the two most common types of payloads include:
6161

6262
- An entry point
63-
- [A script (payload)](../move/move-on-aptos/move-scripts)
63+
- [A script (payload)](../move/move-on-aptos/scripts/index.md)
6464

6565
Currently, the SDKs [Python](/sdks/python-sdk.md) and [Typescript](/sdks/ts-sdk/index.md) support both. This guide points out many of those entry points, such as `coin::transfer` and `aptos_account::create_account`.
6666

‎apps/docusaurus/docs/indexer/custom-processors/parsing-txns.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ There are four types of transactions on Aptos:
2626

2727
The first 3 of these are internal to the system and are not relevant to most processors; we do not cover them in this guide.
2828

29-
Generally speaking, most user transactions originate from a user calling an entry function in a Move module deployed on chain, for example `0x1::coin::transfer`. In all other cases they originate from [Move scripts](/move/move-on-aptos/move-scripts). You can learn more about the different types of transactions [here](../../concepts/txns-states##types-of-transactions).
29+
Generally speaking, most user transactions originate from a user calling an entry function in a Move module deployed on chain, for example `0x1::coin::transfer`. In all other cases they originate from [Move scripts](/move/move-on-aptos/scripts/index.md). You can learn more about the different types of transactions [here](../../concepts/txns-states##types-of-transactions).
3030

3131
A user transaction that a processor handles contains a variety of information. At a high level it contains:
3232

‎apps/docusaurus/docs/move/book/modules-and-scripts.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ A Move source file (or **compilation unit**) may contain multiple modules and sc
99
### Scripts
1010

1111
:::tip Tutorial
12-
To learn how to publish and execute a Move script, follow the [Move Scripts](../move-on-aptos/move-scripts.md) example.
12+
To learn how to publish and execute a Move script, follow the [Move Scripts](../move-on-aptos/scripts/script-tutorial.md) example.
1313
:::
1414

1515
A script has the following structure:

‎apps/docusaurus/docs/move/move-on-aptos/scripts/compiling-scripts.md

+63
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
title: "Compiling Move Scripts"
3+
---
4+
5+
import CodeBlock from '@theme/CodeBlock';
6+
7+
# How can I compile Move Scripts?
8+
9+
Move scripts can be compiled with the already existing Aptos Move compiler in
10+
the Aptos CLI. Simply create a script file and compile it in the package with:
11+
12+
```shell
13+
aptos move compile
14+
```
15+
16+
There will then be compiled bytecode files under `build/` with the same name as
17+
the function in Move.
18+
19+
For example this script in package `transfer_half`, would compile
20+
to `build/transfer_half/bytecode_scripts/transfer_half.mv`
21+
22+
```move
23+
script {
24+
use std::signer;
25+
use aptos_framework::coin;
26+
use aptos_framework::aptos_account;
27+
28+
fun transfer_half<Coin>(caller: &signer, receiver_address: address) {
29+
// Retrieve the balance of the caller
30+
let caller_address: address = signer::address_of(caller);
31+
let balance: u64 = coin::balance<Coin>(caller_address);
32+
33+
// Send half to the receiver
34+
let half = balance / 2;
35+
aptos_account::transfer_coins<Coin>(caller, receiver_address, half);
36+
}
37+
}
38+
```
39+
40+
Additionally, there is a convenience function for a package with exactly one
41+
script with the below command:
42+
43+
```shell
44+
aptos move compile-script
45+
```
46+
47+
Providing output like below returning the exact location of the script and a
48+
hash for convenience
49+
50+
```shell
51+
Compiling, may take a little while to download git dependencies...
52+
UPDATING GIT DEPENDENCY https://github.com/aptos-labs/aptos-core.git
53+
INCLUDING DEPENDENCY AptosFramework
54+
INCLUDING DEPENDENCY AptosStdlib
55+
INCLUDING DEPENDENCY MoveStdlib
56+
BUILDING transfer_half
57+
{
58+
"Result": {
59+
"script_location": "/opt/git/developer-docs/apps/docusaurus/static/move-examples/scripts/transfer_half/script.mv",
60+
"script_hash": "9b57ffa952da2a35438e2cf7e941ef2120bb6c2e4674d4fcefb51d5e8431a148"
61+
}
62+
}
63+
```

‎apps/docusaurus/docs/move/move-on-aptos/scripts/index.md

+46
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
title: "Building with Move Scripts"
3+
---
4+
5+
import CodeBlock from '@theme/CodeBlock';
6+
7+
# What are Move Scripts?
8+
9+
Move Scripts are a way to run multiple public functions on Aptos in a single
10+
transaction. This is similar to deploying a helper module that would do common
11+
tasks, but allows for the flexibility of not having to deploy beforehand.
12+
13+
An example would be a function to transfer a half of a user's balance to another
14+
account. This is something that is easily programmable, but likely would not
15+
need a module deployed for it:
16+
17+
```move
18+
script {
19+
use std::signer;
20+
use aptos_framework::coin;
21+
use aptos_framework::aptos_account;
22+
23+
fun transfer_half<Coin>(caller: &signer, receiver_address: address) {
24+
// Retrieve the balance of the caller
25+
let caller_address: address = signer::address_of(caller);
26+
let balance: u64 = coin::balance<Coin>(caller_address);
27+
28+
// Send half to the receiver
29+
let half = balance / 2;
30+
aptos_account::transfer_coins<Coin>(caller, receiver_address, half);
31+
}
32+
}
33+
```
34+
35+
# Learn more about using Move Scripts
36+
37+
- [Writing scripts](./writing-scripts.md)
38+
- [Compiling scripts](./compiling-scripts.md)
39+
- [Running scripts](./running-scripts.md)
40+
41+
# More details
42+
43+
For more details on Move Scripts, checkout:
44+
45+
- [Move Book on Scripts](/move/book/modules-and-scripts.md)
46+
- [Tutorial on Scripts](./script-tutorial.md)

‎apps/docusaurus/docs/move/move-on-aptos/scripts/running-scripts.md

+105
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
title: "Running Move Scripts"
3+
---
4+
5+
import CodeBlock from '@theme/CodeBlock';
6+
7+
# How can I run Move Scripts?
8+
9+
Move scripts are supported in the Aptos TypeScript SDK, Aptos Wallet Adapter,
10+
and in the Aptos CLI.
11+
12+
## Running scripts with the TypeScript SDK
13+
14+
To use a script with the TypeScript SDK, add the `bytecode` directly to the
15+
transaction in place of an entry function name.
16+
17+
```ts
18+
import { readFileSync } from "fs";
19+
import { Aptos, Account, AccountAddress } from "@aptos-labs/ts-sdk";
20+
21+
// Setup client, and account to sign
22+
const aptos = new Aptos();
23+
const account = Account.generate();
24+
25+
// Load script bytecode
26+
const buffer = readFileSync("./transfer_half.mv", "buffer");
27+
const bytecode = new Uint8Array.from(buffer);
28+
29+
// Build a transaction with the bytecode of the script
30+
const transaction = await aptos.transaction.build.simple({
31+
sender: account.accountAddress,
32+
data: {
33+
bytecode,
34+
typeArguments: ["0x1::aptos_coin::AptosCoin"],
35+
functionArguments: ["0x1"],
36+
},
37+
});
38+
39+
// Submit and wait for the transaction to complete
40+
const pendingTxn = await aptos.signAndSubmitTransaction({
41+
signer: account,
42+
transaction,
43+
});
44+
await aptos.waitForTransaction({ transactionHash: pendingTxn.hash });
45+
```
46+
47+
## Running scripts with the Aptos Wallet Adapter
48+
49+
:::warning
50+
Not all wallets support scripts, but when the wallet supports scripts, it can be
51+
provided as below
52+
:::
53+
54+
Similar to the TypeScript SDK, the same inputs are accepted as a transaction
55+
type on the wallet adapter. Just simply load the bytecode as a hex `string` or
56+
a `uint8array`.
57+
58+
```ts
59+
import { useWallet } from "@aptos-labs/wallet-adapter-react";
60+
61+
//...
62+
63+
// Load the bytecode either as a uint8array or a hex encoded string
64+
const BYTECODE_IN_HEX = "0xa11ceb0b...78979";
65+
66+
export default function App() {
67+
const { signAndSubmitTransaction } = useWallet();
68+
69+
function submitScript() {
70+
signAndSubmitTransaction({
71+
data: {
72+
bytecode: BYTECODE_IN_HEX,
73+
typeArguments: ["0x1::aptos_coin::AptosCoin"],
74+
functionArguments: ["0x1"],
75+
},
76+
});
77+
}
78+
79+
// ...
80+
}
81+
```
82+
83+
## Running scripts with the CLI
84+
85+
Running scripts with the CLI can be run with the command
86+
87+
```shell
88+
aptos move run-script
89+
```
90+
91+
There are two ways to run it, with a pre-compiled script, or it will compile the
92+
script in-place similar to the compile step.
93+
94+
If you already have a compiled script, you can run it
95+
with `--compiled-script-path` like the example below:
96+
97+
```shell
98+
aptos move run-script --compiled-script-path /opt/git/developer-docs/apps/docusaurus/static/move-examples/scripts/transfer_half/script.mv
99+
```
100+
101+
Similarly, if it's not compiled, just use `--script-path`
102+
103+
```shell
104+
aptos move run-script --script-path ./sources/transfer_half.move
105+
```

‎apps/docusaurus/docs/move/move-on-aptos/move-scripts.md ‎apps/docusaurus/docs/move/move-on-aptos/scripts/script-tutorial.md

+6-4
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
11
---
2-
title: "Move Scripts"
2+
title: "Move Scripts Tutorial"
33
---
44

55
# Move Scripts
66

7-
This tutorial explains how to write and execute a [Move script](../book/modules-and-scripts.md). You can use Move scripts to execute a series of commands across published Move module interfaces.
7+
This tutorial explains how to write and execute a [Move script](../../book/modules-and-scripts.md). You can use Move scripts to execute a series of commands across published Move module interfaces.
8+
9+
For more information about scripts, see the [Move scripts docs](./index.md)
810

911
## Example use case
1012

@@ -39,7 +41,7 @@ Now that you know what you would like to accomplish, you need to determine:
3941
- Do I need a `Move.toml`?
4042
- How do I run my script with the CLI?
4143

42-
Let us run through how to execute a Move script with a step-by-step example using the [Aptos CLI](../../tools/aptos-cli/use-cli/use-aptos-cli.md).
44+
Let us run through how to execute a Move script with a step-by-step example using the [Aptos CLI](../../../tools/aptos-cli/use-cli/use-aptos-cli.md).
4345

4446
1. Make a new directory for your work:
4547

@@ -48,7 +50,7 @@ Let us run through how to execute a Move script with a step-by-step example usin
4850
cd testing
4951
```
5052

51-
2. Set up the Aptos CLI and [create an account](../../tools/aptos-cli/use-cli/use-aptos-cli#initialize-local-configuration-and-create-an-account):
53+
2. Set up the Aptos CLI and [create an account](../../../tools/aptos-cli/use-cli/use-aptos-cli#initialize-local-configuration-and-create-an-account):
5254

5355
```sh
5456
aptos init --network devnet

‎apps/docusaurus/docs/move/move-on-aptos/scripts/writing-scripts.md

+59
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
title: "Writing Move Scripts"
3+
---
4+
5+
import CodeBlock from '@theme/CodeBlock';
6+
7+
# How can I write Move Scripts?
8+
9+
Move scripts can be written in tandem with Move contracts, but it's highly
10+
suggested to use a separate Move package for it. This will make it easier for
11+
you to determine which bytecode file comes from the script.
12+
13+
## Package layout
14+
15+
The package needs a Move.toml and a sources directory, similar to code modules.
16+
17+
For example, we may have a directory layout like:
18+
19+
```
20+
my_project/
21+
├── Move.toml
22+
└── sources/
23+
└── my_script.move
24+
25+
```
26+
27+
## Script syntax
28+
29+
Scripts can be written exactly the same as modules on Aptos. Imports can be used
30+
for any dependencies in the Move.toml file, and all public functions, including
31+
entry functions, can be called from the contract. There are a few limitations:
32+
33+
- There must be only one function in the contract, it will compile to that name.
34+
- Input arguments can only be one of
35+
[`u8`, `u16`, `u32`, `u64`, `u256`, `address`, `bool`, `signer`, `&signer`, `vector<u8>`].
36+
There is no support for vectors of other types, or structs.
37+
38+
An example below:
39+
40+
```move
41+
script {
42+
use std::signer;
43+
use aptos_framework::coin;
44+
use aptos_framework::aptos_account;
45+
46+
fun transfer_half<Coin>(caller: &signer, receiver_address: address) {
47+
// Retrieve the balance of the caller
48+
let caller_address: address = signer::address_of(caller);
49+
let balance: u64 = coin::balance<Coin>(caller_address);
50+
51+
// Send half to the receiver
52+
let half = balance / 2;
53+
aptos_account::transfer_coins<Coin>(caller, receiver_address, half);
54+
}
55+
}
56+
```
57+
58+
For more specific details see:
59+
[Move Book on Scripts](/move/book/modules-and-scripts.md)

‎apps/docusaurus/docs/nodes/full-node/aptos-db-restore.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ data in remote storage, such as Amazon S3 or Google Cloud Storage. The links to
2323

2424
| | AWS Backup Data | Google Cloud Backup Data |
2525
| ------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
26-
| Testnet | Discontinued | https://github.com/aptos-labs/aptos-networks/blob/main/testnet/backups/gcs.yaml |
26+
| Testnet | Discontinued | https://github.com/aptos-labs/aptos-networks/blob/main/testnet/backups/gcs.yaml |
2727
| Mainnet | https://github.com/aptos-labs/aptos-networks/blob/main/mainnet/backups/s3-public.yaml | https://github.com/aptos-labs/aptos-networks/blob/main/mainnet/backups/gcs.yaml |
2828

2929
:::tip

‎apps/docusaurus/docs/reference/glossary.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -451,7 +451,7 @@ See [`table.move`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move
451451
- A single transaction script can send funds to multiple recipients and invoke procedures from several different modules.
452452
- A transaction script **is not** stored in the global state and cannot be invoked by other transaction scripts. It is a single-use program.
453453

454-
To see example uses of transaction scripts, follow [Move scripts](../move/move-on-aptos/move-scripts.md) and the [Your First Multisig](../tutorials/first-multisig.md) tutorial.
454+
To see example uses of transaction scripts, follow [Move scripts](../move/move-on-aptos/scripts/script-tutorial.md) and the [Your First Multisig](../tutorials/first-multisig.md) tutorial.
455455

456456
## V
457457

‎apps/docusaurus/docusaurus.config.ts

+4
Original file line numberDiff line numberDiff line change
@@ -427,6 +427,10 @@ const config: Config = {
427427
from: "/sdks/new-ts-sdk/typescript",
428428
to: "/sdks/ts-sdk/typescript",
429429
},
430+
{
431+
from: "/move/move-on-aptos/move-scripts",
432+
to: "/move/move-on-aptos/scripts/script-tutorial",
433+
},
430434
],
431435
// Create redirects for all the move pages
432436
createRedirects(existingPath) {

‎apps/docusaurus/src/components/sidebars.ts

+16-1
Original file line numberDiff line numberDiff line change
@@ -207,9 +207,24 @@ const sidebars: SidebarsConfig = {
207207
"move/move-on-aptos/objects/using-objects",
208208
],
209209
},
210+
{
211+
type: "category",
212+
label: "Move Scripts",
213+
collapsible: true,
214+
collapsed: true,
215+
link: {
216+
type: "doc",
217+
id: "move/move-on-aptos/scripts/index",
218+
},
219+
items: [
220+
"move/move-on-aptos/scripts/writing-scripts",
221+
"move/move-on-aptos/scripts/compiling-scripts",
222+
"move/move-on-aptos/scripts/running-scripts",
223+
"move/move-on-aptos/scripts/script-tutorial",
224+
],
225+
},
210226
"move/move-on-aptos/resource-accounts",
211227
"move/move-on-aptos/modules-on-aptos",
212-
"move/move-on-aptos/move-scripts",
213228
"move/move-on-aptos/cli",
214229
"move/move-on-aptos/cryptography",
215230
"move/move-on-aptos/gas-profiling",

0 commit comments

Comments
 (0)