diff --git a/components/sidebar/index.tsx b/components/sidebar/index.tsx index 0dfc1f6..0e075f7 100644 --- a/components/sidebar/index.tsx +++ b/components/sidebar/index.tsx @@ -29,10 +29,26 @@ const rootStyles = cva([ const contentStyles = cva(["w-2/3"]); const Sidebar = ({ map, onPageEntryClick, className }: SidebarProps) => { + const meta = map[0].kind === "Meta" ? map[0] : undefined; + + // This should never happen + if (!meta) return null; + + const sortedMap: PageMapItem[] = [meta]; + for (const childMeta of Object.keys(meta.data)) { + const foundChild = map.find((child) => { + const found = + (child.kind === "Folder" || child.kind === "MdxPage") && + child.name === childMeta; + return found; + }); + sortedMap.push(foundChild); + } + return (
-
+
); diff --git a/pages/_meta.json b/pages/_meta.json index c28890b..8875330 100644 --- a/pages/_meta.json +++ b/pages/_meta.json @@ -1,5 +1,7 @@ { - "index": "Welcome", - "protocol": "Protocol", - "using-the-dapp": "Using the dapp" + "index": "Welcome to Carrot documentation", + "about-carrot": "About Carrot", + "carrot-protocol": "Carrot protocol", + "for-the-campaign-creators": "For the campaign creators", + "for-the-users": "For the users" } diff --git a/pages/about-carrot/_meta.json b/pages/about-carrot/_meta.json new file mode 100644 index 0000000..b819669 --- /dev/null +++ b/pages/about-carrot/_meta.json @@ -0,0 +1,10 @@ +{ + "what-is-carrot": "What is Carrot?", + "how-does-carrot-work": "How does Carrot work?", + "technical-documentation": "Technical documentation", + "links-and-socials": "Links and socials", + "faq": "FAQ", + "carrot-dapp": "Carrot dapp", + "carrot-protocol": "Carrot protocol", + "carrot-templates": "Carrot templates" +} diff --git a/pages/about-carrot/carrot-dapp.mdx b/pages/about-carrot/carrot-dapp.mdx new file mode 100644 index 0000000..e69de29 diff --git a/pages/about-carrot/carrot-protocol.mdx b/pages/about-carrot/carrot-protocol.mdx new file mode 100644 index 0000000..e69de29 diff --git a/pages/about-carrot/carrot-templates.mdx b/pages/about-carrot/carrot-templates.mdx new file mode 100644 index 0000000..e69de29 diff --git a/pages/about-carrot/faq.mdx b/pages/about-carrot/faq.mdx new file mode 100644 index 0000000..e69de29 diff --git a/pages/protocol/kpi-tokens.mdx b/pages/about-carrot/how-does-carrot-work.mdx similarity index 100% rename from pages/protocol/kpi-tokens.mdx rename to pages/about-carrot/how-does-carrot-work.mdx diff --git a/pages/protocol/templates.mdx b/pages/about-carrot/links-and-socials.mdx similarity index 100% rename from pages/protocol/templates.mdx rename to pages/about-carrot/links-and-socials.mdx diff --git a/pages/protocol/oracles.mdx b/pages/about-carrot/technical-documentation.mdx similarity index 100% rename from pages/protocol/oracles.mdx rename to pages/about-carrot/technical-documentation.mdx diff --git a/pages/protocol/introduction.mdx b/pages/about-carrot/what-is-carrot.mdx similarity index 100% rename from pages/protocol/introduction.mdx rename to pages/about-carrot/what-is-carrot.mdx diff --git a/pages/carrot-protocol/_meta.json b/pages/carrot-protocol/_meta.json new file mode 100644 index 0000000..6f4f6be --- /dev/null +++ b/pages/carrot-protocol/_meta.json @@ -0,0 +1,7 @@ +{ + "introduction": "Introduction", + "how-does-carrot-work": "How does Carrot work?", + "what-are-templates": "What are templates?", + "what-are-kpi-token-templates": "What are KPI token templates?", + "what-are-oracle-templates": "What are oracle templates?" +} diff --git a/pages/carrot-protocol/how-does-carrot-work/_meta.json b/pages/carrot-protocol/how-does-carrot-work/_meta.json new file mode 100644 index 0000000..573f1d1 --- /dev/null +++ b/pages/carrot-protocol/how-does-carrot-work/_meta.json @@ -0,0 +1,6 @@ +{ + "index": "How does Carrot work?", + "what-are-goals-and-conditions": "What are goals and conditions?", + "what-is-a-collateral": "What is a collateral?", + "what-is-an-oracle": "What is an oracle?" +} diff --git a/pages/carrot-protocol/how-does-carrot-work/index.mdx b/pages/carrot-protocol/how-does-carrot-work/index.mdx new file mode 100644 index 0000000..8686b3c --- /dev/null +++ b/pages/carrot-protocol/how-does-carrot-work/index.mdx @@ -0,0 +1,38 @@ +--- +title: How does Carrot work +subtitle: Exploring the Features of the Carrot Orchestrator +--- + +The Carrot Orchestrator, as the base Carrot dApp, enables users to interact with +Carrot templates. It serves as an orchestrator for these templates, offering the +following key pages: + +## Homepage + +The homepage of the orchestrator consists of three distinct sections: + +- **Informative Video and Hero Section**: When no featured campaign is + present, the homepage showcases an explanatory video that highlights how + Carrot simplifies incentivization. +- **Featured Campaigns**: At times, the Carrot team may feature campaigns from + partners, which will be prominently displayed at the top of the homepage. +- **Latest Campaigns**: The subsequent section presents the five most recent + campaigns. These listings are continually updated, providing a quick + overview of ongoing activities in the Carrot ecosystem. +- **KPI Token Templates**: This section offers a selection of KPI token + templates that allow users to create campaigns. Note that the availability + of this section depends on whether multiple templates are deployed on the + network. If only one template is deployed, the section will not be visible + by default. + +## Campaigns Page + +The campaigns page provides a user-friendly interface to browse through created +campaigns. Users can optionally filter campaigns by state (active, expired, or +finalized) or search for specific text. Additionally, campaigns can be sorted in +ascending or descending order based on their creation dates. + +These two main pages form the core functionality of the Carrot Orchestrator. The +subsequent sections will delve into the details of interacting with the official +first-party Carrot templates, which users typically engage with the most on the +Carrot dApp. diff --git a/pages/carrot-protocol/how-does-carrot-work/what-are-goals-and-conditions.mdx b/pages/carrot-protocol/how-does-carrot-work/what-are-goals-and-conditions.mdx new file mode 100644 index 0000000..e69de29 diff --git a/pages/carrot-protocol/how-does-carrot-work/what-is-a-collateral.mdx b/pages/carrot-protocol/how-does-carrot-work/what-is-a-collateral.mdx new file mode 100644 index 0000000..e69de29 diff --git a/pages/carrot-protocol/how-does-carrot-work/what-is-an-oracle.mdx b/pages/carrot-protocol/how-does-carrot-work/what-is-an-oracle.mdx new file mode 100644 index 0000000..e69de29 diff --git a/pages/using-the-dapp/introduction.mdx b/pages/carrot-protocol/introduction.mdx similarity index 100% rename from pages/using-the-dapp/introduction.mdx rename to pages/carrot-protocol/introduction.mdx diff --git a/pages/carrot-protocol/what-are-kpi-token-templates/_meta.json b/pages/carrot-protocol/what-are-kpi-token-templates/_meta.json new file mode 100644 index 0000000..ad7fe97 --- /dev/null +++ b/pages/carrot-protocol/what-are-kpi-token-templates/_meta.json @@ -0,0 +1,5 @@ +{ + "index": "What are KPI token templates", + "erc20-kpi-token-template": "ERC20 KPI token template", + "creating-your-own-kpi-token-template": "Creating your own KPI token template" +} diff --git a/pages/carrot-protocol/what-are-kpi-token-templates/creating-your-own-kpi-token-template.mdx b/pages/carrot-protocol/what-are-kpi-token-templates/creating-your-own-kpi-token-template.mdx new file mode 100644 index 0000000..e69de29 diff --git a/pages/carrot-protocol/what-are-kpi-token-templates/erc20-kpi-token-template.mdx b/pages/carrot-protocol/what-are-kpi-token-templates/erc20-kpi-token-template.mdx new file mode 100644 index 0000000..e69de29 diff --git a/pages/carrot-protocol/what-are-kpi-token-templates/index.mdx b/pages/carrot-protocol/what-are-kpi-token-templates/index.mdx new file mode 100644 index 0000000..8a3adce --- /dev/null +++ b/pages/carrot-protocol/what-are-kpi-token-templates/index.mdx @@ -0,0 +1,38 @@ +--- +title: What are KPI token templates +subtitle: Exploring the Features of the Carrot Orchestrator +--- + +The Carrot Orchestrator, as the base Carrot dApp, enables users to interact with +Carrot templates. It serves as an orchestrator for these templates, offering the +following key pages: + +## Homepage + +The homepage of the orchestrator consists of three distinct sections: + +- **Informative Video and Hero Section**: When no featured campaign is + present, the homepage showcases an explanatory video that highlights how + Carrot simplifies incentivization. +- **Featured Campaigns**: At times, the Carrot team may feature campaigns from + partners, which will be prominently displayed at the top of the homepage. +- **Latest Campaigns**: The subsequent section presents the five most recent + campaigns. These listings are continually updated, providing a quick + overview of ongoing activities in the Carrot ecosystem. +- **KPI Token Templates**: This section offers a selection of KPI token + templates that allow users to create campaigns. Note that the availability + of this section depends on whether multiple templates are deployed on the + network. If only one template is deployed, the section will not be visible + by default. + +## Campaigns Page + +The campaigns page provides a user-friendly interface to browse through created +campaigns. Users can optionally filter campaigns by state (active, expired, or +finalized) or search for specific text. Additionally, campaigns can be sorted in +ascending or descending order based on their creation dates. + +These two main pages form the core functionality of the Carrot Orchestrator. The +subsequent sections will delve into the details of interacting with the official +first-party Carrot templates, which users typically engage with the most on the +Carrot dApp. diff --git a/pages/using-the-dapp/orchestrator.mdx b/pages/carrot-protocol/what-are-oracle-templates.mdx similarity index 100% rename from pages/using-the-dapp/orchestrator.mdx rename to pages/carrot-protocol/what-are-oracle-templates.mdx diff --git a/pages/carrot-protocol/what-are-templates.mdx b/pages/carrot-protocol/what-are-templates.mdx new file mode 100644 index 0000000..6a69f09 --- /dev/null +++ b/pages/carrot-protocol/what-are-templates.mdx @@ -0,0 +1,37 @@ +--- +subtitle: Exploring the Features of the Carrot Orchestrator +--- + +The Carrot Orchestrator, as the base Carrot dApp, enables users to interact with +Carrot templates. It serves as an orchestrator for these templates, offering the +following key pages: + +## Homepage + +The homepage of the orchestrator consists of three distinct sections: + +- **Informative Video and Hero Section**: When no featured campaign is + present, the homepage showcases an explanatory video that highlights how + Carrot simplifies incentivization. +- **Featured Campaigns**: At times, the Carrot team may feature campaigns from + partners, which will be prominently displayed at the top of the homepage. +- **Latest Campaigns**: The subsequent section presents the five most recent + campaigns. These listings are continually updated, providing a quick + overview of ongoing activities in the Carrot ecosystem. +- **KPI Token Templates**: This section offers a selection of KPI token + templates that allow users to create campaigns. Note that the availability + of this section depends on whether multiple templates are deployed on the + network. If only one template is deployed, the section will not be visible + by default. + +## Campaigns Page + +The campaigns page provides a user-friendly interface to browse through created +campaigns. Users can optionally filter campaigns by state (active, expired, or +finalized) or search for specific text. Additionally, campaigns can be sorted in +ascending or descending order based on their creation dates. + +These two main pages form the core functionality of the Carrot Orchestrator. The +subsequent sections will delve into the details of interacting with the official +first-party Carrot templates, which users typically engage with the most on the +Carrot dApp. diff --git a/pages/for-the-campaign-creators/_meta.json b/pages/for-the-campaign-creators/_meta.json new file mode 100644 index 0000000..433a2d0 --- /dev/null +++ b/pages/for-the-campaign-creators/_meta.json @@ -0,0 +1,4 @@ +{ + "benefits-of-using-carrot": "Benefits of using Carrot", + "how-to-create-a-campaign": "How to create a campaign?" +} diff --git a/pages/for-the-campaign-creators/benefits-of-using-carrot.mdx b/pages/for-the-campaign-creators/benefits-of-using-carrot.mdx new file mode 100644 index 0000000..23ef74a --- /dev/null +++ b/pages/for-the-campaign-creators/benefits-of-using-carrot.mdx @@ -0,0 +1,34 @@ +--- +subtitle: Get started with Carrot and what it's all about. +--- + +Carrot is a platform that enables flexible and efficient incentivization, +rewarding what really matters to you in a capital efficient way. Whether you're +a protocol or a single user, if you need to reach a goal by incentivizing a +certain behavior, Carrot can help. + +## How it works + +Incentivization in Carrot is enabled through what we call **KPI token +campaigns**. At a high level, **KPI token campaigns** are made up of the +following concepts: + +- **Goal**: each KPI token campaign defines a goal to be reached and for which + efficient incentivization is needed. +- **Condition**: the goal needs to be turned into a condition so that Carrot + can correctly assess if it was reached or not. This is a simple step that + will be described in more details later in the documentation. +- **Collateral(s)**: collaterals are the rewards given out to the campaign + participants if the goal is reached. Logic related to collateral(s) + unlocking is template-specific (the concept of templates is addressed later + in the docs). +- **KPI tokens**: KPI tokens represent a claim to all or part of the + collateral whenever the goal is either fully reached or partially reached. +- **Oracle(s)**: oracles are used in Carrot to relay condition outcomes + on-chain from the real world once they are known, allowing for the + finalization of the KPI token campaign. + +Some of these concepts are on-chain entities and implemented through the use of +templates, which enables Carrot to be extremely flexible in implementing +incentivization strategies that work great for every possible use case. The +concept of templates is expanded in the next section. diff --git a/pages/for-the-campaign-creators/how-to-create-a-campaign.mdx b/pages/for-the-campaign-creators/how-to-create-a-campaign.mdx new file mode 100644 index 0000000..f0177f3 --- /dev/null +++ b/pages/for-the-campaign-creators/how-to-create-a-campaign.mdx @@ -0,0 +1,16 @@ +--- +title: KPI tokens +subtitle: KPI tokens implement incentivization strategies. +--- + +KPI tokens and their templates are the main piece of logic in Carrot, the ones +that have full control over the incentivization strategies. + +They represent on-chain the condition that the user wants to incentivize and the +collateral(s) it can take. They have attached oracles that relay information to +them regarding condition outcomes. + +Based on these outcomes, they can freely decide what to do about the +collateral(s) and where to allocate it. + +In this sense, KPI tokens are the heart of any KPI token campaign. diff --git a/pages/for-the-users/_meta.json b/pages/for-the-users/_meta.json new file mode 100644 index 0000000..632cf77 --- /dev/null +++ b/pages/for-the-users/_meta.json @@ -0,0 +1,4 @@ +{ + "what-is-a-carrot-token": "What is a Carrot token?", + "how-to-redeem-the-collateral": "How to redeem the collateral?" +} diff --git a/pages/for-the-users/how-to-redeem-the-collateral.mdx b/pages/for-the-users/how-to-redeem-the-collateral.mdx new file mode 100644 index 0000000..f0177f3 --- /dev/null +++ b/pages/for-the-users/how-to-redeem-the-collateral.mdx @@ -0,0 +1,16 @@ +--- +title: KPI tokens +subtitle: KPI tokens implement incentivization strategies. +--- + +KPI tokens and their templates are the main piece of logic in Carrot, the ones +that have full control over the incentivization strategies. + +They represent on-chain the condition that the user wants to incentivize and the +collateral(s) it can take. They have attached oracles that relay information to +them regarding condition outcomes. + +Based on these outcomes, they can freely decide what to do about the +collateral(s) and where to allocate it. + +In this sense, KPI tokens are the heart of any KPI token campaign. diff --git a/pages/for-the-users/what-is-a-carrot-token.mdx b/pages/for-the-users/what-is-a-carrot-token.mdx new file mode 100644 index 0000000..23ef74a --- /dev/null +++ b/pages/for-the-users/what-is-a-carrot-token.mdx @@ -0,0 +1,34 @@ +--- +subtitle: Get started with Carrot and what it's all about. +--- + +Carrot is a platform that enables flexible and efficient incentivization, +rewarding what really matters to you in a capital efficient way. Whether you're +a protocol or a single user, if you need to reach a goal by incentivizing a +certain behavior, Carrot can help. + +## How it works + +Incentivization in Carrot is enabled through what we call **KPI token +campaigns**. At a high level, **KPI token campaigns** are made up of the +following concepts: + +- **Goal**: each KPI token campaign defines a goal to be reached and for which + efficient incentivization is needed. +- **Condition**: the goal needs to be turned into a condition so that Carrot + can correctly assess if it was reached or not. This is a simple step that + will be described in more details later in the documentation. +- **Collateral(s)**: collaterals are the rewards given out to the campaign + participants if the goal is reached. Logic related to collateral(s) + unlocking is template-specific (the concept of templates is addressed later + in the docs). +- **KPI tokens**: KPI tokens represent a claim to all or part of the + collateral whenever the goal is either fully reached or partially reached. +- **Oracle(s)**: oracles are used in Carrot to relay condition outcomes + on-chain from the real world once they are known, allowing for the + finalization of the KPI token campaign. + +Some of these concepts are on-chain entities and implemented through the use of +templates, which enables Carrot to be extremely flexible in implementing +incentivization strategies that work great for every possible use case. The +concept of templates is expanded in the next section. diff --git a/pages/index.mdx b/pages/index.mdx index 85f74a8..3636d68 100644 --- a/pages/index.mdx +++ b/pages/index.mdx @@ -1,5 +1,5 @@ --- -title: Welcome +title: Welcome to Carrot documentation subtitle: Learn how the Carrot protocol makes tokenized incentivization possible. --- diff --git a/pages/protocol/_meta.json b/pages/protocol/_meta.json deleted file mode 100644 index e46f9c4..0000000 --- a/pages/protocol/_meta.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "introduction": "Introduction", - "templates": "Templates", - "oracles": "Oracles", - "kpi-tokens": "KPI tokens" -} diff --git a/pages/using-the-dapp/_meta.json b/pages/using-the-dapp/_meta.json deleted file mode 100644 index a96fe2e..0000000 --- a/pages/using-the-dapp/_meta.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "introduction": "Introduction", - "orchestrator": "Orchestrator", - "kpi-token-templates": "KPI token templates", - "oracle-templates": "Oracle templates" -} diff --git a/pages/using-the-dapp/kpi-token-templates/_meta.json b/pages/using-the-dapp/kpi-token-templates/_meta.json deleted file mode 100644 index 405ae48..0000000 --- a/pages/using-the-dapp/kpi-token-templates/_meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "erc20": "ERC20" -} \ No newline at end of file diff --git a/pages/using-the-dapp/kpi-token-templates/erc20/_meta.json b/pages/using-the-dapp/kpi-token-templates/erc20/_meta.json deleted file mode 100644 index 236c83b..0000000 --- a/pages/using-the-dapp/kpi-token-templates/erc20/_meta.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "index": "ERC20 KPI token template", - "creation": "Creation", - "interaction": "Interaction" -} diff --git a/pages/using-the-dapp/kpi-token-templates/erc20/creation.mdx b/pages/using-the-dapp/kpi-token-templates/erc20/creation.mdx deleted file mode 100644 index 780a503..0000000 --- a/pages/using-the-dapp/kpi-token-templates/erc20/creation.mdx +++ /dev/null @@ -1,174 +0,0 @@ ---- -subtitle: Create a KPI token through the Carrot dapp ---- - -In order to create a KPI token, you can simply go to the dapp's homepage and -either click on "create campaign" in the hero section that is presented to you -right away or scroll down to the "templates" section below, locate the ERC20 KPI -token in the list and click on the "use template" button. - -A brief description about what the template is about and its features are -presented in the template card in the "templates" section. - -After clicking on "use template" a fullscreen modal should pop up with the -creation form loaded from the template's latest version. - -A guide is presented below on how to fill the creation form based on what you -want to create. - -## General information - -The first step collects generic information about the campaign you want to -create. In particular: - -- **Title**: the campaign's title should be short and memorable and tell - potential users what the campaign is about. -- **Description**: the campaign's description is a potentially long text that - supports Markdown through a powerful in-app editor. As many details as - possible about the campaign should go here, including an exhaustive - description about the goal it's trying to achieve and how to exactly measure - if the goal was achieved or not. -- **Tags**: tags are arbitrary short strings mainly used for discoverability. -- **Expiration**: the expiration date for the KPI token. The expiration - mechanism is there to protect the KPI token creator from potentially - malicious oracles that could lock in collaterals by becoming unresponsive. - If the KPI token is not finalized by the expiration date, any collateral - minus any minimum payout paid out to KPI token holders will be returned to - the KPI token creator. The expiration date should be chosen so that it's - reasonably later compared to when oracles are expected to know the outcome - of a condition. -- **ERC20 token name, symbol and supply**: these are informations that will be - used to create and mint the onchain ERC20 tokens that represent a claim to - the collateral. Choose them depending on what you want to incentivize. - -## Collaterals - -The second step is fully dedicated to the selection of collaterals. Up to 5 -ERC20 token amounts can be selected as collaterals and a minimum payout can also -be specified. - -In order to add a collateral to the collaterals list, you start by selecting a -token from the token selector located in the left part of the form. By clicking -it, an ERC20 token picker should pop up, showing supported tokens in the -official Carrot token list by default. You can search among the available tokens -using the searchbar in the top part of the modal, and if you don't find what -you're looking for you can add arbitrary tokens by pasting their address in the -same searchbar. If the address points to a valid ERC20 token, an import row will -be displayed and the token will be successfully imported. - -If you want to have more choices token list wise, you can click the "manage -lists" button in the bottom part of the modal and pick a different list from -where to load tokens from. - -Once you have selected a token you can use the number input at the right side of -the token picker in order to specify the amount you want to use as collateral, -and the number input below it to specify any minimum payout you want to set. - -If you want, you can quickly select the maximum amount available in your -currently connected wallet by clicking the orange "max" text to the right of the -displayed balance right below the token box. - -Keep in mind that a protocol fee is applied to the chosen collaterals and its -value (both in percentage and absolute terms) can be seen in the bottom part of -the collateral picker box once you've typed in an amount in the number input. - -The chosen minimum payout can't be more or equal than the "standard" amount of -collateral minus any protocol fee, as that would mean no collateral would be -dynamically unlocked based on the condition results, making the created KPI -token pointless. In those cases, explicative errors are shown and the "add to -campaign" button will be disabled. - -Once you're satisfied with the input amounts, and if the data is valid, the "add -to campaign" button will be enabled, and by clicking it you should see the input -values being moved to the collateral table below. The collateral rows will show -the effective collateral amount the KPI token will hold after any protocol fee -has been taken, and you can hover the "total amount" column for each collateral -row in order to have an exhaustive fee breakdown shown to you. - -It's possible to remove wrong collateral entries by clicking on the "x" icon to -the left of the collateral row you want to remove. - -By default, if a collateral row is added with the same token to one of the -collateral rows already present in the table, the row in the table will be -overwritten, so you can use this feature to correct any mistake you've made -while adding rows to the table. - -Once you're satisfied with the collaterals, click the "next" button to move -forward with the KPI token creation. - -## Oracle configuration - -At the moment, only the Reality.eth v3 oracle template is present in the Carrot -protocol, so by default it is autoselected by the ERC20 KPI token template and -you're presented with its creation form. In normal conditions an additional step -would be presented to you asking to pick the oracle templates you want to use -for the KPI token. - -To see how the various fields on the Reality.eth v3 oracle template creation -form can be populated, check out the specific guide made on that (TODO: add link -to the Reality.eth v3 oracle template creation form). - -Once you're satisfied with the oracle configuration click the "next" button. - -## Outcome configuration - -The outcome configuration step takes care to instruct the KPI token template on -how to interpret results coming from the selected oracle. - -2 types of congifurations are available: - -- **Categorical**: if you want to have a "yes/no" type of condition (i.e. was - the goal reached yes or no), this is the correct choice. You will need to - enable the "binary" switch in the UI, and this will automatically disable - the lower and higher bound number inputs below. -- **Scalar**: if you want to have a range type of condition (i.e. in cases - where you want to track numeric values and have collaterals unlocked - depending on where the final result falls within a range), this is the - correct choice. In order to specify it, first disable the "binary" switch - above (if currently enable) and enter the lower and higher bound values - manually. - -Extra care has to be taken while filling in these values as the collaterals -unlocking strictly depends on this. The ERC20 KPI token template unlocks -collaterals based on these values, so misconfigured values an result in KPI -tokens not behaving as expected. - -In order to mitigate the aforementioned issue, the ERC20 KPI token creation form -tries to determine whether you want to create categorical or scalar tokens based -on the oracle configuration performed in the prior step. This won't work in all -cases though, and in general you should review the configuration even if -automatically applied by the ERC20 KPI token creation form. - -In case an automatic setting of the outcome configuration has been performed, -the message below will be shown to the user. Please double check any automatic -configuration and see if it matches up with the oracle configuration you have -performed. - -Once you're satisfied with the outcome configuration click the "next" button. - -## Deployment - -It's finally the time to deploy your KPI token. 2 simple steps are required in -order to deploy the KPI token on-chain: - -- **Collateral(s) approval**: this step requires you to approve all the picked - collaterals for usage by the created KPI token. Click on the "Approve - (currently approved token symbol)" button until all collaterals are - approved. At this point, the create button should be enabled. -- **Creation**: by clicking on the "create" button below once it becomes - enabled you'll be able to deploy the KPI token on-chain as configured by you - in the previous steps. - -## Final step - -Once the create transactions has been validated on-chain, you'll be able to -visit the campaign's page for the KPI token you just created. Congratulations! - -Additionally, you should see the minted ERC20 tokens minted by Carrot to -represent the conditional collateral for your campaign in your possession in the -wallet you've used to create the campaign. You can now go ahead and distribute -these tokens to the people you believe will have the most impact in reaching the -goal you want to achieve in order to incentivize them to reach it. - -Follow the "interaction guide" (TODO: link to interaction guide) below to learn -how to navigate the ERC20 KPI token campaign page. diff --git a/pages/using-the-dapp/kpi-token-templates/erc20/index.mdx b/pages/using-the-dapp/kpi-token-templates/erc20/index.mdx deleted file mode 100644 index 59d3f4f..0000000 --- a/pages/using-the-dapp/kpi-token-templates/erc20/index.mdx +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: ERC20 KPI token template -subtitle: - Composable and flexible ERC20 KPI tokens that can easily be distributed via - farming or airdrops. ---- - -This token template lets anyone create ERC20 tokens that can easily be -distributed via farming or airdrops, and that can be backed by multiple ERC20 -collaterals tied to user-defined conditions. The following sections will go in -detail over the characteristics of the template and its functionality. - -## Collaterals - -The template accepts up to 5 ERC20 token amounts as collaterals. These ERC20 -tokens will be unlocked (all or in part, depending on how the condition is set -up) at finalization time and either sent back to the KPI token owner or unlocked -for KPI token holders to redeem (or both, as we'll see in subsequent sections). - -Additionally, the concept of minimum payouts is supported. Minimum payouts -represent an amount of collateral that will always be paid out to KPI token -holders at finalization or expiration time regardless of the goal's current -condition (reached or not reached). - -## Conditions (oracles) - -The template supports up to 5 different oracles relaying back condition results. -With the current frontend implementation of the creation form (see below for -more details on upcoming features), each condition governs an equal part of the -underlying collateral. - -Let's run a couple examples to make the last sentence clearer and explain a -couple different scenarios: - -1. Let's say we have a simple ERC20 KPI token set up with a single oracle and - 1,000,000 DAI as collateral. In this case the oracle "governs" the full - 1,000,000 DAI collateral, meaning that the result relayed back by the oracle - is the only piece of data the template will use to determine how much of the - collateral to unlock for KPI token holders to redeem and how much to send - back. -2. In a KPI token that has the same 1,000,000 DAI single collateral as above, - but with 2 oracles, the template now has 2 pieces of data to work with, and - each one of these pieces of data will govern 50% of the collateral, so - 500,000 DAI for the first oracle and 500,000 DAI for the second one. -3. In a more complex example of a multi-collateral multi-oracle KPI token that - has 1,000 DAI and 2 WETH as collaterals and 2 oracles, the template again has - 2 pieces of data to work with, but this time each one of these pieces of data - will govern 50% of EACH collateral, so 500 DAI and 1 WETH for the first - oracle and 500 DAI and 1 WETH for the second one. - -You can see from the last example above how if multiple oracles are applied to a -multiple collateral KPI token, each one of the oracles governs a portion of each -different collateral. - -## Finalization logic - -The template implements its own finalization logic based on bounds, which makes -it flexible to adapt to any need. - -Bounds can be set to instruct the template on how to interpret results relayed -back by oracles. This unlocks the possibility to have both categorical (yes/no) -and scalar goals (range) to be expressed in a seamless way when creating the KPI -token. - -In the categorical case, the template will only interpret oracle answers in 2 -distict ways: yes or no. If the answer from the oracle is interpreted as a YES -(goal reached) the collaterals will be fully unlocked for KPI token holders to -redeem, while if the answer is NO (goal not reached), the collaterals minus any -minimum payout (see the collaterals section above for an explanation on minimum -payouts) will be sent back to the KPI token owner. - -TODO: write about the expiration logic TODO: write about upcoming not yet -implemented features (multi-oracle is not yet implemented for example, and also -condition weighting) diff --git a/pages/using-the-dapp/kpi-token-templates/erc20/interaction.mdx b/pages/using-the-dapp/kpi-token-templates/erc20/interaction.mdx deleted file mode 100644 index d7b13c6..0000000 --- a/pages/using-the-dapp/kpi-token-templates/erc20/interaction.mdx +++ /dev/null @@ -1,101 +0,0 @@ ---- -subtitle: Interact with an ERC20 KPI token campaign ---- - -Interacting with a KPI token can be done through the token's **page**. Opening a -token's page is as simple as clicking the "view campaign" button on a KPI token -campaign created using the ERC20 KPI token template. - -The page is generally structured in three different sections: - -- General information -- Wallet position card -- Oracle page card - -In the sections below more detail is given for each of the section - -## General information - -The first section of the campaign page (the hero section) is populated with -information regarding the campaign at hand. In particular: - -- **Title**: the campaign's title will be displayed right at the top of the - page, just on top of the campaign's card. -- **Owner**: the campaign's current owner. -- **Description**: the campaign's description, that goes into details about - what the campaign is about and optionally how the end results must be - calculated. -- **Rewards**: the campaign's rewards. This is the current rewards amount, - meaning that if some rewards have already been claimed/sent back to the KPI - token owner, this value will reflect it. -- **Minimum payouts**: the campaign's minimum payouts (the amount of rewards - that are guaranteed to be paid out to KPI token holders in any - circumstance). -- **KPI token**: this is the on-chain name and symbol of the ERC20 token - representing the collateral tied to the unlocking condition. -- **Initial supply**: the amount of ERC20 tokens minted when the campaign was - created (chosen by the campaign's creator). This value doesn't take into - account redemptions and token burnings. -- **Current supply**: the current ERC20 supply taking into account redemptions - and token burnings. -- **Expiration time**: the time to the KPI token expiration. To know more - about the concept of expiration check out the generic information section - about the template. - -## Wallet position card - -The wallet position card displays position information for the currently -connected wallet (and as such it won't be displayed if no wallet is connected). -In particular the shown information includes: - -- **Guaranteed rewards**: this value is calculated based on minimum payouts - and the current KPI token balance of the connected wallet. These are rewards - that are guaranteed to be redeemable once the KPI token finalizes, no matter - what. -- **Maximum rewards**: the full reward amount to be unlocked if the campaign's - condition is fully reached, depending on the connected wallet's balance of - the KPI token. -- **Balance**: the campaign's KPI token balance of the connected wallet. -- **Claimable rewards**: the currently claimable rewards of the connected - wallet. - -Additionally, an "actions" section is there at the bottom of the card, changing -depending on the KPI token's state. - -The possible states and values shown in this section are: - -- **Not finalized and not expired**: if the token hasn't expired but is not - yet finalized, a text is displayed telling the user pretty much nothing can - be done unless the KPI token either expires or gets finalized. The user will - be instructed to use the oracle page section below in the page to help - finalize the KPI token, if applicable (in case the used oracle for the - campaign needs manual intervention, such as when using Reality.eth). -- **Finalized without balance**: if the KPI token has been finalized but the - connected wallet has no balance of it, the user is told, but no action is - possible. -- **Finalized with balance but no redemption possible**: if the KPI token has - finalized, the connected wallet has some balance of it, but no redemption is - possible, the user is presented with 2 choices: either do nothing, or burn - the KPI tokens by clicking the displayed action button. -- **Finalized with balance and redemption possible**: if the KPI token has - finalized, the connected wallet has some balance of it, and redemption is - possible, the user is presented with a button he can click to redeem his - rewards. -- **Expired without balance**: if the KPI token has expired and the connected - wallet has no balance of it, nothing can be done. -- **Expired with balance**: two different scenarios are possible here. If the - KPI token had some minimum payouts, these will be paid out to users - regularly, and as such a "redeem" action will be possible. If no minimum - payouts were specified the user will be presented with an option to burn his - KPI tokens, which have expired worthless. - -## Oracle page card - -This section is dedicated to the frontend for the oracle the KPI token campaignc -reator picked while creating the campaign. The KPI token template has no direct -control over this, it just allocates part of the page to render the oracle's -frontend, and as such specific documentation for this portion of the template -strictly depends on the oracle picked to resolve the campaign and its page -frontend documentation. - -To know more on this check out the oracles section of the documentation. diff --git a/pages/using-the-dapp/oracle-templates/_meta.json b/pages/using-the-dapp/oracle-templates/_meta.json deleted file mode 100644 index 01e9c6b..0000000 --- a/pages/using-the-dapp/oracle-templates/_meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "reality.eth-v3": "Reality.eth v3" -} \ No newline at end of file diff --git a/pages/using-the-dapp/oracle-templates/reality.eth-v3/_meta.json b/pages/using-the-dapp/oracle-templates/reality.eth-v3/_meta.json deleted file mode 100644 index 53444c0..0000000 --- a/pages/using-the-dapp/oracle-templates/reality.eth-v3/_meta.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "index": "Reality.eth v3 oracle template", - "creation": "Creation", - "interaction": "Interaction" -} diff --git a/pages/using-the-dapp/oracle-templates/reality.eth-v3/creation.mdx b/pages/using-the-dapp/oracle-templates/reality.eth-v3/creation.mdx deleted file mode 100644 index 15d11b0..0000000 --- a/pages/using-the-dapp/oracle-templates/reality.eth-v3/creation.mdx +++ /dev/null @@ -1,78 +0,0 @@ ---- -subtitle: Create a KPI token through the Carrot dapp ---- - -If the chosen KPI token template supports it, at a certain point in the KPI -token creation flow you will be asked to pick one or more oracles to use. In -order to use the Reality.eth v3 oracle template, simply pick it from the -provided picker. - -After doing that you will be presented with the template's creation form. Below -is a detailed description of all the available parameters and how they affect -the created oracle. - -**If at any point you need more information, check out the -[official Reality.eth documentation](https://reality.eth.limo/app/docs/html/index.html).** - -## Arbitrator - -An arbitrator is responsible for providing a final answer to a question when -there is a dispute, in exchange for a fee. If the arbitrator is untrustworthy, -the system cannot be relied on to provide accurate answers, so that's why -whitelisted arbitrators are available to be picked from a dropdown. - -Since arbitration is expensive, it will usually only be requested after parties -have posted bonds, and the bonds have escalated to a level where the bond you -stand to gain by paying for arbitration is higher than the fee. Accordingly, -arbitrators should feel free to set fairly high fees that will adequately cover -the cost of a thorough arbitration process. - -## Question type - -Self explanatory. The question type determines the type of answer users will -have to input in the final answer form. Available values (as picked from the -dropdown) are: - -- **Yes/no**: this will make the question a binary one, where allowed - responses will only be yes or no, picked from a response form that will - consist of 2 radio buttons. Needless to say, this type of question/response - lends itself well to binary goals that are either fully reached or not. -- **Number**: this will usually make the question a scalar one, where the - allowed response will only be a number, typed in a response form that will - consist of a number input. This type of question/response lends itself well - to scalar goals that support a payout range. - -## Question timeout - -This value represents how much time people will have to correct incorrect -reponses after they are posted. 24 hours usually strikes a good balance between -resolution time and security. You may prefer a longer setting if you think your -question will need time to come to the attention of people qualified to answer -it, or a shorter setting if you think many people will be paying attention -within a short timespan, but be careful as low values make it easier for -maliciously wrong answers to slip in. - -## Opening timestamp - -A Reality.eth oracle can be created with an opening timestamp in the future if -the answer to the question it asks can only be known in the future. This value -determines when the question will become answerable by users. - -Due to the risks involved in setting this value too late compared to the KPI -token's expiration date, a rule is enforced on compatible KPI tokens that at -least 3 full resolution periods must pass between the opening of the question to -answers and the KPI token expiration. This is to avoid occasions in which the -KPI token expires worthless exclusively because (maliciously or not) a KPI token -creator has chosen the opening timestamp and the expiration values too close to -each other to allow for an organic answer resolution process to take place. - -## Minimum bond - -It's possible to enforce a minimum bond that will be applied to the question as -soon as it opens up for answer. Setting a minimum bond can insure no spamming -happens on the question due to the low barrier of entry. - -## Question - -A self explanatory value. This is the question text that will need to be -answered using the crowdsourced Reality.eth oracle. diff --git a/pages/using-the-dapp/oracle-templates/reality.eth-v3/index.mdx b/pages/using-the-dapp/oracle-templates/reality.eth-v3/index.mdx deleted file mode 100644 index 6a5aee8..0000000 --- a/pages/using-the-dapp/oracle-templates/reality.eth-v3/index.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Reality.eth v3 oracle template -subtitle: - A crowdsourced, decentralized and flexible oracle that leverages Reality.eth - v3. ---- - -This oracle template acts as an adapter to the Reality.eth v3 protocol, allowing -the creation of arbitrary goals/conditions through it. By leveraging Reality.eth -v3, there's no restriction on the type of condition to be used on the KPI token -to which this oracle is applied, since any goal can be oraclized through -Reality.eth. A crowdsourced process will determine the final outcome to the goal -and guarantee the correctness of the final value through strong crypto -incentives. Once the final answer is known, the oracle template will relay it -back to the KPI token to which it is attached, triggering the oracle's -finalization in the process. - -To know more about how Reality.eth makes crowdsourced generalized oracles -possible, check out the platform's docs -[here](https://reality.eth.limo/app/docs/html/dapp.html). diff --git a/pages/using-the-dapp/oracle-templates/reality.eth-v3/interaction.mdx b/pages/using-the-dapp/oracle-templates/reality.eth-v3/interaction.mdx deleted file mode 100644 index 2586f22..0000000 --- a/pages/using-the-dapp/oracle-templates/reality.eth-v3/interaction.mdx +++ /dev/null @@ -1,120 +0,0 @@ ---- -subtitle: Interact with a Reality.eth v3 oracle instance ---- - -The "page" component for a Reality.eth v3 oracle will be visible in any KPI -token page that has used at least one Reality.eth v3 oracle. From there, you'll -be able to interact with the oracle. - -Here you will be able to see generic information about the oracle, in -particular: - -- **Arbitrator**: the arbitrator that was picked while creating the oracle. - This is the arbitrator that will determine the final answer if asked to. -- **Timeout**: the picked answer's timeout. The timeout is the amount of time - that passes between when an answer being posted and when it is considered - final. This is also the time any user interested in answering the question - has to override an already present answer before it is finalized. For - example, if the answer timeout is 30s and an answer is posted now, it will - be considered final in 30s barring any question override, that must happen - in these 30s. -- **Direct oracle link**: if for any reason the Carrot oracle page is not - allowing the user to post an answer, a direct link to the Reality.eth dapp - (when supported) is offered to increase the availability of the oracle. The - link can also be used to double check that all the shown parameters are - correct. -- **Current answer**: this is the current highest-bond answer that has been - submitted to the question, if there's any. If no answer has been given yet, - it will be reflected in this value. -- **Finalizing in**: this is a countdown to when the currently highest-bond - answer will be considered final. It also represent the time any answerer has - to override the current answer if he considers it incorrect. -- **Bonded amount**: this is the native currency amount that has been bonded - alongside the currently answer. It represents the level of conviction the - answerer has in the given answer. At least double this amount in the chain's - native currency will need to be paid to override the answer.. -- **Question**: this is the question's text. - -The remaining part of the oracle page can show one of two things depending on -the question's state: if the opening timestamp is set in the future (i.e. the -question is not yet accepting answers), a countdown is shown to inform users -when it will in fact be possible to start posting answers. - -If instead the question is currently open and accepts answers, an answer form -will be shown depending on which kind of answer type was picked while creating -the oracle. - -The section below goes into more details regarding the multiple available answer -forms and how they work. - -## Answer forms - -Answer forms can be used by users to interact with the question at hand and -provide an answer to it, when applicable. The answer types generally depend on -how the question was configured when asked, but 2 values in particular will -always be available to answer with: - -- **Invalid question**: if anyone thinks the asked question cannot be answered - correctly due to how the question itself was structured, they can answer - with this option. This answer will always result in the goal being attached - to the oracle to be resolved as if it was not reached. -- **Answered too soon**: if you think it's too soon to correctly answer the - question because some event still has to happen, you can pick this answer. - Once a question has this answer as finalized, it is brought to a special - state, where it can be reopened by anyone in the future by clicking a button - once the needed events have materialized and enough information is present - to correctly answer the question. This process can be repeated n times - without limit if the reopened question still can't be answered due to - time-related constraints. - -The 2 answers above are only applicable in special cases, but following we have -an explanation of the type of answers that can be given in standard cases: - -- **Binary**: the binary answer form only allows the answer to be yes or no, - as the name suggests. The two options are selectable through dedicated radio - buttons. -- **Numeric**: the numeric answer form only allows numeric answers to be given - through a number input field. This is especially useful when anyone wants to - create scalar campaigns, the end result of which must fall into a range in - order to determine the payout. - -A bond must then be attached to the given answer to show conviction in it. The -bond is also used as an incentive mechanism to ensure the given answers aren't -malicious, as at the end of the answer process the total bonded native currency -amount will be redistributed among the ones that have historically given the -answer that was recognized as the true one by the crowdsourced process, and as a -result taken away from the ones that have posted wrong answers. - -The value can be freely decided if no previous answer was given and if no -minimum bond was set by the oracle creator. In case another answer is already -present, the bond must be at minimum double of the previous answer's bond, while -if no answer is currently present and a minimum bond was specified by the oracle -creator, that minimum bond amount must be respected. - -## Arbitration - -If you see a question with an incorrect answer and a high bond that you can't -possibly double to override it, you can request arbitration. - -Most arbitrators required a fee to be paid in order for the resolution service -they provide, and it's generally paid in native currency. The fee may be quite -high, and it will not be returned to you even if you are right. However, you -will receive the bond posted with the incorrect answer. To make it profitable to -request arbitration, you can increase your bond to the point where the person -posting the incorrect answer will either give up, making your answer the winner, -or post a bond that exceeds the amount you will have to pay the arbitrator. - -Once the arbitration fee has been paid the question will be locked in a "pending -arbitration" state, and the participants will have to wait for the arbitrator to -send their final answer to the contract. - -## Finalization - -Once a final answer is determined, a couple actions will be made available. In -particular: - -- **Finalize oracle**: this action finalizes the oracle and relays the final - result back to the KPI token. -- **Withdraw winnings**: if you have accrued any winnings from the Reality.eth - answer determineation process, you'll be able to withdraw them by clicking - this button.