|
| 1 | +--- |
| 2 | +id: near-drop |
| 3 | +title: Near Drop |
| 4 | +--- |
| 5 | + |
| 6 | +import Tabs from '@theme/Tabs'; |
| 7 | +import TabItem from '@theme/TabItem'; |
| 8 | +import {CodeTabs, Language, Github} from "@site/src/components/codetabs" |
| 9 | + |
| 10 | +NEAR Drop is a smart contract that allows users to create token drops ($NEAR, Fungible and Non-Fungible Tokens), and link them to specific private keys. Whoever has the private key can claim the drop into an existing account, or ask the contract to create a new one for them. |
| 11 | + |
| 12 | +Particularly, it shows: |
| 13 | + |
| 14 | +1. How to create a token drops (NEAR, FT and NFT) |
| 15 | +2. How to leverage Function Call keys for enabling amazing UX |
| 16 | + |
| 17 | +:::tip |
| 18 | + |
| 19 | +This example showcases a simplified version of the contract that both [Keypom](https://keypom.xyz/) and the [Token Drop Utility](https://dev.near.org/tools?tab=linkdrops) use to distribute tokens to users |
| 20 | + |
| 21 | +::: |
| 22 | + |
| 23 | +--- |
| 24 | + |
| 25 | +## Contract Overview |
| 26 | + |
| 27 | +The contract exposes 3 methods to create drops of NEAR tokens, FT, and NFT. To claim the tokens, the contract exposes two methods, one to claim in an existing account, and another that will create a new account and claim the tokens into it. |
| 28 | + |
| 29 | +This contract leverages NEAR unique feature of [FunctionCall keys](../../1.concepts/protocol/access-keys.md), which allows the contract to create new accounts and claim tokens on behalf of the user. |
| 30 | + |
| 31 | +Imagine Alice want to drop some NEAR to Bob: |
| 32 | + |
| 33 | +1. Alice will call `create_near_drop` passing some NEAR amount, and a **Public** Access Key |
| 34 | +2. The Contract will check if Alice attached enough tokens and create the drop |
| 35 | +3. The Contract will add the `PublicKey` as a `FunctionCall Key` to itself, that **only allow to call the claim methods** |
| 36 | +4. Alice will give the `Private Key` to Bob |
| 37 | +5. Bob will use the Key to sign a transaction calling the `claim_for` method |
| 38 | +6. The Contract will check if the key is linked to a drop, and if it is, it will send the drop |
| 39 | + |
| 40 | +It is important to notice that, in step (5), Bob will be using the Contract's account to sign the transaction, and not his own account. Remember that in step (3) the contract added the key to itself, meaning that anyone with the key can call the claim methods in the name of the contract. |
| 41 | + |
| 42 | +<details> |
| 43 | + |
| 44 | +<summary>Contract's interface</summary> |
| 45 | + |
| 46 | +#### `create_near_drop(public_keys, amount_per_drop)` |
| 47 | +Creates `#public_keys` drops, each with `amount_per_drop` NEAR tokens on them |
| 48 | + |
| 49 | +#### `create_ft_drop(public_keys, ft_contract, amount_per_drop)` |
| 50 | +Creates `#public_keys` drops, each with `amount_per_drop` FT tokens, corresponding to the `ft_contract` |
| 51 | + |
| 52 | +#### `create_nft_drop(public_key, nft_contract)` |
| 53 | +Creates a drop with an NFT token, which will come from the `nft_contract` |
| 54 | + |
| 55 | +#### `claim_for(account_id)` |
| 56 | +Claims a drop, which will be sent to the existing `account_id` |
| 57 | + |
| 58 | +#### `create_account_and_claim(account_id)` |
| 59 | +Creates the `account_id`, and then drops the tokens into it |
| 60 | + |
| 61 | +</details> |
| 62 | + |
| 63 | +--- |
| 64 | + |
| 65 | +## Contract's State |
| 66 | + |
| 67 | +We can see in the contract's state that the contract keeps track of different `PublicKeys`, and links them to a specific `DropId`, which is simply an identifier for a `Drop` (see bellow). |
| 68 | + |
| 69 | +- `top_level_account`: The account that will be used to create new accounts, generally it will be `testnet` or `mainnet` |
| 70 | +- `next_drop_id`: A simple counter used to assign unique identifiers to each drop |
| 71 | +- `drop_id_by_key`: A `Map` between `PublicKey` and `DropId`, which allows the contract to know what drops are claimable by a given key |
| 72 | +- `drop_by_id`: A simple `Map` that links each `DropId` with the actual `Drop` data. |
| 73 | + |
| 74 | +<Github fname="lib.rs" language="rust" |
| 75 | + url="https://github.com/near-examples/near-drop/blob/main/src/lib.rs" |
| 76 | + start="22" end="29" /> |
| 77 | + |
| 78 | +--- |
| 79 | + |
| 80 | +## Drop Types |
| 81 | + |
| 82 | +There are 3 types of drops, which differ in what the user will receive when they claims the corresponding drop - NEAR, fungible tokens (FTs) or non-fungible tokens (NFTs). |
| 83 | + |
| 84 | +<Language value="rust" language="rust"> |
| 85 | +<Github fname="drop_types.rs" |
| 86 | + url="https://github.com/near-examples/near-drop/blob/main/src/drop_types.rs" |
| 87 | + start="8" end="16" /> |
| 88 | +<Github fname="near_drop.rs" |
| 89 | + url="https://github.com/near-examples/near-drop/blob/main/src/near_drop.rs" |
| 90 | + start="9" end="16" /> |
| 91 | +<Github fname="ft_drop.rs" |
| 92 | + url="https://github.com/near-examples/near-drop/blob/main/src/ft_drop.rs" |
| 93 | + start="16" end="24" /> |
| 94 | +<Github fname="nft_drop.rs" |
| 95 | + url="https://github.com/near-examples/near-drop/blob/main/src/nft_drop.rs" |
| 96 | + start="15" end="22" /> |
| 97 | +</Language> |
| 98 | + |
| 99 | +:::info |
| 100 | + |
| 101 | +Notice that in this example implementation users cannot mix drops. This is, you can either drop NEAR tokens, or FT, or NFTs, but not a mixture of them (i.e. you cannot drop 1 NEAR token and 1 FT token in the same drop) |
| 102 | + |
| 103 | +::: |
| 104 | + |
| 105 | +--- |
| 106 | + |
| 107 | +## Create a drop |
| 108 | + |
| 109 | +All `create` start by checking that the user deposited enough funds to create the drop, and then proceed to add the access keys to the contract's account as [FunctionCall Keys](../../1.concepts/protocol/access-keys.md). |
| 110 | + |
| 111 | +<Tabs> |
| 112 | + |
| 113 | + <TabItem value="NEAR" label="NEAR Drop"> |
| 114 | + <Language value="rust" language="rust"> |
| 115 | + <Github fname="create_near_drop" |
| 116 | + url="https://github.com/near-examples/near-drop/blob/main/src/lib.rs" |
| 117 | + start="44" end="66" /> |
| 118 | + <Github fname="near_drop" |
| 119 | + url="https://github.com/near-examples/near-drop/blob/main/src/near_drop.rs" |
| 120 | + start="63" end="95" /> |
| 121 | + </Language> |
| 122 | + </TabItem> |
| 123 | + <TabItem value="FT" label="FT Drop"> |
| 124 | + <Language value="rust" language="rust"> |
| 125 | + <Github fname="create_ft_drop" |
| 126 | + url="https://github.com/near-examples/near-drop/blob/main/src/lib.rs" |
| 127 | + start="68" end="89" /> |
| 128 | + <Github fname="ft_drop" |
| 129 | + url="https://github.com/near-examples/near-drop/blob/main/src/ft_drop.rs" |
| 130 | + start="108" end="142" /> |
| 131 | + </Language> |
| 132 | + </TabItem> |
| 133 | + <TabItem value="NFT" label="NFT Drop"> |
| 134 | + <Language value="rust" language="rust"> |
| 135 | + <Github fname="create_nft_drop" |
| 136 | + url="https://github.com/near-examples/near-drop/blob/main/src/lib.rs" |
| 137 | + start="91" end="103" /> |
| 138 | + <Github fname="nft_drop" |
| 139 | + url="https://github.com/near-examples/near-drop/blob/main/src/nft_drop.rs" |
| 140 | + start="80" end="106" /> |
| 141 | + </Language> |
| 142 | + </TabItem> |
| 143 | +</Tabs> |
| 144 | + |
| 145 | +<hr class="subsection" /> |
| 146 | + |
| 147 | +### Storage Costs |
| 148 | + |
| 149 | +While we will not go into the details of how the storage costs are calculated, it is important to know what is being taken into account: |
| 150 | + |
| 151 | +1. The cost of storing each Drop, which will include storing all bytes associated with the `Drop` struct |
| 152 | +2. The cost of storing each `PublicKey -> DropId` relation in the maps |
| 153 | +3. Cost of storing each `PublicKey` in the account |
| 154 | + |
| 155 | +Notice that (3) is not the cost of storing the byte representation of the `PublicKey` on the state, but the cost of adding the key to the contract's account as a FunctionCall key. |
| 156 | + |
| 157 | +--- |
| 158 | + |
| 159 | +## Claim a drop |
| 160 | + |
| 161 | +In order to claim drop, a user needs to sign a transaction using the `Private Key`, which is the counterpart of the `Public Key` that was added to the contract. |
| 162 | + |
| 163 | +All `Drops` have a `counter` which decreases by 1 each time a drop is claimed. This way, when all drops are claimed (`counter` == 0), we can remove all information from the Drop. |
| 164 | + |
| 165 | +There are two ways to claim a drop: claim for an existing account and claim for a new account. The main difference between them is that the first one will send the tokens to an existing account, while the second one will create a new account and send the tokens to it. |
| 166 | + |
| 167 | +<hr class="subsection" /> |
| 168 | + |
| 169 | +<Tabs> |
| 170 | + <TabItem value="existing" label="Existing Account"> |
| 171 | + <Language value="rust" language="rust"> |
| 172 | + <Github fname="claim_for" |
| 173 | + url="https://github.com/near-examples/near-drop/blob/main/src/claim.rs" |
| 174 | + start="11" end="14" /> |
| 175 | + <Github fname="internal_claim" |
| 176 | + url="https://github.com/near-examples/near-drop/blob/main/src/claim.rs" |
| 177 | + start="58" end="85" /> |
| 178 | + </Language> |
| 179 | + </TabItem> |
| 180 | + <TabItem value="new" label="New Account"> |
| 181 | + <Language value="rust" language="rust"> |
| 182 | + <Github fname="create_account_and_claim" |
| 183 | + url="https://github.com/near-examples/near-drop/blob/main/src/claim.rs" |
| 184 | + start="16" end="41" /> |
| 185 | + <Github fname="resolve_account_create" |
| 186 | + url="https://github.com/near-examples/near-drop/blob/main/src/claim.rs" |
| 187 | + start="43" end="56" /> |
| 188 | + <Github fname="internal_claim" |
| 189 | + url="https://github.com/near-examples/near-drop/blob/main/src/claim.rs" |
| 190 | + start="58" end="85" /> |
| 191 | + </Language> |
| 192 | + </TabItem> |
| 193 | +</Tabs> |
| 194 | + |
| 195 | +--- |
| 196 | + |
| 197 | +### Testing the Contract |
| 198 | + |
| 199 | +The contract readily includes a sandbox testing to validate its functionality. To execute the tests, run the following command: |
| 200 | + |
| 201 | +<Tabs groupId="code-tabs"> |
| 202 | + <TabItem value="rust" label="🦀 Rust"> |
| 203 | + |
| 204 | + ```bash |
| 205 | + cargo test |
| 206 | + ``` |
| 207 | + |
| 208 | + </TabItem> |
| 209 | +</Tabs> |
| 210 | + |
| 211 | +:::tip |
| 212 | +The `integration tests` use a sandbox to create NEAR users and simulate interactions with the contract. |
| 213 | +::: |
| 214 | + |
| 215 | +--- |
| 216 | + |
| 217 | +### Deploying the Contract to the NEAR network |
| 218 | + |
| 219 | +In order to deploy the contract you will need to create a NEAR account. |
| 220 | + |
| 221 | +<Tabs groupId="cli-tabs"> |
| 222 | + <TabItem value="short" label="Short"> |
| 223 | + |
| 224 | + ```bash |
| 225 | + # Create a new account pre-funded by a faucet |
| 226 | + near create-account <accountId> --useFaucet |
| 227 | + ``` |
| 228 | + </TabItem> |
| 229 | + |
| 230 | + <TabItem value="full" label="Full"> |
| 231 | + |
| 232 | + ```bash |
| 233 | + # Create a new account pre-funded by a faucet |
| 234 | + near account create-account sponsor-by-faucet-service <my-new-dev-account>.testnet autogenerate-new-keypair save-to-keychain network-config testnet create |
| 235 | + ``` |
| 236 | + </TabItem> |
| 237 | +</Tabs> |
| 238 | + |
| 239 | +Then build and deploy the contract: |
| 240 | + |
| 241 | +```bash |
| 242 | +cargo near build |
| 243 | + |
| 244 | +cargo near deploy <accountId> with-init-call new json-args '{"top_level_account": "testnet"}' prepaid-gas '100.0 Tgas' attached-deposit '0 NEAR' network-config testnet sign-with-keychain send |
| 245 | +``` |
| 246 | + |
| 247 | +--- |
| 248 | + |
| 249 | +### CLI: Interacting with the Contract |
| 250 | + |
| 251 | +To interact with the contract through the console, you can use the following commands: |
| 252 | + |
| 253 | +<Tabs groupId="cli-tabs"> |
| 254 | + <TabItem value="short" label="Short"> |
| 255 | + |
| 256 | + ```bash |
| 257 | + # create a NEAR drop |
| 258 | + near call <account-id> create_near_drop '{"public_keys": ["ed25519:AvBVZDQrg8pCpEDFUpgeLYLRGUW8s5h57NGhb1Tc4H5q", "ed25519:4FMNvbvU4epP3HL9mRRefsJ2tMECvNLfAYDa9h8eUEa4"], "amount_per_drop": "10000000000000000000000"}' --accountId <account-id> --deposit 1 --gas 100000000000000 |
| 259 | + |
| 260 | + # create a FT drop |
| 261 | + near call <account-id> create_ft_drop '{"public_keys": ["ed25519:HcwvxZXSCX341Pe4vo9FLTzoRab9N8MWGZ2isxZjk1b8", "ed25519:5oN7Yk7FKQMKpuP4aroWgNoFfVDLnY3zmRnqYk9fuEvR"], "amount_per_drop": "1", "ft_contract": "<ft-contract-account-id>"}' --accountId <account-id> --gas 100000000000000 |
| 262 | + |
| 263 | + # create a NFT drop |
| 264 | + near call <account-id> create_nft_drop '{"public_key": "ed25519:HcwvxZXSCX341Pe4vo9FLTzoRab9N8MWGZ2isxZjk1b8", "nft_contract": "<nft-contract-account-id>"}' --accountId <account-id> --gas 100000000000000 |
| 265 | + |
| 266 | + # claim to an existing account |
| 267 | + # see the full version |
| 268 | + |
| 269 | + # claim to a new account |
| 270 | + # see the full version |
| 271 | + ``` |
| 272 | + </TabItem> |
| 273 | + |
| 274 | + <TabItem value="full" label="Full"> |
| 275 | + |
| 276 | + ```bash |
| 277 | + # create a NEAR drop |
| 278 | + near contract call-function as-transaction <account-id> create_near_drop json-args '{"public_keys": ["ed25519:AvBVZDQrg8pCpEDFUpgeLYLRGUW8s5h57NGhb1Tc4H5q", "ed25519:4FMNvbvU4epP3HL9mRRefsJ2tMECvNLfAYDa9h8eUEa4"], "amount_per_drop": "10000000000000000000000"}' prepaid-gas '100.0 Tgas' attached-deposit '1 NEAR' sign-as <account-id> network-config testnet sign-with-keychain send |
| 279 | + |
| 280 | + # create a FT drop |
| 281 | + near contract call-function as-transaction <account-id> create_ft_drop json-args '{"public_keys": ["ed25519:HcwvxZXSCX341Pe4vo9FLTzoRab9N8MWGZ2isxZjk1b8", "ed25519:5oN7Yk7FKQMKpuP4aroWgNoFfVDLnY3zmRnqYk9fuEvR"], "amount_per_drop": "1", "ft_contract": "<ft-contract-account-id>"}' prepaid-gas '100.0 Tgas' attached-deposit '0 NEAR' sign-as <account-id> network-config testnet sign-with-keychain send |
| 282 | + |
| 283 | + # create a NFT drop |
| 284 | + near contract call-function as-transaction <account-id> create_nft_drop json-args '{"public_key": "ed25519:HcwvxZXSCX341Pe4vo9FLTzoRab9N8MWGZ2isxZjk1b8", "nft_contract": "<nft-contract-account-id>"}' prepaid-gas '100.0 Tgas' attached-deposit '0 NEAR' sign-as <account-id> network-config testnet sign-with-keychain send |
| 285 | + |
| 286 | + # claim to an existing account |
| 287 | + near contract call-function as-transaction <account-id> claim_for json-args '{"account_id": "<claimer-account-id>"}' prepaid-gas '30.0 Tgas' attached-deposit '0 NEAR' sign-as <account-id> network-config testnet sign-with-plaintext-private-key --signer-public-key ed25519:AvBVZDQrg8pCpEDFUpgeLYLRGUW8s5h57NGhb1Tc4H5q --signer-private-key ed25519:3yVFxYtyk7ZKEMshioC3BofK8zu2q6Y5hhMKHcV41p5QchFdQRzHYUugsoLtqV3Lj4zURGYnHqMqt7zhZZ2QhdgB send |
| 288 | + |
| 289 | + # claim to a new account |
| 290 | + near contract call-function as-transaction <account-id> create_account_and_claim json-args '{"account_id": "<claimer-account-id>"}' prepaid-gas '100.0 Tgas' attached-deposit '0 NEAR' sign-as <account-id> network-config testnet sign-with-plaintext-private-key --signer-public-key ed25519:4FMNvbvU4epP3HL9mRRefsJ2tMECvNLfAYDa9h8eUEa4 --signer-private-key ed25519:2xZcegrZvP52VrhehvApnx4McL85hcSBq1JETJrjuESC6v6TwTcr4VVdzxaCReyMCJvx9V4X1ppv8cFFeQZ6hJzU send |
| 291 | + ``` |
| 292 | + </TabItem> |
| 293 | +</Tabs> |
| 294 | + |
| 295 | +:::note Versioning for this article |
| 296 | + |
| 297 | +At the time of this writing, this example works with the following versions: |
| 298 | + |
| 299 | +- near-cli: `0.17.0` |
| 300 | +- rustc: `1.82.0` |
| 301 | + |
| 302 | +::: |
0 commit comments