======= This marketplace is published under MIT license, so you can clone an use it as you like, here are the instructions to run it and the info about the Varda project. If you need help setting up the project consider buying my NFTs here to get a free setup of the marketplace on your favourite hosting.
To run this project locally:
- Prerequisites: Make sure you've installed Node.js โฅ 12
- Install dependencies:
yarn install
- Run the local development server:
yarn dev
(seepackage.json
for a full list ofscripts
you can run withyarn
)
Now you'll have a local development environment backed by the NEAR TestNet!
Go ahead and play with the app and the code. As you make code changes, the app will automatically reload.
- The "backend" code lives in the
/contract
folder. See the README there for more info. - The frontend code lives in the
/src
folder./src/index.html
is a great place to start exploring. Note that it loads in/src/index.js
, where you can learn how the frontend connects to the NEAR blockchain. - Tests: there are different kinds of tests for the frontend and the smart
contract. See
contract/README
for info about how it's tested. The frontend code gets tested with jest. You can run both of these at once withyarn run test
.
Every smart contract in NEAR has its own associated account. When you run yarn dev
, your smart contract gets deployed to the live NEAR TestNet with a throwaway account. When you're ready to make it permanent, here's how.
near-cli is a command line interface (CLI) for interacting with the NEAR blockchain. It was installed to the local node_modules
folder when you ran yarn install
, but for best ergonomics you may want to install it globally:
yarn install --global near-cli
Or, if you'd rather use the locally-installed version, you can prefix all near
commands with npx
Ensure that it's installed with near --version
(or npx near --version
)
Each account on NEAR can have at most one contract deployed to it. If you've already created an account such as your-name.testnet
, you can deploy your contract to nft-mint-frontend.your-name.testnet
. Assuming you've already created an account on NEAR Wallet, here's how to create nft-mint-frontend.your-name.testnet
:
-
Authorize NEAR CLI, following the commands it gives you:
near login
-
Create a subaccount (replace
YOUR-NAME
below with your actual account name):near create-account nft-mint-frontend.YOUR-NAME.testnet --masterAccount YOUR-NAME.testnet
Modify the line in src/config.js
that sets the account name of the contract. Set it to the account id you used above.
const CONTRACT_NAME = process.env.CONTRACT_NAME || 'nft-mint-frontend.YOUR-NAME.testnet'
One command:
yarn deploy
As you can see in package.json
, this does two things:
- builds & deploys smart contract to NEAR TestNet
- builds & deploys frontend code to GitHub using gh-pages. This will only work if the project already has a repository set up on GitHub. Feel free to modify the
deploy
script inpackage.json
to deploy elsewhere.
near call $NFT_CONTRACT_ID new_default_meta '{"owner_id": "'$NFT_CONTRACT_ID'"}' --accountId $NFT_CONTRACT_ID
Step 5: remember to allow minting to the artists near account for them to be able to mint
near call $NFT_CONTRACT_ID allow_minting_access '{"account_id": "xxx.near"}' --accountId $NFT_CONTRACT_ID
And on the allowlist constant in app.js line 53
thanks to Ben Kurrek for his contribution to this part of the code.
On Windows, if you're seeing an error containing EPERM
it may be related to spaces in your path. Please see this issue for more details.
4f7a76af9674e39c244036d8c80c7beeee5f9bca
Using the PoC backbone for NFT Marketplaces on NEAR Protocol.
- add stNEAR as a trading ft
- implement Narwallet with Varda Vault NEARNFT dispay for unlockable content
- basic purchase of NFT with FT
- demo pay out royalties (FTs and NEAR)
- test and determine standards for markets (best practice?) to buy/sell NFTs (finish standard) with FTs (already standard)
- demo some basic auction types, secondary markets and
- frontend example
- first pass / internal audit
- connect with bridged tokens e.g. buy and sell with wETH/nDAI (or whatever we call these)
- add ability to migrate NFT to ethereum blockchain using rainbowbridge/aurora
High level diagram of NFT sale on Market using Fungible Token:
Remove the FT steps for NEAR transfers (but nft_transfer_payout and resolve_purchase still the same).
Differences from nft-simple
NFT standard reference implementation:
- anyone can mint an NFT
- Optional token_type
- capped supply by token_type
- lock transfers by token_token
- enumerable.rs
Frontend App Demo: /test/app.test.js/
- install, deploy, test
yarn && yarn test:deploy
- run app -
yarn start
App Tests: /test/app.test.js/
- install, deploy, test
yarn && yarn test:deploy
- if you update contracts -
yarn test:deploy
- if you update tests only -
yarn test
Associated Video Demos (most recent at top)
Some additional ideas around user onboarding:
Install Rust https://rustup.rs/
- Install near-cli:
npm i -g near-cli
- Create testnet account: Wallet
- Login:
near login
- Install everything:
yarn && (cd server && yarn)
- Deploy the contract and run the app tests:
yarn test:deploy
- (WIP) Start server and run server tests:
cd server && yarn start
then in another terminal from the rootyarn test:server
- If you ONLY change the JS tests use
yarn test
. - If you change the contract run
yarn test:deploy
again. - If you run out of funds in the dev account run
yarn test:deploy
again. - If you change the dev account (yarn test:deploy) the server should restart automatically, but you may need to restart the app and sign out/in again with NEAR Wallet.
There's 3 main areas to explore:
- frontend app - shows how to create guest accounts that are added to the app contract via the nodejs server. Guests can mind NFTs, put them up for sale and earn NEAR tokens. When the guest has NEAR they can upgrade their account to a full account.
- app.test.js (demos frontend only tests)
The tests are set up to auto generate the dev account each time you run test:deploy
e.g. you will get a new NFT contract address each time you run a test.
This is just for testing. You can obviously deploy a token to a fixed address on testnet / mainnet, it's an easy config update.
When you run app / server tests. There's a contract deployed and a special account created guests.OWNER_ACCOUNT_ID
to manage the sponsored users (the ones you will pay for gas fees while onboarding). This special "guests" account is different from the test guest account bob.TOKEN_ID.OWNER_ACCOUNT_ID
. It is an account, different from the owner or token accounts, that manages the guests keys.
The guest users can claim_drop, ft_transfer_guest
and receive tokens from other users, e.g. in the server tests the owner transfers tokens to the guest account via API call and using client side code.
Then, following the server tests, the guest transfers tokens to alice (who is a real NEAR account e.g. she pays her own gas).
Finally, the guest upgrades themselves to a real NEAR account, something demoed in the video.
It's a lot to digest but if you focus on the /test/app.test.js
you will start to see the patterns.
One of the issues with onboarding new users to crypto is that they need to have crypto to do anything e.g. mint an NFT. A creator, artist or community might want to drop a bunch of free minting options to their fans for them to mint user generated content, but the audience has (1) no crypto to pay for fees (2) no wallet (3) no concept of crypto or blockchain; prior to the drop.
So let's solve these issues by allowing users to generate content the traditional Web2 way!
We do a demo of creating a "guest" named account for an app where the gas fees are sponsored by a special app account called "guests.APP_NAME.near". The guest account doesn't exist (sometimes called a virtual or contract account) until the user creates and sells and NFT that generates some NEAR tokens and then they can upgrade to a real account. Until then their name is reserved because only the app is able to create "USERNAME.APP_NAME.near".
This has many advantages for user onboarding, where users can use the app immediately and later can be upgraded to a full account. The users also don't have to move any assets - namely the fungible tokens they earned as a guest user.
Beyond having npm and node (latest versions), you should have Rust installed. I recommend nightly because living on the edge is fun.
Also recommend installing near-cli globally
npm i -g near-cli
Everything else can be installed via:
yarn
cd server && yarn
There is only one config.js file found in src/config.js
, this is also used for running tests.
Using src/config.js
you can set up your different environments. Use REACT_APP_ENV
to switch environments e.g. in package.json
script deploy
.
You can run unit tests in the Rust contracts themselves, but it may be more useful to JS tests against testnet itself.
Note: to run the app and server tests make sure you install and start the server.
- cd server
- yarn && yarn start
Commands:
test
will simply run app tests against the contract already deployed. You can mess around withapp.test.js
and try different frontend stufftest:deploy
- will deploy a new dev account (/neardev
) and deploy a new contract to this account, then runtest
test:server
- will test the server, make sure you start it (see "Note" above)test:unit
- runs the rust unit tests
If you've changed your contract or your dev account has run out of funds use test:deploy
, if you're updating your JS tests only then use test
.
There are helpers in test/test-utils.js
that take care of:
- creating a near connection and establishing a keystore for the dev account
- creating test accounts each time a test is run
- establishing a contract instance so you can call methods
You can change the default funding amount for test accounts in src/config.js
In src/state/near.js
you will see that src/config.js
is loaded as a function. This is to satisfy the jest/node test runner.
You can destructure any properies of the config easily in any module you import it in like this:
// example file app.js
import getConfig from '../config';
export const {
GAS,
networkId, nodeUrl, walletUrl, nameSuffix,
contractName,
} = getConfig();
Note the export const in the destructuring?
Now you can import these like so:
//example file Component.js
import { GAS } from '../app.js'
...
await contract.withdraw({ amount: parseNearAmount('1') }, GAS)
...
- Bundled with Parcel 2.0 (@next) && eslint
- Minimal all-in-one state management with async/await support
The following steps describe how to use
src/utils/state
to create and use your ownstore
andStateProvider
.
- Create a file e.g.
/state/app.js
and add the following code
import { State } from '../utils/state';
// example
const initialState = {
app: {
mounted: false
}
};
export const { store, Provider } = State(initialState);
- Now in your
index.js
wrap yourApp
component with theStateProvider
import { Provider } from './state/app';
ReactDOM.render(
<Provider>
<App />
</Provider>,
document.getElementById('root')
);
- Finally in
App.js
you canuseContext(store)
const { state, dispatch, update } = useContext(store);
<p>Hello {state.foo && state.foo.bar.hello}</p>
const handleClick = () => {
update('clicked', !state.clicked);
};
const onMount = () => {
dispatch(onAppMount('world'));
};
useEffect(onMount, []);
When a function is called using dispatch, it expects arguments passed in to the outer function and the inner function returned to be async with the following json args: { update, getState, dispatch }
Example of a call:
dispatch(onAppMount('world'));
All dispatched methods and update calls are async and can be awaited. It also doesn't matter what file/module the functions are in, since the json args provide all the context needed for updates to state.
For example:
import { helloWorld } from './hello';
export const onAppMount = (message) => async ({ update, getState, dispatch }) => {
update('app', { mounted: true });
update('clicked', false);
update('data', { mounted: true });
await update('', { data: { mounted: false } });
console.log('getState', getState());
update('foo.bar', { hello: true });
update('foo.bar', { hello: false, goodbye: true });
update('foo', { bar: { hello: true, goodbye: false } });
update('foo.bar.goodbye', true);
await new Promise((resolve) => setTimeout(() => {
console.log('getState', getState());
resolve();
}, 2000));
dispatch(helloWorld(message));
};
The default names the State
factory method returns are store
and Provider
. However, if you want multiple stores and provider contexts you can pass an additional prefix
argument to disambiguate.
export const { appStore, AppProvider } = State(initialState, 'app');
The updating of a single store, even several levels down, is quite quick. If you're worried about components re-rendering, use memo
:
import React, { memo } from 'react';
const HelloMessage = memo(({ message }) => {
console.log('rendered message');
return <p>Hello { message }</p>;
});
export default HelloMessage;
Higher up the component hierarchy you might have:
const App = () => {
const { state, dispatch, update } = useContext(appStore);
...
const handleClick = () => {
update('clicked', !state.clicked);
};
return (
<div className="root">
<HelloMessage message={state.foo && state.foo.bar.hello} />
<p>clicked: {JSON.stringify(state.clicked)}</p>
<button onClick={handleClick}>Click Me</button>
</div>
);
};
When the button is clicked, the component HelloMessage will not re-render, it's value has been memoized (cached). Using this method you can easily prevent performance intensive state updates in further down components until they are neccessary.
Reference: