Merge pull request #57 from Convex-Dev/develop

Updates for Convex Coin info and more

blog/2024-11-25-protonet/index.md

@@ -29,7 +29,7 @@ Here's what you can expect in the next two weeks:
 - **4th Dec**: Desktop day. We'll be running a workshop for developers and power users using Convex Desktop. If that's you, join our live interactive session session, 4-6pm UK time on the [Convex Community Discord](https://discord.com/invite/xfYGq4CT7v). Mike may be generously donating some Convex Coins to participants to help them get started, so don't miss out!
 - **5rd Dec**: Launch of **independently operated peers**, including one hosted by [Paisley](https://www.paisley.io/), a user owned DeFi / payments network running on Convex.
 - **6th Dec**: **Virtual launch party**. 6pm UK time on the [Convex Community Discord](https://discord.com/invite/xfYGq4CT7v). Expect demos, big ideas and lively discussion. BYO coffee, pizza and beers etc. 
-- **9th Dec**: Paisley web-based dApp goes live, offering a way for anyone to **buy Convex Coins** using stablecoins (starting with USDT on Base). 
+- **9th Dec**: Paisley web-based dApp goes live, offering a way for anyone to **buy Convex Coins** using stablecoins (starting with USDC on Base). 
 - **10 Dec**: Analysis day. We'll be looking back on the launch process, examining the state of the network and writing up some reports, insights and learnings.
 - **11 Dec**: If we need to, peers will get a code update. Hopefully not necessary, but if this needs to happen due to any issues found there may be a short window of maintenance where transactions won't work.
 - **12 Dec**: Community day. We'll be online to discuss anything and everything related to Convex and the future. Join for community hangout at 4pm UK time, on the Discord as usual. 

docs/cad/003_encoding/README.md

@@ -244,7 +244,7 @@ The high hex digit of each tag byte specifies the general category of teh data v
 | -------- | -------------------- | -------- |
 | 0x0x     | Basic constants      | Special values like `nil` |
 | 0x1x     | Numerics             | Integers, Doubles |
-| 0x2x     | References           | Addresses, References to branch values |
+| 0x2x     | References           | References to branch values |
 | 0x3x     | Strings and Blobs    | Raw Blob data, UTF-8 Strings etc. |
 | 0x4x     | Reserved             | Reserved for future use, possible N-dimensional arrays |
 | 0x5x     | Reserved             | Reserved for future use |
@@ -346,22 +346,6 @@ Ref encodings are used for child values contained within other cell encodings su
 
 These rules are necessary to ensure uniqueness of the parent encoding (otherwise, there would be two or more encodings for many values, e.g. one with an embedded child and the other with a external branch ref).
 
-### `0x21` Address
-
-Addresses are used to reference sequentially allocated accounts in Convex. 
-
-```
-0x21 <VLQ Count = address number>
-```
-
-An Address is encoded by the tag byte followed by a VLQ Encoding of the 64-bit value of the Address. 
-
-The address number MUST be positive, i.e. a 63-bit positive integer.
-
-Since addresses are allocated sequentially from zero (and Accounts can be re-used), this usually results in a short encoding.
-
-Addresses MAY be used by implementations outside the CVM for other types of sequentially allocated values.
-
 ### `0x30` String
 
 A String is a sequence of bytes with UTF-8 string encoding assumed.
@@ -693,6 +677,8 @@ Applications SHOULD use a small code value (e.g. a small Long, or a Byte Flag) t
 
 Applications MAY in addition use the hex digit `z` to further disambiguate code types. In combination with the 18 valid one byte encodings, this gives a reasonably generous 288 distinct code types before another byte is required.
 
+Lisp aficionados and hackers may find appeal in the fact that e.g. `0xC0` can be used to represent a Cons cell. While Convex Lisp does not use this, it is a perfectly valid application of extension types.
+
 ### `0xD0`-`0xDF` Data Records
 
 Data Records are record types where every field value is encoded (i.e. the record is densely coded).
@@ -727,6 +713,8 @@ Where:
 
 Extension values are arbitrary non-negative integer values with a one byte tag, where the low byte of the tag is available for applications to define a special meaning for the value. 
 
+For example, Convex uses the extension value `0xEA` to indicate an Address. Since Addresses are allocated sequentially from zero (and Accounts can be re-used), this usually results in a short VLQ encoding.
+
 Extension values are considered "BlobLike" and can therefore be used a a key in an Index
 
 Examples: 

docs/tutorial/coins/index.md

@@ -0,0 +1,126 @@
+# Convex Coins
+
+## About Convex Coins
+
+Convex Coins are the native currency of Convex. It's a utility token that lets you use the full power of the Convex Network. It's also a scarce resource: the coin supply is limited by design.  
+
+Convex Coins can be subdivided into coppers. 1 Convex Coin = 1,000,000,000 coppers (one billion). This means that you can use small fractions of a Convex Coins: useful for precise calculations of micropayments etc.
+
+
+## Receiving Coins
+
+Receiving coins is generally a good thing. You might receive Convex Coins for multiple reasons:
+- You purchased some from the release curve
+- You were awarded coins from the Convex Foundation as a contributor
+- Someone is making a payment to you, e.g. for goods and services that you provide
+- You are using an app that makes use of Convex Coins
+
+So how do you actually receive them? They are a digital asset, after all, and you can't put them in your pocket.
+
+To receive coins you need a Convex account. Convex accounts are recorded as part of the Convex global state, which is updated, verified and protected by peers of the decentralised network. Accounts hold a balance of Convex Coins and are designated with an address which looks like:
+
+```
+#23798
+```
+
+If you have an account you use already, that's great: you can just provide the address and receive coins directly. The sender can use this address to make any transfer to you as required.
+
+### Getting an Account
+
+If you don't have an account, then any other user of the network can create one for you. If you are new to Convex, the person or organisation sending you coins will normally do this for you.
+
+However, it is very important to secure the new account so that only you can access it. Accounts and the coins they contain are protected by strong cryptography, so to do this you will need to provide an Ed25519 public key. This is usually shown as a 32-byte hex string that looks like:
+
+```
+0xe3B4746e32f32Eb7B1c6Af045dd7238ee5eea71B33c8b5CD91a22BcDAc5b0c54
+```
+
+Account are *psuedonymous*: The account public key or address alone doesn't identify you as an individual, but it is possible that others may discover additional information that associates you with the account. 
+
+### Creating an Ed255198 key pair
+
+You can create an Ed25519 key pair any way you like - there are multiple tools and software solutions that can do this for you and help you to secure your private keys.
+
+One easy option is to use Convex Desktop. If you choose to create a key using Convex Desktop. The key generation screen looks like this:
+
+![alt text](keygen.png)
+
+At the bottom you can see the key pair generated:
+- Private Ed25519 seed: `5b32f8ff94d1f901098fa41a4045449726849dda5e1a3de34ae123037418795c` (KEEP SECRET!!!)
+- Ed25519 Public key: `0xe3B4746e32f32Eb7B1c6Af045dd7238ee5eea71B33c8b5CD91a22BcDAc5b0c54` (OK to share!)
+
+To minimise risk, Convex Desktop does not save keys on your computer (unless you tell it to), so make sure you have taken an offline backup of the necessary information to recreate it. Typically you will want to keep:
+
+```
+Mnemonic: sing bomb stay manual powder hard north mixture sausage lunch retreat desert
+Passphrase: hello1234567890ZZ
+```
+
+Note: The BIP39 path is always `m/44/864/0/0/0` by default. You don't need to remember this if you use the default, but if you change this then make sure you back this up too!
+
+**DOUBLE CHECK**: Make sure you can independently recreate your key pair from the mnemonic and passphrase you have written down. If you can't then you have probably made a mistake and it would be safer to create a new one! 
+
+### Creating extra accounts
+
+Once you have an account, you might want more than one. This can be useful for multiple reasons:
+- Security: if you lose they key to one account, the others are safe
+- Separating accounts for different purposes, e.g. developer work vs. savings
+- Having an account that is shared with others with a limited balance
+- Privacy: You don't want all your transactions going through a single account 
+
+Alternatively, you might want to create an account for someone else so that you can transfer coins to them.
+
+If you are a power user or developer, you can use the Convex REPL to create a new account. Example usage as follows:
+
+```clojure
+;; Create account with this desired public key. Make sure you use the PUBLIC key here!!
+(create-account 0xe3B4746e32f32Eb7B1c6Af045dd7238ee5eea71B33c8b5CD91a22BcDAc5b0c54)
+=> #21568
+
+;; Send 100 Convex Coins to the new account
+;; Note: 1 Convex Coin = 1000000000 coppers, so remember to add 9 zeros!
+(transfer #21568 100000000000)
+```
+
+When you create a new account, make sure you record the account number. While it is possible to go and look back at transaction history and/or search for accounts that have your public key if you forget it, it's a lot easier if you just write down the account number!
+
+## Securing your Coins
+
+### Basic rules
+
+NEVER give your private key (or the seed phrases used to create it) to anyone else. Anyone with access to these can sign transactions for your account, and steal your coins. As a wise man once said: Not your keys, not your coins!
+
+ALWAYS ensure you are signing transactions on a device that you control and trust. For small coin to medium balances, your laptop may be fine. If you are at higher risk, sign transactions only on an air-gapped laptop (i.e. not connected to the internet).
+
+### Physical Backups
+
+If you have a significant holding of Convex coins, you may wish to keep a secure physical backup of your mnemonic phrase. Writing it down and putting it in a safe is an option, or you might choose to use something more durable like a metal seed phrase storage device (these are available relatively cheaply online).
+
+Here's an example of a backup of the example mnemonic used above:
+
+![alt text](backup.jpg)  
+
+Don't forget to backup your passphrase as well (that can more plausibly be something that you can remember, but still, plenty of people have lost Bitcoin due to forgetting it....).
+
+### Custodial Accounts
+
+Some companies (e.g. exchanges) may offer custodial accounts on Convex. These accounts are similar to the self-custody account described above in that they have an address like `#82456` and can receive / send Convex coins, with two key differences:
+- The company providing the custody will keep the private key safe. You don't have it.
+- You can't execute transactions yourself: you will need to use the services of the custody provider (e.g. using their app)
+
+Custodial accounts have the advantage that you don't need to manage your own key security. This can be easier for many users, and can be very secure if the custodial provider manages the keys properly on your behalf.
+
+The risk is that you are dependent on the custody provider to keep the keys secure and faithfully execute transactions on your behalf. Only use custody providers that you trust!
+
+### Account Controllers
+
+Accounts can optionally specify a `*controller*`, which is a facility that allows other accounts to control your account.
+
+Typical reasons to do this might include:
+- You have a secure fallback account that you can use to recover coins and other assets if you lose the private key to your regular account 
+- You want to control your account via code (e.g. via a smart contract)
+- You want a trusted third party to have the ability to recover your account even if you lose your keys
+- An app may set itself as the controller so that it can restore / take actions in your account on your behalf
+
+This is a useful and powerful feature but it should be **used with caution**. Account controllers have full control of the account: they can change the keys, move funds etc. Do not set a controller unless you trust the controller account to act in your best interests. At the very least, you should expect the controller account to be **more secure** than the account that it controls.
+

docs/tutorial/convex-lisp/index.md

@@ -9,6 +9,8 @@ Convex Lisp is a powerful modern Lisp for decentralised systems.
 
 It is designed from the ground up to support immutable lattice data structures and functional programming for robust but flexible decentralised programs.
 
+You don't need to know Convex Lisp to use Convex, but it's a powerful tool for developers wishing to build dApps and digital assets. Most of the core Convex on-chain tools are written in and designed to be used from Convex Lisp.
+
 ## 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 as the first language on the CVM for a number of reasons: