Add docs for omni-transaction-rs + near example

docs/2.build/1.chain-abstraction/chain-signatures/chain-signatures-contract/controlling-near-accounts/1.introduction.md

@@ -0,0 +1,64 @@
+---
+id: introduction
+title: Controlling a NEAR account
+sidebar_label: Overview
+---
+
+This example is of a `simple subscription service` that allows a user to subscribe to an arbitrary service and lets the contract to charge them 5 NEAR tokens every month; sort of like a standing order. For most chains an account has a single key, the power of NEARs account model combined with chain signatures is that you can add an `MPC controlled key` to your account allowing a smart contract to control your account through code and limited actions (including ones that require a full access key to sign).
+
+This concept also enables:
+- **Account recovery**: allow a contract to add a new private key to your account after preset conditions are met.
+- **Trial accounts**: [Keypom](https://github.com/keypom/multichain-trial-accounts) uses this concept to create trial accounts that can only perform a limited number of actions and can be upgraded to a full account upon the completion of specified actions.
+- **DCA service**: a contract that allows a DEX to buy a token for a user every fixed period with a pre-defined amount of $USDC.
+- **and more...**
+
+These were all previously possible - before chain signatures - since a NEAR account is also a smart contract, but this required the user to consume a lot of $NEAR in storage costs to upload the contract to the account and it lacked flexibility. This approach is much more scalable and new account services can be switched in and out easily.
+
+Since a NEAR account is also a multichain account, any dervied foreign accounts associated with the NEAR account also inherit these account services.
+
+---
+
+## Running the example 
+
+This example has contracts written in Rust and scripts to interact with the contract in NodeJS. 
+
+Go ahead and clone the repository to get started:
+
+```bash
+# Clone the repository
+git clone https://github.com/PiVortex/subscription-example.git
+
+# Navigate to the scripts directory
+cd subscription-example/scripts
+
+# Install the dependencies
+npm install
+```
+
+To interact with the contract you will need three different accounts. A subscriber, an admin, and an account to hold the contract. Run the following command to create the accounts and deploy the contract:
+
+```bash
+npm run setup
+```
+
+To subscribe to the service run the following command:
+
+```bash
+npm run subscribe
+```
+
+To charge the subscriber from the admin account run the command:
+
+```bash 
+npm run charge
+```
+
+To unsubscribe from the service run the command:
+
+```bash
+npm run unsubscribe
+```
+
+---
+
+In the [next section](./2.contract.md) we'll look at the contract code and walk through each part relevant to controlling a NEAR account with chain signatures. 

docs/2.build/1.chain-abstraction/chain-signatures/chain-signatures-contract/controlling-near-accounts/2.contract.md

@@ -0,0 +1,132 @@
+---
+id: contract
+title: Contract
+---
+
+import {Github, Language} from "@site/src/components/codetabs"
+
+Feel free to explore the contract code in full. In this tutorial, we assume a basic understanding of Rust and NEAR contracts as we'll only look at the parts relevant to chain signatures. The main data the contract stores is a map of the subscribers and when they last paid the subscription fee.
+
+---
+
+## Constructing the transaction 
+
+We only want the smart contract to be able to sign transactions to charge the subscriber 5 NEAR tokens, no other transactions should be allowed to be signed. This is why we construct the transaction inside of the contract with the `omni-transaction-rs` library. 
+
+NEAR transactions have different `Actions`, a list of these actions can be found in [this section of the docs](../../../../1.concepts/protocol/transaction-anatomy.md#actions). It would be natural to assume that the `Transfer` action would be most appropriate here since we are just sending tokens from one account to another, but in fact we'll use the `FunctionCall` action since it will allow us to verify that the transaction has actually been sent and excepted by the network.
+
+<details>
+    <summary> Why a function call instead of a transfer? </summary>
+
+    There are two reasons for this:
+    1) Just because a transaction has been signed it does not mean it has been sent to the network. We don't want to update the state of the contract to say that the subscription has been paid just because the transaction has been signed, we need to confirm that the transaction has been sent and accepted by the network, the best way to do this in a contract is to call a function on the contract.
+
+    2) The MPC contract can sign transactions that are deemed to be "invalid". The MPC could sign a transaction to send 5 $NEAR from the subscriber to the contract but the subscriber might not actually have 5 $NEAR in their account. As a result, the transaction would be invalid and the network would reject it. With similar reasoning to the first point, we need to confirm that the transaction has been accepted by the network before we update the state of the contract.
+
+</details>
+
+<Language language="rust" showSingleFName={true}>
+    <Github fname="charge_subscription.rs"
+            url="https://github.com/PiVortex/subscription-example/blob/main/contract/src/charge_subscription.rs#L45-L54"
+            start="45" end="54" />
+</Language>
+
+Once we have the action we can build the transaction as a whole. You can see that the transaction requires the `public_key` of the sender, the `nonce` of the key, and a recent `block_hash`, we take all of these as arguments to the function since the nonce and the block hash are not accessible inside of the context of the contract, and the public key is much easier to derive outside of the contract, plus we'll save ourselves some gas by doing it this way. 
+
+<Language language="rust" showSingleFName={true}>
+    <Github fname="charge_subscription.rs"
+            url="https://github.com/PiVortex/subscription-example/blob/main/contract/src/charge_subscription.rs#L56-L69"
+            start="56" end="69" />
+</Language>
+
+After we make the call to the MPC contract to sign the transaction we'll need to original transaction to create a fully signed transaction therefore we are going to pass the transaction to the callback function. Before the do that we need to `serialize` the transaction to a `JSON string` since many of the types used in the transaction are not serializable by default.
+
+<Language language="rust" showSingleFName={true}>
+    <Github fname="charge_subscription.rs"
+            url="https://github.com/PiVortex/subscription-example/blob/main/contract/src/charge_subscription.rs#L71-L74"
+            start="71" end="74" />
+</Language>
+
+The MPC contract takes a `transaction payload` as an argument instead of the transaction directly. To get the transaction payload we serialize the transaction to borsh using `.build_for_signing()`, then produce a SHA256 hash of the result and finally convert it to a 32-byte array.
+
+<Language language="rust" showSingleFName={true}>
+    <Github fname="charge_subscription.rs"
+            url="https://github.com/PiVortex/subscription-example/blob/main/contract/src/charge_subscription.rs#L76-L81"
+            start="76" end="81" />
+</Language>
+
+---
+
+## Calling the MPC contract
+
+In our `signer.rs` file, we have defined the interface for the `sign` method on the MPC contract. 
+
+<Language language="rust" showSingleFName={true}>
+    <Github fname="signer.rs"
+            url="https://github.com/PiVortex/subscription-example/blob/main/contract/src/signer.rs#L40-L43"
+            start="40" end="43" />
+</Language>
+
+As an input, it takes the payload, the path and the key_version. The `path` determines which public key the MPC contract should use to sign the transaction, in this example the path is the account Id of the subscriber, so each subscriber has a unique key. The `key_version` states which key type is being used. Currently the only key type supported is secp256k1 which has a key version of `0`.
+
+<Language language="rust" showSingleFName={true}>
+    <Github fname="signer.rs"
+            url="https://github.com/PiVortex/subscription-example/blob/main/contract/src/signer.rs#L3-L18"
+            start="3" end="18" />
+</Language>
+
+We then make a `cross contract call` to the `sign` function on the MPC contract and make a callback with the JSON stringified transaction.
+
+<Language language="rust" showSingleFName={true}>
+    <Github fname="charge_subscription.rs"
+            url="https://github.com/PiVortex/subscription-example/blob/main/contract/src/charge_subscription.rs#L87-L98"
+            start="87" end="98" />
+</Language>
+
+We attach a small amount of gas to the callback and use a `gas weight of 0` so the majority of the attached gas can be used by the MPC contract.
+
+---
+
+## Reconstructing the signature 
+
+Once the transaction has been signed by the MPC contract we can reconstruct the signature and add it to the transaction. You could decide to reconstruct the signature and add it to the transaction outside of the contract, but an advantage of doing it in the contract is that you can return a fully signed transaction from the contract which can be straight away sent to the network instead of having to store the transaction in the frontend. It also makes it much easier for indexers/relayers to get transactions and broadcast them, making it less likely that transactions will be signed without being sent.
+
+The MPC contract returns the signature in a structure called `SignResult` that contains the three portions of the signature: `big_r`, `s` and the `recovery_id` often referred to as v. Note that `r` and `s` are wrapped in the additional structures `AffinePoint` and `Scalar` respectively. 
+
+<Language language="rust" showSingleFName={true}>
+    <Github fname="signer.rs"
+            url="https://github.com/PiVortex/subscription-example/blob/main/contract/src/signer.rs#L20-L38"
+            start="20" end="38" />
+</Language>
+
+We receive the parts of the signature as hex strings. We need to convert them to bytes, remember that two hex characters make a single byte. A NEAR secp256k1 signature is 65 bytes long, the first 32 bytes being `r` (where r is the first 32 bytes of big_r, which is 34 bytes long itself), the next 32 bytes are all the bytes from `s` and the final byte is the last byte of `big_r`. The recovery id is not used in this case. We then use a method to convert the bytes to a secp256k1 signature 
+
+<Language language="rust" showSingleFName={true}>
+    <Github fname="charge_subscription.rs"
+            url="https://github.com/PiVortex/subscription-example/blob/main/contract/src/charge_subscription.rs#L109-L129"
+            start="109" end="129" />
+</Language>
+
+The final step is to `deserialize` the transaction we passed and add the signature to it. Now we can return the `fully signed transaction`.
+
+<Language language="rust" showSingleFName={true}>
+    <Github fname="charge_subscription.rs"
+            url="https://github.com/PiVortex/subscription-example/blob/main/contract/src/charge_subscription.rs#L110-L130"
+            start="131" end="139" />
+</Language>
+
+---
+
+## Receiving payment
+
+Once the signed transaction is relayed to the `NEAR network` it will call the pay_subscription method in the contract. You can see that we are only updating the state of the contract here when the transaction has been accepted by the network.
+
+<Language language="rust" showSingleFName={true}>
+    <Github fname="lib.rs"
+            url="https://github.com/PiVortex/subscription-example/blob/main/contract/src/lib.rs#L61-L79"
+            start="61" end="79" />
+</Language>
+
+---
+
+In the [next section](./3.scripts.md) we'll look at the key parts of the scripts that interact with the contract which will show how to derive the subscriber's MPC public key and get the data outside the contract required to build the transaction inside.

docs/2.build/1.chain-abstraction/chain-signatures/chain-signatures-contract/controlling-near-accounts/3.scripts.md

@@ -0,0 +1,75 @@
+---
+id: scripts
+title: Scripts
+---
+
+import {Github, Language} from "@site/src/components/codetabs"
+
+In this repo there are a few scripts to interact with the contract. It is not just as simple as calling a method in the contract as we will have to do manage the subscriber's MPC public key.
+
+---
+
+## Key derivation
+
+You'll see in each of these scripts we are using a file called [derive-mpc-key.js](https://github.com/PiVortex/subscription-example/blob/main/scripts/utils/derive-mpc-key.js), as it's name suggests this is used to derive the public key of the MPC key being used to sign the transactions on behalf of the subscriber. Feel free to look into this code but you don't particularly need to understand it.
+
+However, there are some things worth noting. NEAR accounts usually use ed25519 keys but they also support secp256k1 keys. As mentioned previously we are using `secp256k1` keys here since this is the only key type currently supported by the MPC contract. You can also see that the full `path` is a combination of the `predecessor` to the MPC contract (the subscription contract) along with the `derivation path` given as the argument. The inclusion of the predecessor means that only this contract is able to sign transactions for the given key. 
+
+---
+
+## Subscribe
+
+To start a new subscription we simply derive the MPC key for the subscriber by inputting the `contractAccountId` as the `predecessorId` and the `subscriberAccountId` as the `derviationPath` and add it to the account. We then call the `subscribe` method in the contract.
+
+<Language language="javascript" showSingleFName={true}>
+    <Github fname="start-subscription.js"
+            url="https://github.com/PiVortex/subscription-example/blob/main/scripts/start-subscription.js#L32-L46"
+            start="32" end="46" />
+</Language>
+
+---
+
+## Charge
+
+In the charge script, we call the `charge_subscription` method from the `admin` account to charge a payment from the `subscriber` account. To call this method we need to supply the off-chain data to construct the transaction as mentioned before. We need:
+- The subscriber's MPC controlled `public_key`, so the MPC signs a transaction for the correct public key.
+- The `next nonce` of the key, so the transaction is unique.
+- A `block hash` within the last 24 hours. This is used to ensure that the transaction was recently signed. If the signed transaction is not relayed within 24 hours of the block hash supplied then the network will reject the transaction.  
+
+These details are available via RPC calls.
+
+<Language language="javascript" showSingleFName={true}>
+    <Github fname="charge-subscription.js"
+            url="https://github.com/PiVortex/subscription-example/blob/main/scripts/charge-subscription.js#L33-L56"
+            start="33" end="56" />
+</Language>
+
+The admin then calls the `charge_subscription` method with the input details and the account Id of the subscriber being charged. We are attaching 0.1 NEAR as deposit for the MPC contract which - in most cases - will be more than enough (the required deposit is variable depending on traffic to the MPC) and we will be refunded any excess. The admin is attaching a deposit and not just the contract because refunds are given to the original `signer` of the call to the MPC.
+
+<Language language="javascript" showSingleFName={true}>
+    <Github fname="charge-subscription.js"
+            url="https://github.com/PiVortex/subscription-example/blob/main/scripts/charge-subscription.js#L58-L68"
+            start="58" end="68" />
+</Language>
+
+We then fetch the result (which is the signed transaction) from the transaction outcome, convert it to a `Uint8Array`, serialize it to `base64`, and then broadcast it to the network. 
+
+<Language language="javascript" showSingleFName={true}>
+    <Github fname="charge-subscription.js"
+            url="https://github.com/PiVortex/subscription-example/blob/main/scripts/charge-subscription.js#L70-L77"
+            start="70" end="77" />
+</Language>
+
+This will execute the method call to the contract from the subscriber charging the subscriber 5 NEAR tokens, provided the subscriber has enough funds in their account.
+
+---
+
+## Unsubscribe
+
+To unsubscribe from the service the subscriber calls the `unsubscribe` method in the contract. While, with the deployed code, the contract will no longer have access to the path to sign transactions for the user it is best practice to remove the MPC key from the account just in case the contract is compromised.
+
+<Language language="javascript" showSingleFName={true}>
+    <Github fname="end-subscription.js"
+            url="https://github.com/PiVortex/subscription-example/blob/main/scripts/end-subscription.js#L32-L46"
+            start="32" end="46" />
+</Language>

website/sidebars.js

@@ -97,6 +97,17 @@ const sidebar = {
           "items": [
             "concepts/abstraction/chain-signatures",
             'build/chain-abstraction/chain-signatures/chain-signatures',
+            {
+              "Implementing Contract Logic": [
+                {
+                  "Controlling Existing NEAR Accounts": [
+                    "build/chain-abstraction/chain-signatures/chain-signatures-contract/controlling-near-accounts/introduction",
+                    "build/chain-abstraction/chain-signatures/chain-signatures-contract/controlling-near-accounts/contract",
+                    "build/chain-abstraction/chain-signatures/chain-signatures-contract/controlling-near-accounts/scripts",
+                  ]
+                },
+              ]
+            },
             // 'build/chain-abstraction/nft-chain-keys',
           ]
         },