Add doc for call TxScript

Author: Lbqds

docs/dapps/tutorials/dapp-recipes.md

@@ -258,3 +258,80 @@ const testResult1 = await TokenFaucet.tests.withdraw({
 const contractState1 = testResult1.contracts[0] as TokenFaucetTypes.State
 expect(contractState1.fields.balance).toEqual(8n)
 ```
+
+## Call TxScript
+
+Call `TxScript` is a feature that allows interaction with smart contracts on Alephium without consuming gas and modifying the on-chain state. Instead, it executes scripts and returns updated contract states.
+
+### Call contract functions
+
+```rust
+Contract Foo(mut value: U256) {
+  @using(updateFields = true, checkExternalCaller = false)
+  pub fn foo() -> () {
+    value = value + 1
+  }
+}
+
+@using(preapprovedAssets = false)
+TxScript Main(foo: Foo) {
+  foo.foo()
+}
+```
+
+You can use the generated `TypeScript` code to call `TxScript`:
+
+```typescript
+import { getSigner } from '@alephium/web3-test'
+
+const signer = await getSigner()
+const deployFooResult = await Foo.deploy(signer, { initialFields: { value: 0n } })
+const fooInstance = deployFooResult.contractInstance
+const callResult = await Main.call({
+  initialFields: { foo: fooInstance.contractId },
+  interestedContracts: [fooInstance.address]
+})
+expect(callResult.contracts[0].fields.value).toEqual(1n)
+```
+
+### Query and return contract states
+
+`TxScript` also allows you to query and return the states of multiple contracts in a single request:
+
+```rust
+Contract Foo(value: U256) {
+  pub fn foo() -> U256 {
+    return value
+  }
+}
+
+Contract Bar(value: ByteVec) {
+  pub fn bar() -> ByteVec {
+    return value
+  }
+}
+
+TxScript Main(foo: Foo, bar: Bar) {
+  pub fn main() -> (U256, ByteVec) {
+    return foo.foo(), bar.bar()
+  }
+}
+```
+
+Implicit definition of the `main` function does not allow for return values, so an explicit definition of the `main` function is required here.
+
+You can use the generated `TypeScript` code to call `TxScript`:
+
+```typescript
+import { getSigner } from '@alephium/web3-test'
+
+const signer = await getSigner()
+const deployFooResult = await Foo.deploy(signer, { initialFields: { value: 0n } })
+const deployBarResult = await Bar.deploy(signer, { initialFields: { value: '0011' } })
+const fooInstance = deployFooResult.contractInstance
+const barInstance = deployBarResult.contractInstance
+const callResult = await MainForCall.call({
+  initialFields: { foo: fooInstance.contractId, bar: barInstance.contractId }
+})
+expect(callResult.returns).toEqual([0n, '0011'])
+```

docs/ralph/contracts.md

@@ -325,10 +325,10 @@ Contract Foo() {
 @using(preapprovedAssets = false)
 // `TxScript` fields are more like function parameters, and these
 // fields need to be specified every time the script is executed.
-TxScript Main(fooId: ByteVec) {
+TxScript Main(foo: Foo) {
   // The body of `TxScript` consists of statements
   bar()
-  Foo(fooId).foo(0)
+  foo.foo(0)
 
   // You can also define functions in `TxScript`
   fn bar() -> () {
@@ -337,6 +337,23 @@ TxScript Main(fooId: ByteVec) {
 }
 ```
 
+The `main` function of `TxScript` serves as the entry point for contract code execution. It supports both explicit and implicit definitions of the `main` function:
+
+1. Implicit definition of the `main` function, in the example above, the compiler automatically generates a `main` function for the `TxScript`.
+2. Explicit definition of the `main` function:
+
+```rust
+TxScript Main(foo: Foo) {
+  @using(preapprovedAssets = false)
+  pub fn main() -> () {
+    bar()
+    foo.foo(0)
+  }
+}
+```
+
+The explicitly defined `main` function cannot have parameters. If you need to specify parameters, you can pass them as parameters of the `TxScript`.
+
 ## Gasless Transaction
 
 In Ralph, you can use the built-in `payGasFee` to pay transaction gas fees on behalf of the user, for example: