Donation
Our donation example enables to forward NEAR Tokens to an account while keeping track of it. It is one of the simplest examples on making a contract handle tranfers.
Frontend of the Donation App
Obtaining the Donation Exampleโ
You have two options to start the Donation Example.
- You can use the app through
Github Codespaces, which will open a web-based interactive environment. - Clone the repository locally and use it from your computer.
| Codespaces | Clone locally |
|---|---|
 | ๐ https://github.com/near-examples/donation-examples.git |
Structure of the Exampleโ
The example is divided in two main components:
- The smart contract, available in two flavors: rust and javascript
- The frontend, that interacts with an already deployed contract.
- ๐ JavaScript
- ๐ฆ Rust
โโโ sandbox-ts # sandbox testing
โ โโโ src
โ โ โโโ main.ava.ts
โ โโโ ava.config.cjs
โ โโโ package.json
โโโ src # contract's code
โ โโโ contract.ts
โ โโโ model.ts
โ โโโ utils.ts
โโโ package.json # package manager
โโโ README.md
โโโ tsconfig.json # test script
โโโ tests # workspaces testing
โ โโโ workspaces.rs
โโโ src # contract's code
โ โโโ donation.rs
โ โโโ lib.rs
โโโ Cargo.toml # package manager
โโโ README.md
โโโ rust-toolchain.toml
Frontendโ
The donation example includes a frontend that interacts with an already deployed smart contract, allowing user to donate NEAR tokens to a faucet service.
Running the Frontendโ
To start the frontend you will need to install the dependencies and start the server.
cd frontend
yarn
yarn dev
Go ahead and login with your NEAR account. If you don't have one, you will be able to create one in the moment. Once logged in, input the amount of NEAR you want to donate and press the donate button. You will be redirected to the NEAR Wallet to confirm the transaction. After confirming it, the donation will be listed in the "Latest Donations".
Understanding the Frontendโ
The frontend is a Next.JS project generated by create-near-app. Check DonationsTable.jsx and DonationsForm.jsx to understand how components are displayed and interacting with the contract.
- DonationsTable.jsx
- DonationsForm.jsx
Loading...
Loading...
An interesting aspect of the donation example is that it showcases how to retrieve a result after being redirected to the NEAR wallet to accept a transaction.
Smart Contractโ
The contract exposes methods to donate tokens (donate), and methods to retrieve the recorded donations (e.g. get_donation_for_account).
- ๐ Javascript
- ๐ฆ Rust
Loading...
Loading...
Testing the Contractโ
The contract readily includes a set of unit and sandbox testing to validate its functionality. To execute the tests, run the following commands:
- ๐ JavaScript
- ๐ฆ Rust
cd contract-ts
yarn
yarn test
cd contract-rs
cargo test
The integration tests use a sandbox to create NEAR users and simulate interactions with the contract.
Deploying the Contract to the NEAR networkโ
In order to deploy the contract you will need to create a NEAR account.
- Short
- Full
# Create a new account pre-funded by a faucet
near create-account <accountId> --useFaucet
# Create a new account pre-funded by a faucet
near account create-account sponsor-by-faucet-service <my-new-dev-account>.testnet autogenerate-new-keypair save-to-keychain network-config testnet create
Go into the directory containing the smart contract (cd contract-ts or cd contract-rs), build and deploy it:
cargo near build
cargo near deploy <accountId>
To interact with your contract from the frontend, simply replace the variable CONTRACT_NAME in the index.js file.
CLI: Interacting with the Contractโ
To interact with the contract through the console, you can use the following commands
Get donationsโ
- Short
- Full
near view donation.near-examples.testnet get_donations '{"from_index": "0","limit": "10"}'
near contract call-function as-read-only donation.near-examples.testnet get_donations json-args '{"from_index": "0","limit": "10"}' network-config testnet now
Get beneficiaryโ
- Short
- Full
near view donation.near-examples.testnet get_beneficiary
near contract call-function as-read-only donation.near-examples.testnet get_beneficiary json-args {} network-config testnet now
Get number of donorsโ
- Short
- Full
near view donation.near-examples.testnet number_of_donors
near contract call-function as-read-only donation.near-examples.testnet number_of_donors json-args {} network-config testnet now
Get donation for an accountโ
- Short
- Full
# Require accountId
near view donation.near-examples.testnet get_donation_for_account '{"account_id":<accountId>}'
# Require accountId
near contract call-function as-read-only donation.near-examples.testnet get_donation_for_account json-args '{"account_id":<accountId>}' network-config testnet now
Donate to the contractโ
- Short
- Full
# Replace <accountId> with your account ID
# Require deposit
near call donation.near-examples.testnet donate --accountId <accountId> --deposit 0.1
# Replace <accountId> with your account ID
# Require deposit
near contract call-function as-transaction donation.near-examples.testnet donate json-args {} prepaid-gas '30.0 Tgas' attached-deposit '0.1 NEAR' sign-as <accountId> network-config testnet sign-with-keychain send
If you're using your own account, replace donation.near-examples.testnet with your accountId.
Moving Forwardโ
A nice way to learn is by trying to expand a contract. Modify the donation example so it accumulates the tokens in the contract
instead of sending it immediately. Then, make a method that only the beneficiary can call to retrieve the tokens.
At the time of this writing, this example works with the following versions:
- near-cli:
4.0.13 - node:
18.19.1 - rustc:
1.77.0
