Skip to content

Commit 9e24d7f

Browse files
FestivemenaFestivemena
authored
Near Drop Tutorial (#2694)
* Added Expanded Near Drop Tutorial * Update near-drop.md
1 parent 51a4851 commit 9e24d7f

File tree

10 files changed

+1830
-222
lines changed

10 files changed

+1830
-222
lines changed

‎docs/tutorials/examples/near-drop.md

Lines changed: 406 additions & 222 deletions
Large diffs are not rendered by default.

‎docs/tutorials/neardrop/access-keys.md

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
---
2+
id: access-keys
3+
title: Access Key Management
4+
sidebar_label: Access Key Management
5+
description: "Understand how function-call access keys enable gasless operations in NEAR Drop."
6+
---
7+
import Tabs from '@theme/Tabs';
8+
import TabItem from '@theme/TabItem';
9+
import {Github} from "@site/src/components/codetabs"
10+
11+
This is where NEAR gets really cool. Function-call access keys are what make gasless claiming possible - let's understand how they work!
12+
13+
---
14+
15+
## The Problem NEAR Solves
16+
17+
Traditional blockchains have a chicken-and-egg problem:
18+
- You need tokens to pay gas fees
19+
- But you need gas to receive tokens
20+
- New users are stuck!
21+
22+
NEAR's solution: **Function-call access keys** that let you call specific functions without owning the account.
23+
24+
---
25+
26+
## How Access Keys Work
27+
28+
NEAR has two types of keys:
29+
30+
**Full Access Keys** 🔑
31+
- Complete control over an account
32+
- Can do anything: transfer tokens, deploy contracts, etc.
33+
- Like having admin access
34+
35+
**Function-Call Keys** 🎫
36+
- Limited permissions
37+
- Can only call specific functions
38+
- Like having a concert ticket - gets you in, but only to your seat
39+
40+
---
41+
42+
## NEAR Drop's Key Magic
43+
44+
Here's what happens when you create a drop:
45+
46+
<Github fname="lib.rs" language="rust"
47+
url="https://github.com/Festivemena/Near-drop/blob/main/contract/src/lib.rs"
48+
start="140" end="170" />
49+
50+
**The result**: Recipients can claim tokens without having NEAR accounts or paying gas!
51+
52+
---
53+
54+
## Key Permissions Breakdown
55+
56+
Function-call keys in NEAR Drop have strict limits:
57+
58+
<Github fname="lib.rs" language="rust"
59+
url="https://github.com/Festivemena/Near-drop/blob/main/contract/src/lib.rs"
60+
start="8" end="20" />
61+
62+
**What keys CAN do:**
63+
- Call `claim_for` to claim to existing accounts
64+
- Call `create_account_and_claim` to create new accounts
65+
- Use up to 0.005 NEAR worth of gas
66+
67+
**What keys CANNOT do:**
68+
- Transfer tokens from the contract
69+
- Call any other functions
70+
- Deploy contracts or change state maliciously
71+
- Exceed their gas allowance
72+
73+
---
74+
75+
## Key Lifecycle
76+
77+
The lifecycle is simple and secure:
78+
79+
```
80+
1. CREATE → Add key with limited permissions
81+
2. SHARE → Give private key to recipient
82+
3. CLAIM → Recipient uses key to claim tokens
83+
4. CLEANUP → Remove key after use (prevents reuse)
84+
```
85+
86+
Here's the cleanup code:
87+
88+
<Github fname="claim.rs" language="rust"
89+
url="https://github.com/Festivemena/Near-drop/blob/main/contract/src/claim.rs"
90+
start="200" end="220" />
91+
92+
---
93+
94+
## Advanced Key Patterns
95+
96+
### Time-Limited Keys
97+
98+
You can make keys that expire:
99+
100+
<Github fname="lib.rs" language="rust"
101+
url="https://github.com/Festivemena/Near-drop/blob/main/contract/src/lib.rs"
102+
start="300" end="330" />
103+
104+
### Key Rotation
105+
106+
For extra security, you can rotate keys:
107+
108+
<Github fname="lib.rs" language="rust"
109+
url="https://github.com/Festivemena/Near-drop/blob/main/contract/src/lib.rs"
110+
start="350" end="380" />
111+
112+
---
113+
114+
## Security Best Practices
115+
116+
**✅ DO:**
117+
- Use minimal gas allowances (0.005 NEAR is plenty)
118+
- Remove keys immediately after use
119+
- Validate key formats before adding
120+
- Monitor key usage patterns
121+
122+
**❌ DON'T:**
123+
- Give keys excessive gas allowances
124+
- Reuse keys for multiple drops
125+
- Skip cleanup after claims
126+
- Log private keys anywhere
127+
128+
---
129+
130+
## Gas Usage Monitoring
131+
132+
Track how much gas your keys use:
133+
134+
<Github fname="lib.rs" language="rust"
135+
url="https://github.com/Festivemena/Near-drop/blob/main/contract/src/lib.rs"
136+
start="400" end="420" />
137+
138+
---
139+
140+
## Integration with Frontend
141+
142+
Your frontend can generate keys securely:
143+
144+
<Github fname="crypto.js" language="javascript"
145+
url="https://github.com/Festivemena/Drop/blob/main/src/utils/crypto.js"
146+
start="1" end="30" />
147+
148+
Create claim URLs:
149+
150+
<Github fname="crypto.js" language="javascript"
151+
url="https://github.com/Festivemena/Drop/blob/main/src/utils/crypto.js"
152+
start="32" end="45" />
153+
154+
---
155+
156+
## Troubleshooting Common Issues
157+
158+
**"Access key not found"**
159+
- Key wasn't added properly to the contract
160+
- Key was already used and cleaned up
161+
- Check the public key format
162+
163+
**"Method not allowed"**
164+
- Trying to call a function not in the allowed methods list
165+
- Our keys only allow `claim_for` and `create_account_and_claim`
166+
167+
**"Insufficient allowance"**
168+
- Key ran out of gas budget
169+
- Increase `FUNCTION_CALL_ALLOWANCE` if needed
170+
171+
**"Key already exists"**
172+
- Trying to add a duplicate key
173+
- Generate new unique keys for each drop
174+
175+
---
176+
177+
## Why This Matters
178+
179+
Function-call access keys are NEAR's superpower for user experience:
180+
181+
🎯 **No Onboarding Friction**: New users can interact immediately
182+
⚡ **Gasless Operations**: Recipients don't pay anything
183+
🔒 **Still Secure**: Keys have minimal, specific permissions
184+
🚀 **Scalable**: Works for any number of recipients
185+
186+
This is what makes NEAR Drop possible - without function-call keys, you'd need a completely different (and much more complex) approach.
187+
188+
---
189+
190+
## Next Steps
191+
192+
Now that you understand how the gasless magic works, let's see how to create new NEAR accounts during the claiming process.
193+
194+
[Continue to Account Creation →](./account-creation.md)
195+
196+
---
197+
198+
:::tip Key Insight
199+
Function-call access keys are like giving someone a specific key to your house that only opens one room and only works once. It's secure, limited, and perfect for token distribution!
200+
:::

‎docs/tutorials/neardrop/account-creation.md

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
---
2+
id: account-creation
3+
title: Account Creation
4+
sidebar_label: Account Creation
5+
description: "Enable new users to create NEAR accounts automatically when claiming their first tokens."
6+
---
7+
8+
import Tabs from '@theme/Tabs';
9+
import TabItem from '@theme/TabItem';
10+
import {Github} from "@site/src/components/codetabs"
11+
12+
The ultimate onboarding experience: users can claim tokens AND get a NEAR account created for them automatically. No existing account required!
13+
14+
---
15+
16+
## The Magic of NEAR Account Creation
17+
18+
Most blockchains require you to have an account before you can receive tokens. NEAR flips this around:
19+
20+
**Traditional Flow:**
21+
1. Create wallet → Fund with tokens → Receive more tokens
22+
23+
**NEAR Drop Flow:**
24+
1. Get private key → Claim tokens → Account created automatically ✨
25+
26+
This eliminates the biggest barrier to Web3 adoption.
27+
28+
---
29+
30+
## How It Works
31+
32+
Account creation happens in two phases:
33+
34+
### Phase 1: Create the Account
35+
<Github fname="claim.rs" language="rust"
36+
url="https://github.com/Festivemena/Near-drop/blob/main/contract/src/claim.rs"
37+
start="40" end="60" />
38+
39+
### Phase 2: Claim the Tokens
40+
<Github fname="claim.rs" language="rust"
41+
url="https://github.com/Festivemena/Near-drop/blob/main/contract/src/claim.rs"
42+
start="62" end="75" />
43+
44+
If account creation succeeds, we proceed with the normal claiming process. If it fails (account already exists), we try to claim anyway.
45+
46+
---
47+
48+
## Implementation
49+
50+
Add this to your `src/claim.rs`:
51+
52+
<Github fname="claim.rs" language="rust"
53+
url="https://github.com/Festivemena/Near-drop/blob/main/contract/src/claim.rs"
54+
start="10" end="80" />
55+
56+
Validate account ID format:
57+
58+
<Github fname="claim.rs" language="rust"
59+
url="https://github.com/Festivemena/Near-drop/blob/main/contract/src/claim.rs"
60+
start="100" end="140" />
61+
62+
Calculate funding based on drop type:
63+
64+
<Github fname="claim.rs" language="rust"
65+
url="https://github.com/Festivemena/Near-drop/blob/main/contract/src/claim.rs"
66+
start="142" end="160" />
67+
68+
---
69+
70+
## Account Naming Strategies
71+
72+
### User-Chosen Names
73+
74+
Let users pick their own account names:
75+
76+
<Github fname="claim.rs" language="rust"
77+
url="https://github.com/Festivemena/Near-drop/blob/main/contract/src/claim.rs"
78+
start="180" end="220" />
79+
80+
### Deterministic Names
81+
82+
Or generate predictable names from keys:
83+
84+
<Github fname="claim.rs" language="rust"
85+
url="https://github.com/Festivemena/Near-drop/blob/main/contract/src/claim.rs"
86+
start="240" end="280" />
87+
88+
---
89+
90+
## Frontend Integration
91+
92+
Make account creation seamless in your UI:
93+
94+
<Github fname="ClaimDrop.js" language="javascript"
95+
url="https://github.com/Festivemena/Drop/blob/main/src/components/ClaimDrop.js"
96+
start="50" end="120" />
97+
98+
---
99+
100+
## Testing Account Creation
101+
102+
```bash
103+
# Test creating new account and claiming
104+
near call drop-test.testnet create_named_account_and_claim '{
105+
"preferred_name": "alice-new"
106+
}' --accountId drop-test.testnet \
107+
--keyPair <private-key-here>
108+
109+
# Check if account was created
110+
near view alice-new.testnet state
111+
112+
# Verify balance includes claimed tokens
113+
near view alice-new.testnet account
114+
```
115+
116+
---
117+
118+
## Error Handling
119+
120+
Handle common issues gracefully:
121+
122+
<Github fname="claim.rs" language="rust"
123+
url="https://github.com/Festivemena/Near-drop/blob/main/contract/src/claim.rs"
124+
start="300" end="350" />
125+
126+
---
127+
128+
## Cost Considerations
129+
130+
Account creation costs depend on the drop type:
131+
132+
<Github fname="lib.rs" language="rust"
133+
url="https://github.com/Festivemena/Near-drop/blob/main/contract/src/lib.rs"
134+
start="450" end="480" />
135+
136+
---
137+
138+
## Frontend Account Creation Flow
139+
140+
Add account creation options to your claiming interface:
141+
142+
<Github fname="AccountCreationForm.js" language="javascript"
143+
url="https://github.com/Festivemena/Drop/blob/main/src/components/AccountCreationForm.js"
144+
start="1" end="80" />
145+
146+
---
147+
148+
## What You've Accomplished
149+
150+
Amazing! You now have:
151+
152+
✅ **Automatic account creation** during claims
153+
✅ **Flexible naming strategies** (user-chosen or deterministic)
154+
✅ **Robust error handling** for edge cases
155+
✅ **Cost optimization** based on drop types
156+
✅ **Seamless UX** that removes Web3 barriers
157+
158+
This is the complete onboarding solution - users go from having nothing to owning a NEAR account with tokens in a single step!
159+
160+
---
161+
162+
## Real-World Impact
163+
164+
Account creation enables powerful use cases:
165+
166+
🎯 **Mass Onboarding**: Bring thousands of users to Web3 instantly
167+
🎁 **Gift Cards**: Create accounts for family/friends with token gifts
168+
📱 **App Onboarding**: New users get accounts + tokens to start using your dApp
169+
🎮 **Gaming**: Players get accounts + in-game assets automatically
170+
🏢 **Enterprise**: Employee onboarding with company tokens
171+
172+
You've eliminated the biggest friction point in Web3 adoption!
173+
174+
---
175+
176+
## Next Steps
177+
178+
With gasless claiming and automatic account creation working, it's time to build a beautiful frontend that makes this power accessible to everyone.
179+
180+
[Continue to Frontend Integration →](./frontend.md)
181+
182+
---
183+
184+
:::tip Pro Tip
185+
Always provide enough initial funding for the account type. FT drops need more funding because recipients might need to register on multiple FT contracts later.
186+
:::

0 commit comments

Comments
 (0)