@tqtezos/minter-contracts

smart contracts tests using flextesa sandbox and taquito

Usage no npm install needed!

<script type="module">
  import tqtezosMinterContracts from 'https://cdn.skypack.dev/@tqtezos/minter-contracts';
</script>

README

Minter Contracts

The @tqtezos/minter-contracts package provides a collection of NFT and marketplace smart contracts with configurable admin permissions.

Provided Contracts

Minter Collection

Customizable smart contracts for minting FA2 NFTs as collections.

Editions FA2

The Editions variant of FA2 allows for the minting and distribution of many editions of an NFT that share the same metadata, but with unique identifiers (token_ids). The design of this contract also allows for the minting of many editions runs in O(n) (where n is the number of editions runs minted) and concurrent distribution of editions across multiple creators.

English Auction

An implementation of an English auction marketplace that allows users to initiate auctions of NFTs in either tez or FA2 tokens.

Fixed Price Sale

An implementation of an NFT marketplace that allows users to initiate NFT sales at a fixed price in tez or FA2. These contracts can be configured based on a range of administrative options.

FA2-FA2 swaps

An implementation of a swaps contract that allows two participants to safely exchange their FA2 tokens. There is an extension with allowlist that allows specifying the permitted set of FA2 contracts involved.

Ticket-based NFTs

EXPERIMENTAL An implementation of NFTs using tickets and a dutch auction example, along with wallet contracts for the NFTs. Please note: tickets are a new Tezos feature and care should be taken when using them as they have not been heavily tested in production.

Work-in-progress contracts

Meta-transaction based minting / sales (WIP)

Fractional Ownership (WIP)

Royalties and Profit-splitting (WIP)

JavaScript / TypeScript Package

The contracts are packaged into TypeScript modules and published to npm for use in JavaScript / TypeScript projects.

Package Installation

with npm

npm i @tqtezos/minter-contracts

with yarn

yarn add @tqtezos/minter-contracts

Architecture

Contract Code (for origination)

The code for each contract is exported directly from the @tqtezos/minter-contracts package.

The naming convention used for contract code exports is:

${TitleCasedContractName}Code

Where {TitleCasedContractName} denotes an interpolation of the title-cased name of any particular contract.

For example, to access the code for the fa2_swap contract, one would import:

import { Fa2SwapCode } from '@tqtezos/minter-contracts';

Contract import type shape

Each exported contract code object is wrapped in a special unique type to make it easy to inspect at runtime or with the type system, if necessary.

This type has the following shape:

export declare const ${TitleCasedContractName}Code: {
  __type: ${TitleCasedContractName};
  protocol: string;
  code: object[];
};

Note, this isn't valid TypeScript.

Inspecting the type of the imported Fa2SwapCode object from above, it has the following shape:

export declare const Fa2SwapCode: {
  __type: 'Fa2SwapCode';
  protocol: string;
  code: object[];
};

The raw Michelson code is available at the .code property.

import { Fa2SwapCode } from '@tqtezos/minter-contracts';

// Log the contract's Michelson code
console.log(Fa2SwapCode.code);

Contract Signatures

This package exports additional types representing the signature of any particular contract.

The naming convention for these types is similar to the code import.

${TitleCasedContractName}ContractType

Again, our fa2_swap contract example:

import type { Fa2SwapContractType } from '@tqtezos/minter-contracts'

This type will provide type information about the methods and storage on the contract:

export declare type Fa2SwapContractType = {
  methods: Methods;
  storage: Storage;
  code: {
    __type: 'Fa2SwapCode';
    protocol: string;
    code: object[];
  };
};

Where Methods and Storage represent the unique shape of the contract's entrypoints and storage, respectively.

Network Client

This particular package solely exports smart contract code – it doesn't assume any particular Tezos client. As such, one will need to pick their favorite JavaScript / TypeScript Tezos client to actually interact with the contracts on the Tezos network. We recommend the @taquito/taquito package.

Example usage with taquito

import { Fa2SwapCode } from '@tqtezos/minter-contracts';
import { TezosToolkit } from '@taquito/taquito';

const tezos = new TezosToolkit('https://YOUR_PREFERRED_RPC_URL');
tezos.contract.originate({
  code: Fa2SwapCode.code,
  // ...
});

See the @taquito/taquito package's documentation for more information on interacting with the taquito package.

Local Development (Contributing)

Prerequisites

You'll need these.

Package Scripts

Package scripts are managed and invoked by yarn.

yarn compile-ligo [filter]

Compile LIGO contracts to Michelson.

Accepts an optional filter which compiles only those contracts matching the given filter string.

E.g.,

yarn compile-ligo fa2_swap

If no filter is given, all contracts will be compiled.

Arguments

Argument Position Description Required
[filter] 0 Compile only contracts matcing the given filter string πŸ”˜

Options

Option Alias Description Required
-s --src-path LIGO source path πŸ”˜
-o --out-path Michelson output path πŸ”˜

One may also pass the help command to see a list of options in their terminal.

yarn compile-ligo help

This script delegates LIGO compilation to docker β€” ensure the docker daemon is running for it to execute correctly.

yarn generate-types

This will generate the contract types and code files in bin-ts

yarn generate-types

This script will not compile LIGO contracts beforehand. Be sure to execute yarn compile-ligo first if you need updated contract code.

yarn bootstrap

Bootstrap the network specified in ENV_NAME environment name. Check if the contract addresses in the config file are actually deployed on the network. If necessary, re-deploy compiled contracts and update the config file.

yarn bootstrap-sandbox

Bootstrap flextesa sandbox network.

yarn bootstrap-testnet

Bootstrap flextesa test network.