diff --git a/blog/2024-09-16-new-doc-site.mdx b/blog/2024-09-16-new-doc-site.mdx index add500c..ead0d4f 100644 --- a/blog/2024-09-16-new-doc-site.mdx +++ b/blog/2024-09-16-new-doc-site.mdx @@ -1,11 +1,12 @@ --- slug: first-blog-post -title: Welcome to the new Convex Docs site! +title: New Convex Docs site! authors: [mikera] tags: [welcome, convex, community] --- After a few days of hacking we've finally got our new documentation site up and running! Every great project needs great docs, and we're using a powerful tool to make this happen: [Docusaurus](https://docusaurus.io/) + What's great about this? - Everyone in the community can now easily [contribute documentation](https://github.com/Convex-Dev/design) though the GitHub `design` repository diff --git a/blog/2024-09-16-welcome/index.md b/blog/2024-09-16-welcome/index.md index bab1249..66b60b5 100644 --- a/blog/2024-09-16-welcome/index.md +++ b/blog/2024-09-16-welcome/index.md @@ -8,6 +8,7 @@ tags: [convex, welcome, community] Welcome to the Convex Developer Documentation! The is the go-to resource for building with Convex. We're thrilled to introduce our new developer documentation site. This platform is designed to be your comprehensive guide for mastering Convex, a powerful decentralised platform based on lattice technology. + What you'll find here: diff --git a/blog/authors.yml b/blog/authors.yml index ddf136e..7a73ce5 100644 --- a/blog/authors.yml +++ b/blog/authors.yml @@ -19,3 +19,13 @@ convex: x: convex_world github: Convex-Dev +#helins: +# name: Adam Helinski +# title: Core Contributor +# url: https://github.com/helins +# image_url: https://github.com/helins.png +# page: true +# socials: +# github: helins + + diff --git a/docs/overview/concepts.md b/docs/overview/concepts.md new file mode 100644 index 0000000..e661392 --- /dev/null +++ b/docs/overview/concepts.md @@ -0,0 +1,20 @@ +--- +title: Key Concepts +authors: [convex] +tags: [convex] +--- + +## Overview + +Convex is a decentralised platform for the Internet of Value, offering flexibility and scalability far beyond the capabilities of traditional blockchains. In particular, it is designed to support high volume, interactive applications used directly by end users such as for mobile apps, payments and gaming. + + +## Governance + +Convex is governed by the non-profit Convex Foundation. The Foundation performs the following activities: + +- Ensures good governance of the Convex Network +- Operates key resources on behalf of the community, including the https://convex.world website and developer resources such as GitHub repositories +- Acts as this initial issuer of Convex Coins to individuals and organisations, inlciding management of the release curve +- Provides awards for contributors to Convex (e.g. open source developers) +- Supports the development of the Convex ecosystem via partnerships, marketing, education and other initiatives diff --git a/papers/convex-whitepaper.md b/docs/overview/convex-whitepaper.md similarity index 99% rename from papers/convex-whitepaper.md rename to docs/overview/convex-whitepaper.md index 992f569..f432cec 100644 --- a/papers/convex-whitepaper.md +++ b/docs/overview/convex-whitepaper.md @@ -1,3 +1,8 @@ +--- +title: White Paper +authors: [convex] +tags: [convex, technology] +--- # Convex White Paper ## Abstract diff --git a/docs/overview/faq.md b/docs/overview/faq.md new file mode 100644 index 0000000..a22026a --- /dev/null +++ b/docs/overview/faq.md @@ -0,0 +1,138 @@ +--- +title: FAQ +authors: [convex] +tags: [convex] +--- + +Some answers to common questions can be found here. + + +## Is Convex Free? + +Yes! Convex is free for anyone to use and build applications upon, and always will be. We are building Convex for everyone to support the Internet of Value. + +To make use of the resources of the network, small transaction fees are charged using Convex Coins, which is the native utility token of the network. This is important for serveral reasons: + +- Compensate those who provide important secure infrastructure to the network (i.e. peer operators) +- Prevent denial of service attacks by people flooding the network with wasteful transactions. This makes it very expensive to launch such attacks. +- Create an economic incentive to use the network as efficiently as possible (both for users and developers of smart contracts) + +Our goal is to keep transaction fees small, so that it is never a significant issue for legitimate network users. + + +## How fast is Convex? + +Convex can comfortably process many thousands of complex transactions per second (e.g. transfers and smart contract calls). The CVM itself has been benchmarked at over 1,000,000 TPS on a modern desktop PC. And as we continue making performance improvements it is getting faster by the day. + +But it's important to note that performance and scalability are not just about the raw throughput of transactions. Convex is designed to offer a good overall combination of: + +- Low latency to stable consensus (below 0.5s seconds on a global network) +- High execution throughput (e.g. 50,000+ token-based smart contract transactions per second) +- Advanced features (smart contracts, memory accounting, an on-chain compiler, autonomous Actors) +- A unified global state machine supporting atomic transactions +- True decentralisation as a public utility network (with Convergent Proof of Stake) +- Ability to operate a Peer with affordable hardware + +We achieve all this *without* resorting to over-complicated scaling solutions that introduce various new problems (e.g. cross-shard transactions). We can always add additional scaling features later, but it may not even be necessary. + + +## How do I integrate my application with Convex? + +Convex provides several mechanisms for integration. + +For most decentralised apps, it is easy to build a client-side application that makes use of the **Client API**. This is a convenient REST API using JSON that is ideal for web and mobile applications developers. + +Advanced applications can use the **Binary API** and construct messages directly to communicate with Peers. This is currently only possible for JVM-based languages (Java, Clojure, Scala etc.), but more may be supported in the future. + +Integrators can also use **Direct Peer Integration** where they run a fully operational Convex Peer alongside their server-side applications. This approach is complex and recommended only if you want maximum performance and/or want to interact with the CVM state directly (e.g. for search or indexing purposes). The convex.world server itself uses this technique. + + +## What should go on-chain? + +You often have a choice between putting code and information on the public Convex network or keeping it on a separate server when building a decentralised application. Some applications might do both: we call these "hybrid" dApps. + +Some general principles: + +- Put data *on-chain* when it needs to be *publicly visible and verifiable* +- Put data *on-chain* when you need to make trusted transactions between parties (e.g. exchanging digital assets) +- Keep data processing (e.g. string formatting, sorting) *off-chain* - this is best done on the client +- Keep data *off-chain* when it needs to be private +- Keep code and data *off-chain* if there are significant compute or storage requirements (it would be too expensive to put on-chain) + +It is a good idea to **keep data structures as simple as possible**. Ideally, Actor code should be performing a small set of O(1) operations on the right kind of data structures (looking up / updating a value in a map, appending a value to a vector etc.). We recommend designing the data structures for your Actors carefully first, before writing the code to interact with them. + + +## Is Convex a Blockchain? + +Think of Convex and the undelying lattice technology as "beyond blockchain". + +Convex shares many common attributes with traditional public blockchains: + +- A decentralised consensus network +- Security from malicious actors with cryptographic techniques +- Decentralised ownership of accounts, including the ability to control digital assets and currencies +- Ability to deploy and execute secure smart contract code +- Transactions are grouped into Blocks + +Technically however it's not implemented as a blockchain (in the sense that there is a linked list of blocks where each block contains the hash of a previous block). The Convex consensus algorithm creates an *ordering* of blocks, but the cryptographic hashes used to secure this ordering are kept outside the blocks themselves. This gives us a big advantage, as blocks can be submitted and processed by peers concurrently without having to first determine the hash of preceding block(s). + + +## How does Convex perform so well? + +It's complex! But here are some of the most important points: + +- The consensus algorithm (Convergent Proof of Stake, or CPoS) is extremely fast. It can confirm blocks in milliseconds between peers running on a local network. The main latency delay in the global network is just signal transmission over the Internet: the speed of light is a tricky problem. +- The CVM execution model is designed for performance: CVM operations are relatively high level, but are implemented using very efficient low-level code. +- We wrote a custom database (Etch) from scratch, specifically to support the performance needs of Convex. Having a database perfectly designed and tuned for the specific workload is a huge advantage and is faster than more generic alternatives (e.g. LevelDB) +- We exploit a lot of advanced features of the JVM, which is a very powerful platform backed by thousand man-years of engineering effort. We especially appreciate the JIT compiler, concurrency, asynchronous IO and advanced memory management features. It probably wouldn't be feasible to build something as fast as Convex without these. +- Some of our team have been performance-oriented hackers for many years, with experience in game coding, embedded systems, distributed computing etc. We enjoy and take pride in writing fast, efficient code! + + +## Why does Convex use Lisp? + +A variant of Lisp was chosen as the initial language for the CVM for a few reasons: + +- Lisp expressions are essentially a direct encoding of the [Lambda Calculus](https://en.wikipedia.org/wiki/Lambda_calculus). This means that we are based on fundamentally sound computation theory. +- Lisp macros are a powerful tool for generating code, which is an ideal solution for building sophisticated smart contract capabilities with an on-chain compiler. +- Lisp is a highly expressive language for interactive development, with a long history of REPL-based usage. We feel this is ideal for a platform where we want developers to be instantly productive and able to interact directly with the system in real-time. + +Paul Graham's essay [Beating the Averages](http://www.paulgraham.com/avg.html) is an interesting perspective on the advantages of Lisp for building a business. Despite dating from 2001, we feel many of these points still stand today and are very relevant for people wanting to build applications using Convex. + + +## What is Memory Accounting? + +Memory Accounting is the system in Convex used to track the usage of on-chain memory. Every time a user executes a transaction, the amount of memory used is calculated and deducted from the user's memory allowance. If the user has an insufficient memory allowance, it is possible to automatically buy more on-demand. + +If a user executes a transaction that releases memory, the amount of released memory is credited back to the user's allowance. This creates a good incentive to "clean up after yourself". Actors and smart contracts should also be designed with the option to clean up memory after it is no longer required. + +We need Memory Accounting because on-chain memory is a **scarce resource**, and should be used wisely. An effective way of doing this is to make memory allowances themselves into a digital asset, that can be transferred and traded. This creates a market incentive to utilise memory as efficiently as possible. + + +## What is the difference between Actors and Smart Contracts? + +Actors are virtual agents that live their whole existence inside the Convex Virtual Machine. They are autonomous agents that can execute CVM code, manage digital assets, perform complex computation, make decisions. They follow strict rules that control their execution, so that they can be relied upon to behave in a particular way. + +Smart contracts are a concept: the idea of having real-world contracts or agreements that can be automatically executed and enforced by software, eliminating risk and the need to trust fallible humans. + +You can use Convex Actors to implement smart contracts. Not every Actor needs to be a smart contract, however: an Actor that simply stores on-chain information on your behalf isn't really a contract with anyone else. + + +## When will the Main Network go live? + +We are on track to release the first live version of Convex (Convex Protonet) in 2024. + +An important caveat: getting it right is more important than rushing a release. We won't launch until we are 100% sure it is ready for production use and fully secure with real-world value at stake. + +People will depend on Convex to be a secure, reliable platform for decentralised applications and digital assets. It is not acceptable to expose them to security risks from flaws in the platform, nor is it acceptable to make breaking changes to the CVM that could cause significant problems with smart contracts. + + +## Can I buy Convex as a cryptoasset? + +Not yet, but soon! + +We are establishing the Convex Foundation a non-profit organisation that will facilitate the initial sale of Convex native coins in the near future. Initially, this will be only open to institutional investors. Funds raised will be invested in building Convex and the ecosystem. + + +## Who is building Convex? + +We are a small [team](https://convex.world/about/team) of dedicated hackers and creators passionate about building an amazing platform for the future digital economy. diff --git a/papers/manifesto.md b/docs/overview/manifesto.md similarity index 94% rename from papers/manifesto.md rename to docs/overview/manifesto.md index abbdb79..d7ddd3e 100644 --- a/papers/manifesto.md +++ b/docs/overview/manifesto.md @@ -1,14 +1,20 @@ -# The Convex Manifesto - DRAFT +--- +title: Manifesto +authors: [convex] +tags: [convex, community, philosophy] +--- -We are building open economic systems based on decentralised technology for the 21st century and beyond. +# The Convex Manifesto (draft) -The time is ripe for change: For too long, our societies have been burdened by inefficient and unfair economic systems. Centralised organisations hold undue power, exploiting monopolistic control over most of our economic life. Transaction costs are massive, holding back progress and burdening people with unnecessary expenses. Many people are unfairly excluded from financial and economic participation. Our economic models are causing tragic and unsustainable damage to the natural world we all share. +Building Open, Decentralized Economies for the 21st Century -AI is rapidly changing the landscape of the digital economy, and indeed the whole world. At this critical time in our civilisation, it imperative that control over data, computational power and the economy as a whole is put back in the hands of individuals. +The time for change is now. For far too long, our societies have been shackled by inefficient and inequitable economic systems. Centralized institutions wield excessive power, exploiting monopolistic control over much of our economic activity. Transaction costs are exorbitant, hindering progress and imposing unnecessary burdens on individuals. Countless people are unfairly excluded from financial and economic participation. Our current economic models are inflicting irreversible damage on the natural world we all share. -Convex is a public decentralised system for real-time P2P exchange of data and value, designed as a substrate for the digital economy in the age of AI. As such, it provides the foundation for the type of economics we want to see in the world - fair, inclusive, efficient, diverse and sustainable. +Artificial intelligence is rapidly transforming the digital economy, and indeed, the entire world. At this pivotal moment in human history, it is imperative that control over data, computational power, and the economy as a whole is returned to the hands of individuals. -This manifesto outlines our beliefs and core principles. +Convex is a public, decentralized system for real-time peer-to-peer exchange of data and value, designed as a foundational layer for the digital economy in the age of AI. As such, it provides the bedrock for the kind of economics we envision – fair, inclusive, efficient and sustainable. + +This manifesto outlines our core beliefs and principles. ## Open Economic Systems diff --git a/papers/performance.md b/docs/overview/performance.md similarity index 99% rename from papers/performance.md rename to docs/overview/performance.md index 30a46ea..ecdfa9a 100644 --- a/papers/performance.md +++ b/docs/overview/performance.md @@ -1,4 +1,4 @@ -# Performance - Goals and how we do it +# Performance Convex offers outstanding performance for decentralised applications. Our objective is to offer the best combination of decentralised security and interactive performance for applications in categories such as DeFi, gaming and the metaverse with large numbers of concurrent users. diff --git a/docs/overview/use-cases.md b/docs/overview/use-cases.md new file mode 100644 index 0000000..551251b --- /dev/null +++ b/docs/overview/use-cases.md @@ -0,0 +1,44 @@ +--- +title: Use Cases +authors: [convex] +tags: [convex, ecosystem, applications] +--- + +Convex is a general purpose, programmable decentralised network with global state. As such, there is no inherent limit on the nature of applications that can be built. Here are some of the things that Convex can be used for, and are being actively developed within the Convex community: + +## NFTs + +Non-fungible tokens (NFTs) are a powerful mechanism for creating unique virtual items that can be owned, collected traded and utilised in virtual environments such as games. Each NFT has a unique on-chain ID and can be individually addressed, transferred and used within smart contracts. + +Convex includes a powerful NFT engine based on set theory, capable of millions of NFT transfers per second, and allowing arbitrary metadata and smart contract rules to be attached to individual NFTs. + +## DeFi + +Convex provides comprehensive support for decentralised finance applications. + +As part of the full-stack solution we offer: +- A uniform, fungible token model suitable for utility tokens, stablecoins, governance tokens and more. +- An advanced decentralised token exchange based on constant liquidity pools allowing for efficient trading of fungible tokens of all types. +- Template smart contracts and libraries for creating and interacting with DeFi assets +- Capabilities to delegate control of assets to intermediaries, custodians or decentralised smart contracts +- Capabilities for digital asset governance including trusted smart contract upgrades + +## Gaming + +Games need fast interactive performance and shared global state for immersive multiplayer worlds. With blazing fast performance (just milliseconds for transaction confirmations) and minimal transaction costs, Convex is the perfect platform for decentralised gaming, virtual items and in-game currencies. + +Our first game is a 3D block game inspired by Minecraft, Boulderdash and the Roguelike genre. The entire game world is implemented as a set of Convex Actors. Transactions are automatically executed when the player takes actions that change the world state, and the player can otherwise view and explore the world at zero cost. + +## Metaverse + +Convex provides the ideal substrate for the convergence of real and virtual worlds into new shared realities. With a rich model of digital assets and on-chain smart contract capabilities, we can help you craft the next generation of experiences in virtual reality. + +Our metaverse innovation includes the world's [first fully on-chain 3D game world](https://www.youtube.com/watch?v=op2NccyMEBE). + +## Payments and Retail CBDCs + +Convex supports an [advanced model of digital currencies](https://www.youtube.com/live/XHxEnqBwgN8?feature=shared&t=95) with customisable governance, suitable for CBDCs and other currencies with trusted issuers. Our [open source mobile wallet](https://github.com/Convex-Dev/convexity) (Convexity) makes these easily accessible and convenient for users, and can be customised to create branded experiences with additional functionality. [Here's a demo](https://www.youtube.com/watch?v=2a40mRkcuag). + +With incredible performance, low costs and low latency, Convex digital currencies are ideal for consumer use cases such as digital payments, international transfers and retail purchases. + +If you are involved in a project to create a digital currency, we can help you succeed: get in touch at [info@convex.world](mailto:info@convex.world). diff --git a/docs/tutorial/convex-lisp/index.md b/docs/tutorial/convex-lisp/index.md new file mode 100644 index 0000000..8deac6c --- /dev/null +++ b/docs/tutorial/convex-lisp/index.md @@ -0,0 +1,24 @@ +--- +slug: convex-lisp +title: Convex Lisp +authors: [mikera] +tags: [convex, developer, lisp] +--- + +Convex Lisp is a powerful modern Lisp for decentralised systems. + +## Why Lisp? + +The CVM is designed to be able to support many different languages and paradigms. However, we wanted a powerful language that would empower developers on Convex from the beginning, and chose Lisp for a number of reasons. + +- **Immutability**: Lisp's functional programming paradigm promotes immutability, which is essential for ensuring the integrity and consistency of decentralised systems where data must be replicated and distributed across multiple nodes. +- **Dynamic typing**: Lisp's dynamic typing allows for flexible data structures and easy modifications, crucial for adapting to the constantly evolving nature of decentralised systems. At the same time, Convex Lisp is **strongly typed**, avoiding the issues associated with weak typing. +- **Code is data**: representing code using its own data structures (also known as "homoiconicity") gives Lisp advanced **metaprogramming** capabilities the creation of domain-specific languages (DSLs) tailored to specific concepts, making it easier to reason about and implement complex economic mechanisms. +- **Interactive coding**: Lisp pineered the use of the REPL for highly interactive programming. With Convex, we've taken this a step further with a complete on-chain compiler so that everything on the CVM can be done with simple interactive Lisp commands. + +Convex Lisp was heavily inspired by [Clojure](https://clojure.org/), from which it borrows most basic and many core functions, and [Racket Scheme](https://racket-lang.org/) which inspired many of the more advanced metaprograming facilities. + +## Interesting technical notes + +- Convex Lisp is a **Lisp-1** (i.e. keeps function and data values in the same namespace).This is simpler than a Lisp-2 and seems more appropriate for a functional programming language, where functions are regularly treated as first class values. +- Convex Lisp is designed for **orthogonal persistence**. Developers don't need to care where data or code is stored: it is loaded and cached on demand. This powerful capability means that the CVM can operate code and data data structures much larger than system RAM without imposing any burden on developers. \ No newline at end of file diff --git a/docs/tutorial/lisp-guide-advanced.md b/docs/tutorial/convex-lisp/lisp-guide-advanced.md similarity index 98% rename from docs/tutorial/lisp-guide-advanced.md rename to docs/tutorial/convex-lisp/lisp-guide-advanced.md index c9fbbdd..f88109d 100644 --- a/docs/tutorial/lisp-guide-advanced.md +++ b/docs/tutorial/convex-lisp/lisp-guide-advanced.md @@ -1,3 +1,11 @@ +--- +slug: convex-lisp-advanced +title: Advanced Guide +sidebar_position: 2 +authors: [mikera, helins] +tags: [convex, developer, lisp] +--- + If you've got this far, you may be interested in some of the more advanced features of Convex Lisp. This section is intended for people who want to know more about how Convex Lisp work, and how it integrated with the capabilities of the CVM. ## Compiler Phases diff --git a/docs/tutorial/lisp-guide.md b/docs/tutorial/convex-lisp/lisp-guide.md similarity index 99% rename from docs/tutorial/lisp-guide.md rename to docs/tutorial/convex-lisp/lisp-guide.md index 290d49d..e031d4a 100644 --- a/docs/tutorial/lisp-guide.md +++ b/docs/tutorial/convex-lisp/lisp-guide.md @@ -1,3 +1,11 @@ +--- +slug: convex-lisp-intro +title: Gentle Introduction +sidebar_position: 0 +authors: [mikera, helins] +tags: [convex, developer, lisp] +--- + This guide is intended for developers interested in learning about Convex Lisp. We will take you through the basics of the language, all the way through to designing and deploying a simple smart contract! ## Setup diff --git a/papers/glossary.md b/docs/tutorial/glossary.md similarity index 99% rename from papers/glossary.md rename to docs/tutorial/glossary.md index d4749df..0d5d6cb 100644 --- a/papers/glossary.md +++ b/docs/tutorial/glossary.md @@ -1,3 +1,9 @@ +--- +title: Glossary +authors: [convex] +tags: [convex, community, tutorial] +--- + ## Account An Account is a record of identification and ownership within Convex. Accounts may be either: diff --git a/docusaurus.config.ts b/docusaurus.config.ts index c22065b..13ea3e3 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -75,6 +75,12 @@ const config: Config = { src: 'img/Convex.png', }, items: [ + { + type: 'docSidebar', + sidebarId: 'overviewSidebar', + position: 'left', + label: 'Overview', + }, { type: 'docSidebar', sidebarId: 'tutorialSidebar', diff --git a/papers/concepts.md b/papers/concepts.md deleted file mode 100644 index 3bb28f9..0000000 --- a/papers/concepts.md +++ /dev/null @@ -1,19 +0,0 @@ -# Convex Concepts - -## Overview - -Convex is a decentralised platform for the Internet of Value, offering flexibility and scalability far beyond the capabilities of traditional blockchains. In particular, it is designed to support high volume, interactive applications used directly by end users such as for mobile apps, payments and gaming. - - - - - -## Governance - -Convex is governed by the non-profit Convex Foundation. The Foundation performs the following activities: - -- It ensures good governance of the Convex Network -- It operates key resources on behalf of the community, including the https://convex.world website and developer resources such as GitHub repositories -- It acts as a seller of Convex Coins to individuals and organisations, in exchange for money which is used as a fund to re-invest in the Convex ecosystem -- It provides grants and awards for contributors to Convex (e.g. open source developers) -- It supports the development of the Convex ecosystem diff --git a/papers/convex-whitepaper.pdf b/papers/convex-whitepaper.pdf deleted file mode 100644 index 1d1fd4b..0000000 Binary files a/papers/convex-whitepaper.pdf and /dev/null differ diff --git a/sidebars.ts b/sidebars.ts index 1e1de49..e6a4bf6 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -12,6 +12,8 @@ import type {SidebarsConfig} from '@docusaurus/plugin-content-docs'; */ const sidebars: SidebarsConfig = { // By default, Docusaurus generates a sidebar from the docs folder structure + overviewSidebar: [{type: 'autogenerated', dirName: 'overview'}], + tutorialSidebar: [{type: 'autogenerated', dirName: 'tutorial'}], cadsSidebar: [{type: 'autogenerated', dirName: 'cad'}], diff --git a/papers/open-economy.md b/wip/open-economy.md similarity index 100% rename from papers/open-economy.md rename to wip/open-economy.md