Petyl¶
Petyl¶
Petyl is a token framework for revenue generating ventures
!! Documentation is currently under construction !!
Note
This project relies upon some knowledge about Solidity and the documentation assumes a basic familiarity with it. You may wish to view the Solidity docs if you have not used it previously.
Features¶
- Hybrid token structure - distinct asset classes combined with fungible tokens
- Token converters for converting between different classes
- Customisable rule engine for token transfers
- Different token types - Dividend tokens, vested tokens, options etc
- Contract testing via pytest, including trace-based coverage evaluation
- Property-based and stateful testing via hypothesis
Petyl Protocol¶
Petyl is designed to help value generating ventures grow.
It came from designing a collection of tokens for different purposes - yet all related to the same project. As the project grew, there were different types of incentives that were proposed to help us grow. Ultimately, we tokenised each of the incentives, and wrote some smart contracts with rules for redeeming each of the incentives. It has since been generalised to support a number of token types and use cases.
Petyl Framework¶
Petyl can best be described as a token framework for managing a collection of tokens relating to a value generating entity. We’ll call that entity a Tree
Tokens¶
This page provides a quick overview of Petyl. It relies mostly on examples and assumes a level of familiarity with smart contract dvelopment. For more in-depth content, you should read the documentation sections under “Getting Started” in the table of contents.
If you have any questions about the Petyl protocol, feel free to ask on Ethereum StackExchange or join us on Gitter.
Creating a New Token¶
You can visit the “Petyl Venture Studio”,
Partitions¶
The Petyl protocol is a framework for building hybrid tokens. One such token type is the Hybrid token.
Hybrid tokens¶
A hybrid token is a combination of distinct assets, like an ERC721, and fungible assets such as an ERC20. One common example is for company shares, where they all relate to ownership of the company, but different classes of shares, say founder shares have diffrerent conditions than regular shares.
We can build hybrid tokens with a main contract, the Petyl contract, with one or many partitions. Partitions are seperate tokens which relate to the same underlying asset but distinct from the different partitions.
Token types¶
Both the base token type and the dividend tokens can be added as partitions within the main Petyl contract.
Partitions ID¶
Each base token within the petyl protocol has a Partition ID when created. This is based on a hash and unique to each token deployed.
Converters¶
Converters can be connected to the main petyl contract. Depending on the tokens, the converter is able to mint and burn from one or more token contracts. This allows for both the creation and conversion of tokens.
Use Cases¶
- Founder tokens that vest over time.
- Migrating exisiting ERC20 tokens and converting them into Petyl tokens.
- Converting base tokens into dividend tokens
Adding Converters¶
Main contract owner can assign new converters for any of its underlying tokens. Only the Main Contract summoner is only able to add token converters. This is to ensure the security of the system. Testing is available for basic checks on token converters to ensure a 1 to 1 converting of tokens is kept true.
Converting Tokens¶
Token Rules¶
Base tokens have a smart contract hook which allows an arbitary set of rules be attached to the movement of those tokens. There are a number of use cases where this is interesting.
Examples¶
Restrict project founders from selling tokens before a set vesting date Limit tokens to be traded between employees or investors on a whitelist Automated compliance for specific asset types
Whitelists¶
Base tokens have a smart contract hook which allows an arbitary set of rules be attached to the movement of those tokens. As part of the rules, tokens can call on a token whitelist and return a true or false.
Documents¶
Petyl contracts are able to hold a list of document hashes for a variety of usecases.
The main usecase is to store founding contracts or documents relating to a project if required.
Notifications, announcements and disclosures are also covered in the publishing of documents
Documents can be stored directly onchain, IPFS or mapped to an external website address.
Token Types¶
There are a number of token types, both base tokens and various combinations
Base Tokens¶
Base token type is the foundation of the Petyl protocol. It is essentially an ERC20 with some advanced features from the ERC777 standard and some bonus code to make them work with the Petyl contract.
Functions¶
Full list of functions can be found in the Referrence docs.
Send vs Transfer¶
This is a naming convention from both ERC20 and ERC777 which is used to distinguish them. We have included both the Transfered and Sent events to comply with both standards.
Transfer with data¶
Certain use cases need addional data to be transfered along with token operations. We have included the transferWithData() function to support additional functionality both in sending and receiving tokens.
Operators¶
Token holders can assign an operator for repeated functionality. Any base token added to the Petyl contract will act as an operator for that token.
ERC1820 Registry¶
This is a key part of the ERC777 standard and used as a hook for additional functionality within the Petyl protocol.
Distribution Tokens¶
Distribution tokens are base tokens with additional functions to both keep track and distribute tokens to holders. Due to the internal accounting required to keep track of who is owed what amount, dividend tokens must be minted seperately to base tokens.
Functions¶
Full list of functions can be found in the Reference docs.
Deposit Dividends¶
Accepts up to 5 different ERC20 tokens as well as ETH Limited to a set number of ERC20 tokens in V1 due to gas constraints and security implications. Only the owner can add new ERC20 tokens to be accepted and paid out. Non approved tokens are not lock and can be transfered by the contract owner.
Withdraw Funds¶
Anyone can pull out the amount of tokens they have earnt over the time of holding a dividend token. Transfers are precomputed with dividends owing paid out first before sending to another party.
Ventures¶
The main component of the Petyl Protocol
Components¶
- Partitions
- Token Converters
- Documents
Partitions¶
Different tranches or classes of shares can be represented by seperate tokens, mapped by the main Petyl contract. The
Token Converters¶
Documents¶
The main Petyl contract for each new venture comes built in with Documents
Options¶
Time based conversions of tokens are made by creating a base token with rules and a token converter. The token rules can be as abitary or complex as written in Solidity. The user then calls the converter when these new options tokens meet the time based rules for transfer.
Examples include a tranch of founder shares which require 4 years vesting, which can be unlocked proportionally over time. Employee share offers are also possible with time based rules programmed in, with accounts checked off on a white list if conditions are met.
Dutch Auctions¶
We believe that the market should determine the price of a token rather than you or I. The Dutch Auction mechanism achieves this fairness for two main reasons. First, at every auction everyone who buys a token, buys it at the same price. Second, the market determines that price.
How a Dutch Auction Works¶
Every Dutch auction has a set amount of tokens available to be bought. The price is initially set at a high price and during the auction continues to drop. The price drops until either all the tokens are sold, or hits a minimum price.
Set Up¶
Each dutch auction is defined by a start and end time, starting and minimum token price and the number of tokens to be sold. From this, the linear pricing is determined auction begins automatically. Users are invited to contribute funds as soon as the start time begins.
More information¶
This work was inspired by both the Algorand and Gnosis dutch auctions. More details can be found here: Algo Auction We do not support the refund policy but may do so in the future.