Skip to content

Commit 2ab3235

Browse files
FestivemenaFestivemena
authored
Added Tutorials for Coin Flip, Donation and Advanced XCC (#2766)
* fixed sidebar for Linkdrop * Added Tutorials for Advanced-XCC, Donation and Coin Flip * added factory tutorial and made modifications to the previous tutorials * Coin Flip, Advanced XCC, Donation * minor fixes * fixes 2 * minor preview fix again * minor preview fix again missed imports * fixed broken link * fixed broken issues * fixed description
1 parent ee35254 commit 2ab3235

26 files changed

+3784
-19
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ website/i18n/*
99
website/.docusaurus/*
1010
website/package-lock.json
1111
website/yarn.lock
12+
website/pnpm-lock.yaml
1213
neardev
1314
.idea
1415
.docz

‎docs/tutorials/advanced-xcc/0-introduction.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
id: introduction
3+
title: Advanced Cross-Contract Calls on NEAR
4+
sidebar_label: Introduction
5+
description: "Master complex cross-contract call patterns in NEAR Protocol, including batch operations, parallel execution, and advanced error handling."
6+
---
7+
8+
Cross-contract calls are one of NEAR's most powerful features, enabling smart contracts to interact with each other seamlessly. While basic cross-contract calls allow simple interactions, advanced patterns unlock the full potential of NEAR's composable architecture.
9+
10+
## What You'll Build
11+
12+
By the end of this tutorial, you'll master how to:
13+
14+
- **Batch multiple actions** to the same contract with atomic rollback
15+
- **Execute parallel calls** to different contracts simultaneously
16+
- **Handle complex responses** from multiple contract interactions
17+
- **Manage gas efficiently** across multiple contract calls
18+
- **Implement robust error handling** for multi-contract scenarios
19+
20+
## Why Advanced Cross-Contract Calls Matter
21+
22+
These patterns are essential for:
23+
24+
- **DeFi protocols** that interact with multiple token contracts and AMMs
25+
- **Gaming platforms** that manage assets across different contract systems
26+
- **DAO governance** systems that execute proposals across multiple contracts
27+
- **NFT marketplaces** that coordinate with various collection contracts
28+
29+
:::info Source Code
30+
31+
The complete source code is available at [near-examples/cross-contract-calls](https://github.com/near-examples/cross-contract-calls).
32+
33+
Test contracts are deployed on testnet:
34+
- `hello.near-examples.testnet`
35+
- `counter.near-examples.testnet`
36+
- `guestbook.near-examples.testnet`
37+
38+
:::
39+
40+
## How It Works
41+
42+
Advanced cross-contract calls leverage NEAR's promise-based architecture:
43+
44+
```mermaid
45+
graph TD
46+
A[Your Contract] --> B[Batch Actions]
47+
A --> C[Parallel Calls]
48+
49+
B --> D[Same Contract - Action 1]
50+
B --> E[Same Contract - Action 2]
51+
B --> F[Same Contract - Action 3]
52+
53+
C --> G[Contract A]
54+
C --> H[Contract B]
55+
C --> I[Contract C]
56+
57+
D --> J[Single Result]
58+
E --> J
59+
F --> J
60+
61+
G --> K[Array of Results]
62+
H --> K
63+
I --> K
64+
```
65+
66+
Key concepts:
67+
68+
- **Atomicity**: Batch actions either all succeed or all fail
69+
- **Parallelism**: Multiple contracts execute simultaneously
70+
- **Complex responses**: Handle arrays of results with individual success/failure states
71+
- **Gas optimization**: Efficient gas distribution across multiple calls
72+
73+
## What You Will Learn
74+
75+
This tutorial is organized into focused chapters:
76+
77+
1. **[Project Setup](1-setup.md)** - Get the example project running locally
78+
2. **[Batch Actions](2-batch-actions.md)** - Learn atomic multi-action patterns
79+
3. **[Parallel Execution](3-parallel-execution.md)** - Execute multiple contracts simultaneously
80+
5. **[Testing & Deployment](4-testing-deployment.md)** - Test and deploy your contracts
81+
82+
Let's [get started with the project setup](1-setup.md)!

‎docs/tutorials/advanced-xcc/1-setup.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
---
2+
id: setup
3+
title: Setting up the Advanced Cross-Contract Calls Project
4+
sidebar_label: Project Setup
5+
description: "Get the advanced cross-contract calls example project running locally with all necessary dependencies and test contracts."
6+
---
7+
8+
import Tabs from "@theme/Tabs";
9+
import TabItem from "@theme/TabItem";
10+
11+
Let's set up the project environment with the main contract and test contracts.
12+
13+
## Obtaining the Project
14+
15+
```bash
16+
git clone https://github.com/near-examples/cross-contract-calls
17+
cd cross-contract-calls
18+
```
19+
20+
Choose your language:
21+
22+
<Tabs>
23+
<TabItem value="js" label="JavaScript" default>
24+
25+
```bash
26+
cd contract-advanced-ts
27+
npm install
28+
```
29+
30+
</TabItem>
31+
<TabItem value="rust" label="Rust">
32+
33+
```bash
34+
cd contract-advanced-rs
35+
cargo check
36+
```
37+
38+
</TabItem>
39+
</Tabs>
40+
41+
## Project Structure
42+
43+
```
44+
├── tests/ # Test environment
45+
│ └── external-contracts/ # Pre-compiled contracts
46+
│ ├── counter.wasm # Simple counter
47+
│ ├── guest-book.wasm # Message storage
48+
│ └── hello-near.wasm # Greeting contract
49+
├── src/ # Main contract code
50+
│ ├── batch_actions.* # Batch operations
51+
│ ├── multiple_contracts.* # Parallel execution
52+
│ └── similar_contracts.* # Same-type calls
53+
└── README.md
54+
```
55+
56+
## Test Contracts Overview
57+
58+
### Hello NEAR Contract
59+
- `get_greeting()` - Returns current greeting
60+
- `set_greeting(message: string)` - Updates greeting
61+
62+
### Counter Contract
63+
- `get_num()` - Returns current count
64+
- `increment()` - Increases by 1
65+
- `decrement()` - Decreases by 1
66+
67+
### Guest Book Contract
68+
- `add_message(text: string)` - Adds message
69+
- `get_messages()` - Returns all messages
70+
71+
## Building the Contract
72+
73+
<Tabs>
74+
<TabItem value="js" label="JavaScript" default>
75+
76+
```bash
77+
npm run build
78+
# Output: build/cross_contract.wasm
79+
```
80+
81+
</TabItem>
82+
<TabItem value="rust" label="Rust">
83+
84+
```bash
85+
cargo near build
86+
# Output: target/wasm32-unknown-unknown/release/cross_contract.wasm
87+
```
88+
89+
</TabItem>
90+
</Tabs>
91+
92+
## Running Tests
93+
94+
Verify everything works:
95+
96+
<Tabs>
97+
<TabItem value="js" label="JavaScript" default>
98+
99+
```bash
100+
npm test
101+
```
102+
103+
</TabItem>
104+
<TabItem value="rust" label="Rust">
105+
106+
```bash
107+
cargo test
108+
```
109+
110+
</TabItem>
111+
</Tabs>
112+
113+
Expected output:
114+
```
115+
✓ Test batch actions
116+
✓ Test multiple contracts
117+
✓ Test similar contracts
118+
```
119+
120+
## Contract Initialization
121+
122+
The main contract needs external contract addresses:
123+
124+
<Tabs>
125+
<TabItem value="js" label="JavaScript" default>
126+
127+
```typescript
128+
@NearBindgen({})
129+
export class CrossContractCall {
130+
hello_account: AccountId;
131+
counter_account: AccountId;
132+
guestbook_account: AccountId;
133+
134+
@initialize({})
135+
init({
136+
hello_account,
137+
counter_account,
138+
guestbook_account,
139+
}: {
140+
hello_account: AccountId;
141+
counter_account: AccountId;
142+
guestbook_account: AccountId;
143+
}) {
144+
this.hello_account = hello_account;
145+
this.counter_account = counter_account;
146+
this.guestbook_account = guestbook_account;
147+
}
148+
}
149+
```
150+
151+
</TabItem>
152+
<TabItem value="rust" label="Rust">
153+
154+
```rust
155+
#[near_bindgen]
156+
impl Contract {
157+
#[init]
158+
pub fn init(
159+
hello_account: AccountId,
160+
counter_account: AccountId,
161+
guestbook_account: AccountId,
162+
) -> Self {
163+
Self {
164+
hello_account,
165+
counter_account,
166+
guestbook_account,
167+
}
168+
}
169+
}
170+
```
171+
172+
</TabItem>
173+
</Tabs>
174+
175+
## Deploy Your Contract
176+
177+
```bash
178+
# Create your account
179+
near account create-account sponsor-by-faucet-service xcc.YOUR_NAME.testnet autogenerate-new-keypair save-to-keychain network-config testnet create
180+
181+
# Deploy with initialization
182+
near contract deploy xcc.YOUR_NAME.testnet use-file ./build/cross_contract.wasm with-init-call init json-args '{
183+
"hello_account":"hello.near-examples.testnet",
184+
"counter_account":"counter.near-examples.testnet",
185+
"guestbook_account":"guestbook.near-examples.testnet"
186+
}' prepaid-gas '100.0 Tgas' attached-deposit '0 NEAR' network-config testnet sign-with-keychain send
187+
```
188+
189+
Now let's explore [batch actions](2-batch-actions.md) in the next chapter!

0 commit comments

Comments
 (0)