getgems nft-contracts: the TON contracts behind a working NFT marketplace

A contract registry, with code hashes as the index

The unusual thing about this repository is that the README reads less like documentation and more like a registry of deployed contracts. Each entry lists a source file, the code hash in both base64 and hex, the compiled code cell constant, the storage format builder, a testnet example, a mainnet example, and a contract description written in Russian.

That structure matters more than it first appears. On TON, a contract's code hash is a fingerprint of the compiled code, so listing it lets anyone confirm that the contract sitting at a given address is running the bytes the project intends. The current auction contract, for example, is listed with base64 code hash zlp4U06qps7tja/UhtB262CpsNbb+1Nnb2YmScBomVY= and the matching hex value ce5a78534eaaa6ceed8dafd486d076eb60a9b0d6dbfb53676f662649c0689956, alongside its source file, its compiled code constant NftAuctionV4R1CodeBoc and the storage builder buildNftAuctionV4R1DataCell.

The README also states a warning in both Russian and English about a specific contract address, saying it should not be used to put NFTs for sale, and that getgems is not responsible for users who use it for the purpose of deception. The English text adds the practical advice: to purchase an NFT directly from the blockchain you need to check the contract code and the correctness of the contract data. That is a small piece of advice with a large implication, and it is the reason the code hash listing matters.

The package is set as a monorepo of contract packages under packages/, with TypeScript as the primary language, and the MIT licence applies.

Standard items, marketplace, sale, offer, SBT and swap

The README lists what the collection covers. Standard NFT, collection, sale and marketplace implementations come with tests. There is a separate SBT implementation with tests, described in sbt.md. The getgems marketplace contract comes with tests, as do the getgems sale contract and the getgems single-NFT contract. A swap contract is documented in swap.md and also comes with tests. There is a raffle.md document in the repository root as well.

Sale contracts are split into two shapes. The auction family appears in a v4r1 revision, a v3r3 revision and a deprecated v3r2, while the fixed price family has a v4r1, a v3r3, a deprecated v3r2 and a deprecated v3. On top of those there is an offer contract, nft-offer-v1r3, listed with its own code hashes and its own storage format builder in NftOfferData.ts.

The versioning scheme is the notable part. Each revision gets its own source file, its own compiled code constant, and sometimes its own storage builder, which means upgrading a sale contract is not a configuration change but a switch between distinct deployed contracts. The v4r1 fixed price contract points at both NftFixpriceSaleV3.data.ts and NftFixPriceSaleV4.data.ts for its storage format, which tells you the storage layout itself was versioned alongside the code.

The deprecated entries are kept rather than deleted, each with its code hashes and an example address, so historical listings on chain can still be identified. That is a deliberate archival choice rather than an oversight, and it is the one behaviour in this repository that a user of a normal contract library would not expect.

The marketplace fee is five percent and the addresses are fixed

The economic parameters are stated once, near the top, and they are hardcoded to the marketplace operator rather than being left to the seller.

- marketplace royalty: 5% (marketplaceFeeFactor: 5, marketplaceFeeBase: 100)
- marketplaceFeeAddress: EQCjk1hh952vWaE9bRguFkAhDAL5jj3xj9p0uPWrFBq_GEMS
- marketplaceAddress: EQBYTuYbLf8INxFtD8tQeNk5ZLy-nAX9ahQbG_yl1qQ-GEMS

The fee is expressed as a factor over a base, five over one hundred, so the marketplace takes five percent. The two addresses are TON addresses ending in GEMS, one receiving the fee and one being the marketplace contract itself. Both are baked into the contract, so a seller cannot redirect them by editing their own call.

This is a meaningful design constraint for anyone who wants to reuse these contracts for a different marketplace. A five percent take is not adjustable from outside the code, and the addresses are constants. The README does not describe any parameter for overriding either, so treating these contracts as a general purpose foundation would mean forking the source rather than configuring it.

For a buyer, the corollary is the more useful side of the same fact. The fee and the marketplace address are known in advance, so the cost of a purchase through these contracts is predictable, and the code hash listing lets you confirm that the contract handling the sale is the one described here.

Testing runs on the TON sandbox with Jest and TypeScript

The contracts are written in FunC, the TON smart contract language, and the repository carries both the .func and .fc source files under packages/contracts/sources. The TypeScript side of the repository is the tooling around them, and that is where the test harness lives.

The root package.json is named nft-contracts at version 1.0.0, with the description GetGems NFT contracts and MIT as the licence. The test stack is Jest with ts-jest, alongside chai and mocha, and the repository has a jest.config.js and a tsconfig.json at the root. Two compiler toolchains are declared, @ton-community/func-js and @ton.org/func-js, and the execution environment is @ton/sandbox, with @ton/test-utils and ton-contract-executor also in the dependency list.

The runtime dependencies are what a project like this needs and nothing more: @ton/core, @ton/crypto and @ton/ton for the protocol types, bn.js and uuid for identifiers, and ton-compiler for building the code cells.

The practical structure to understand is that the tests are sandbox tests. The sandbox emulates a cell tree and lets a test drive a contract through a sequence of messages, which is what makes it possible to assert on the storage cell and the sent messages after a sale, an auction or an offer. The package.json does not define a test script, so the exact command to run the suite is not stated in the files provided.

What the README does claim for every listed contract is that it comes with tests. That claim is the one to lean on when judging whether a contract variant is production shaped, since the difference between the current and the deprecated entries is often not just a version number but the presence of a maintained test suite.

One warning about a specific address, and what it tells you to do

The README spends a paragraph on a single contract address, and the paragraph is unusual enough to deserve attention.

The address, EQAIFunALREOeQ99syMbO6sSzM_Fa1RsPD5TBoS0qVeKQ-AR, is named as one not to use to put NFTs for sale. The stated reason is that getgems is not responsible for users who use it for the purpose of deception. The sentence that follows is the practical instruction for buyers: to purchase an NFT directly from the blockchain, you need to check the contract code and the correctness of the contract data.

That instruction is the answer to a question the repository is otherwise not set up to answer. This is not a library with a documentation site and a versioned API; it is a set of contracts plus the fingerprints that let you identify them. The intended workflow for a buyer is to look up the address of the contract you are about to interact with, compare its code hash against the entries in the README, and if it does not match any listed contract, assume the worst.

The same discipline applies to the deprecated entries. A sale contract from the v3 line still exists on chain and can still hold assets. Its code hash is listed precisely so that a buyer can tell a v3 contract from a v4r1 one, and the v3 contracts are not the ones the marketplace currently supports.

This is also the clearest limitation of the repository as a resource. It is a set of artefacts for one marketplace, with hashes and links, and it does not attempt to be a general reference for how TON sale contracts should be designed, nor does it offer an audit. Anyone reusing a contract from here is reusing code on the basis of its hash and its tests, not on the basis of an external review.

Editorial conclusion

nft-contracts suits a team building on TON who needs a reference for how a production marketplace structures its sale contracts, or who needs to verify that a deployed contract matches a known code hash before interacting with it. It does not suit you as a generic NFT starter kit, because the collection is organised around one marketplace's own contract versions, and it does not replace an audit. Before you point anything at mainnet, compare the code hash of the contract you are calling against the hash listed for the version you intend to use, and check the marketplace fee parameters, since the royalty is set to 5 percent with the fee address and marketplace address both fixed to GEMS addresses in the repository.

Frequently asked questions

Official sources

1. getgems-io/nft-contracts on GitHub
2. Issues
3. License: MIT
4. README