Package: ruleslabs-core
Rules protocolCore smart contracts of the Rules protocol.for marketplace contracts, seemarketplacerepository.for pack opening contracts, seepack-openerrepository.OverviewRules protocol is composed of 4 contracts interacting with each other.RulesData,RulesCardsandRulesPacksare responsible for all the logic and data storage.RulesTokensimplements the ERC-1155 standard, and uses other contracts logic to manage its tokens.RulesDataRulesDatais responsible for holding the most basic informations, currently its only utility is to store artists names.@externalscreateArtist:Create an artists if it does not already exist.parametersartist_name: Uint256: the artist name (must be at most 27 characters long)RulesCardsRulesCardhandles cards, their scarcities, their supply and can be used to stop the production for the given scarcity level of a season.cards, card models, scarcities and seasonsA card is a struct composed like bellow, and the main purpose of this contract is to store cards.struct Card:
  member model: CardModel
  member serial_number: felt # uint24
end

struct CardModel:
  member artist_name: Uint256
  member season: felt # uint8
  member scarcity: felt # uint8
endAs you can see, each card is associated to a card model, itself associated to a season and a scarcity level.Scarcity levels are used to control the max supply of a card model and exists in the context of a season, which means a scarcityncan have a different max supply from one season to another.
For each possible season, it exists by default the scarcity level0, the only scarcity level with an infinite max supply.@externalsaddScarcityForSeason:Add a new scarcity level to a given season.parametersseason: felt: the season for which to create the scarcity level.supply: felt: the max supply of the scarcity level to create.stopProductionForSeasonAndScarcity:Definitively Stop the production of new cards for the scarcity level of a given season.parametersseason: feltscarcity: feltcreateCardStore card informations in aUint256, and use it as a card identifier.
If the card informations are invalid, that the scarcity provided does not allow more card creation, or if the card already exists, the transaction will fail.parameterscard: Card:model: CardModel:artist_name: Uint256: must exist inRulesDataseason: felt: must be non null and fit in 8 bitsscarcity: felt: must fit in 8 bits, and exist in the given seasonserial_number: felt: must be non null and fit in 24 bitsreturn valuecard_id: Uint256the card identifierpackCardModelIncrease the packed supply of a card model, in other terms, the quantity of cards in packs. If not enough supply is available for the card model, or if the card model is invalid, the transaction will fail.parameterspack_card_model: PackCardModel:card_model: CardModelquantity: felt: the amount of cards to packRulesPacksPacks and common packsA pack is a list of card models with, optionally, a quantity for each card model, and a number of cards per minted pack. According to the card models quantities and the number of cards per pack, the contract will deduce the pack max supply.pack max supply = sum of card models quantities / number of cards per packGiven thatcards created with the scarcity level0have an unlimited max supply, it allows to create packs with only card models of scarcity level0, and so, to create packs with an unlimited max supply as well.We are calling these packscommon packscreatePackCreate a new pack with a deduced max supply, card models with any valid season and scarcity levels can be provided as long as the available supply of these card models is enough regarding to the pack card models quantitiesstruct PackCardModel:
  member card_model: CardModel
  member quantity: felt
endparameterscards_per_pack: feltpack_card_models: PackCardModel*metadata: Metadata: seemetadata sectionreturn valuepack_id: Uint256: id of the newly created pack. For packs with a limited max supply the nth created pack have the idUint256(low=n, high=0)createCommonPackCreate a new common pack, with all the present and future card models of scarcity level0of a given season.parameterscards_per_pack: feltseason: felt: must be a valid season and no other common pack of the same season must exist.metadata: Metadata: seemetadata sectionreturn valuepack_id: Uint256: id of the newly created pack. For common packs the id is such thatUint256(low=0, high=season)RulesTokensRulesTokenis the protocol's keystone, this ERC-1155 contract handles all the tokens logic.Rules tokens are indivisible, cards have a max supply of 1 (basically, it's NFTs), and packs have a max supply calculated by theRulesPackscontract.createAndMintCardCreate a card inRulesCardsand mint its associated token to the recipient address.parameterscard: Card: the card to create and mint, it must be unique and not minted yet.metadata: Metadata*: seemetadata section.to: felt: address to send the newly minted card token.openPackToPack opening is the mechanism by which a pack token will be burned andcards_per_packcard tokens will be minted.The transfer of cards to the recipient address is not safe, this is done to avoid a Reetrancy attack which could allow a malicious
contract to make the pack opening fail during the transfer acceptance check, if the selected cards does not suit it.Also, to ensure the impossibility of invalidating an opening transaction in progress, it is important to make sure that the pack
has been moved to a secure pack opening contract. See the pack opener contract atperipheryfor more information.parametersto: felt: address to send the newly minted cards.pack_id: felt: the id of the pack to open.cards: Card*: the cards to mint. LikecreateAndMintCarddoes, they will be created inRulesCardsfirst, then, corresponding card tokens will be minted.metadata: Metadata*: seemetadata section.MetadataAccess ControlLocal developmentCompile contractsnilecompilesrc/ruleslabs/contracts/Rules*/Rules*.cairo--directorysrcRun teststoxtests/test.pyDeploy contractsstarknetdeclareartifacts/RulesData.json
starknetdeclareartifacts/RulesCards.json
starknetdeclareartifacts/RulesPacks.json
starknetdeclareartifacts/RulesTokens.json

niledeployProxy[RULES_DATA_CLASS_HASH]niledeployRulesCards[RULES_CARDS_CLASS_HASH]niledeployRulesPacks[RULES_PACKS_CLASS_HASH]niledeployRulesTokens[RULES_TOKENS_CLASS_HASH]