A Cardano NFT marketplace contract including chain indexer and event listener for individual projects.
-
Deno
$\ge$ Version 1.28.3 -
Aiken (
cargo install --git https://github.com/aiken-lang/aiken.git --rev 3c97f057ccb23183b6b4194f8ac20ff0bb395403)
- Import
ContractandLucidand create royalty/fee token. Note: The ideal way to handle the royalty token is to have it under the samepolicy idas the collection. This will make the authentication process smoother and more efficient. However, Nebula allows for specifying a differentpolicy idif necessary. If you have a royalty token already you can skip the step of the royalty token creation.
import { Contract } from "https://deno.land/x/[email protected]/contract/mod.ts" // TODO
import { Lucid, Blockfrost } from "https://deno.land/x/[email protected]/mod.ts"
const lucid = await Lucid.new(
new Blockfrost(
"https://cardano-preprod.blockfrost.io/api/v0",
"<project_id>",
),
"Preprod",
);
lucid.selectWalletFromSeed(
"<seed_phrase>",
);
const owner = "addr...";
const txHash = await Contract.createRoyalty(
lucid,
[{
recipient:
"addr...",
fee: 0.016, // 1.6%
}],
owner,
);
console.log(txHash);This creates a unique royalty token and sends it to a script address controlled by the owner. The output contains the royalty/fee information. After calling Contract.createRoyalty(..) you should see a message in the terminal including the royalty token. Paste it into the Contract config as described in the next step.
- Instantiate the contract and deploy reference scripts.
const contract = new Contract(lucid, {
royaltyToken: "<royalty_token>",
owner, // Make sure you use the same owner here as in Contract.createRoyalty(..)!
policyId: "<policy_id_of_your_nft_project>",
});
console.log(await contract.deployScripts());After calling contract.deployScripts() you should see a message in the terminal including the tx hash of the deployment of the scripts. Paste it into the Contract config as described in the next step.
- Re-instantiate the contract with reference scripts.
const contract = new Contract(lucid, {
royaltyToken: "<royalty_token>",
owner, // Make sure you use the same owner here as the one in Contract.createRoyalty(..)!
policyId: "<policy_id_of_your_nft_project>",
deployTxHash: "<deploy_tx_hash>",
});Now the contract is initialised.
Make sure you don't change the configuration as it could change the script hashes!
Time to play with the marketplace!
Place a bid (on SpaceBud #10):
console.log(await contract.bid([idToBud(10)], 5000000000n));Accept bid (sell):
const [bid] = await contract.getBids(idToBud(10));
console.log(await contract.sell([{ bidUtxo: bid }]));List an NFT (SpaceBud #10):
console.log(await contract.list([idToBud(10)], 6000000000n));Buy:
const [listing] = await contract.getListings(idToBud(10));
console.log(await contract.buy([listing]));Place a floor/open bid with optional constraints (this only works if your NFT is CIP-0068 compliant):
console.log(
await contract.bidOpen(10000000000n, {
types: ["Bear"],
traits: [{ trait: "Hockey Stick" }],
}),
);Accept open bid (with SpaceBud #650 as it is a Bear and has a Hockey Stick):
const [bid] = await contract.getBids("Open");
console.log(await contract.sell([{ bidUtxo: bid, assetName: idToBud(650) }]));And much more is possible!
If you want to keep track of historic data or want to index marketplace data or want to listen to certain events, then you may want to run the watcher.
It is not a requirement to run the core of the marketplace.
-
Deno
$\ge$ Version 1.28.3 -
Ogmios
$\ge$ Version 5.5.7 - Active connection to a Cardano node with Ogmios as bridge.
- Set up the
config.tsfile:
Tip: Call contract.getContractHashes() on your Contract instance to get all the relevant hashes you need for the config.
import {
BidAndListingEventData,
BidOpenEventData,
BidSwapEventData,
Config,
MarketplaceEvent,
SaleEventData,
} from "https://deno.land/x/[email protected]/watcher/src/types.ts";
/**
* Run 'contract.getContractHashes()' on your Contract instance to get all the relevant hashes you need for the config.
*/
export const config: Config = {
scriptHash: "<script_hash>",
bidPolicyId: "<bid_policy_id>",
projects: ["<nft_policy_id>"],
};
// optionally handle events
export function eventsHandler(events: MarketplaceEvent[]) {
for (const event of events) {
switch (event.type) {
case "BidBundle": {
const eventData: BidAndListingEventData = event.data;
// Your logic here
break;
}
case "BidOpen": {
const eventData: BidOpenEventData = event.data;
// Your logic here
break;
}
case "BidSingle": {
const eventData: BidAndListingEventData = event.data;
// Your logic here
break;
}
case "ListingBundle": {
const eventData: BidAndListingEventData = event.data;
// Your logic here
break;
}
case "ListingSingle": {
const eventData: BidAndListingEventData = event.data;
// Your logic here
break;
}
case "BuyBundle": {
const eventData: SaleEventData = event.data;
// Your logic here
break;
}
case "BuySingle": {
const eventData: SaleEventData = event.data;
// Your logic here
break;
}
case "SellBundle": {
const eventData: SaleEventData = event.data;
// Your logic here
break;
}
case "SellSingle": {
const eventData: SaleEventData = event.data;
// Your logic here
break;
}
case "SellSwap": {
const eventData: SaleEventData = event.data;
// Your logic here
break;
}
case "CancelBidBundle": {
const eventData: BidAndListingEventData = event.data;
// Your logic here
break;
}
case "CancelBidOpen": {
const eventData: BidOpenEventData = event.data;
// Your logic here
break;
}
case "CancelBidSingle": {
const eventData: BidAndListingEventData = event.data;
// Your logic here
break;
}
case "CancelListingBundle": {
const eventData: BidAndListingEventData = event.data;
// Your logic here
break;
}
case "CancelListingSingle": {
const eventData: BidAndListingEventData = event.data;
// Your logic here
break;
}
case "CancelBidSwap": {
const eventData: BidSwapEventData = event.data;
// Your logic here
break;
}
}
}
}
export function onChange() {
// optionally handle db changes
}- Start the watcher:
deno run -A https://deno.land/x/[email protected]/watcher/mod.ts --ogmios-url ws://localhost:1337 --database ./marketplace.sqlite --config ./config.ts
Run the querier:
deno run -A https://deno.land/x/[email protected]/watcher/querier.ts --database ./marketplace.sqlite
Runs on port 3000 by default. It hosts the database and allows you to make simple queries. The API will likely be extended and improved over time.
To execute the below listed commands you need to be in the contract directory.
deno task build:contract
deno task build
Outputs a dist folder at ./contract/dist.
deno task test
deno task test:contract
The ideal way to handle the royalty token is to have it under the same policy id as the collection. This will make the authentication process smoother and more efficient. However, Nebula allows for specifying a different policy id if necessary.
The asset name must be 001f4d70526f79616c7479 (hex encoded), it contains the CIP-0067 label 500.
The royalty info datum is specified as follows (CDDL):
big_int = int / big_uint / big_nint
big_uint = #6.2(bounded_bytes)
big_nint = #6.3(bounded_bytes)
optional_big_int = #6.121([big_int]) / #6.122([])
royalty_recipient = #6.121([
address, ; definition can be derived from:
; https://github.com/input-output-hk/plutus/blob/master/plutus-ledger-api/src/PlutusLedgerApi/V1/Address.hs#L31
int, ; fee
optional_big_int, ; min fee
optional_big_int, ; max fee
])
royalty_recipients = [ * royalty_recipient ]
version = 1 ; version is of type int, we start with version 1
royalty_info = #6.121([royalty_recipients, version])
To take advantage of collection offers with constraints, your NFT collection needs to comply with CIP-0068. The metadata must contain two additional key/value pairs (CDDL):
{
...
type => bounded_bytes,
traits => [ * bounded_bytes ]
}
Example (JSON):
{
"image": "ipfs://..",
"name": "SpaceBud #650",
"type": "Bear",
"traits": ["Chestplate", "Belt"]
}Nebula charges by default a protocol fee for each sale, which is currently about 0.9 ADA (the minimum ADA by protocol parameters and it is adjusted automatically when the protocol parameters change). We appreciate all support to fund the development of Nebula. If you want to disable the protocol fee set the flag fundProtocol to false when instantiating the Contract.
- Improve and extend documentation.
- Make the Nebula contract also available on NPM as official package.