feat: add stacking reference page

fixing #812

in reference to: https://github.com/blockstack/stacks-blockchain/pull/1957/

src/_data/boot-contracts-reference.json

@@ -0,0 +1,205 @@
+{
+  "pox": {
+    "public_functions": [
+      {
+        "name": "allow-contract-caller",
+        "input_type": "principal, (optional uint)",
+        "output_type": "(response bool int)",
+        "signature": "(allow-contract-caller caller until-burn-ht)",
+        "description": "Give a contract-caller authorization to call stacking methods. Normally, stacking methods may\nonly be invoked by _direct_ transactions (i.e., the `tx-sender` issues a direct `contract-call` to the stacking methods).\nBy issuing an allowance, the tx-sender may call through the allowed contract."
+      },
+      {
+        "name": "delegate-stack-stx",
+        "input_type": "principal, uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint",
+        "output_type": "(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)",
+        "signature": "(delegate-stack-stx stacker amount-ustx pox-addr lock-period)",
+        "description": "As a delegate, stack the given principal's STX using `partial-stacked-by-cycle`.\nOnce the delegate has stacked > minimum, the delegate should call `stack-aggregation-commit`."
+      },
+      {
+        "name": "delegate-stx",
+        "input_type": "uint, principal, (optional uint), (optional (tuple (hashbytes (buff 20)) (version (buff 1))))",
+        "output_type": "(response bool int)",
+        "signature": "(delegate-stx amount-ustx delegate-to until-burn-ht pox-addr)",
+        "description": "Delegate to `delegate-to` the ability to stack from a given address.\nThis method _does not_ lock the funds, rather, it allows the delegate to issue the stacking lock.\n\nThe caller specifies:\n * amount-ustx: the total amount of ustx the delegate may be allowed to lock\n * until-burn-ht: an optional burn height at which this delegation expiration\n * pox-addr: an optional address to which any rewards *must* be sent"
+      },
+      {
+        "name": "disallow-contract-caller",
+        "input_type": "principal",
+        "output_type": "(response bool int)",
+        "signature": "(disallow-contract-caller caller)",
+        "description": "Revokes authorization from a contract to invoke stacking methods through contract-calls"
+      },
+      {
+        "name": "reject-pox",
+        "input_type": "",
+        "output_type": "(response bool int)",
+        "signature": "(reject-pox)",
+        "description": "Reject Stacking for this reward cycle.\n`tx-sender` votes all its uSTX for rejection.\nNote that unlike Stacking, rejecting PoX does not lock the tx-sender's tokens: PoX rejection acts like a coin vote."
+      },
+      {
+        "name": "revoke-delegate-stx",
+        "input_type": "",
+        "output_type": "(response bool int)",
+        "signature": "(revoke-delegate-stx)",
+        "description": "Revoke a Stacking delegate relationship. A particular Stacker may only have one delegate,\nso this method does not take any parameters, and just revokes the Stacker's current delegate (if one exists)."
+      },
+      {
+        "name": "stack-aggregation-commit",
+        "input_type": "(tuple (hashbytes (buff 20)) (version (buff 1))), uint",
+        "output_type": "(response bool int)",
+        "signature": "(stack-aggregation-commit pox-addr reward-cycle)",
+        "description": "Commit partially stacked STX.\n\nThis allows a stacker/delegate to lock fewer STX than the minimal threshold in multiple transactions,\nso long as:\n   1. The pox-addr is the same.\n   2. This \"commit\" transaction is called _before_ the PoX anchor block.\nThis ensures that each entry in the reward set returned to the stacks-node is greater than the threshold,\n  but does not require it be all locked up within a single transaction"
+      },
+      {
+        "name": "stack-stx",
+        "input_type": "uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint",
+        "output_type": "(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)",
+        "signature": "(stack-stx amount-ustx pox-addr lock-period)",
+        "description": "Lock up some uSTX for stacking!  Note that the given amount here is in micro-STX (uSTX).\nThe STX will be locked for the given number of reward cycles (lock-period).\nThis is the self-service interface.  tx-sender will be the Stacker.\n\n* The given stacker cannot currently be stacking.\n* You will need the minimum uSTX threshold. This isn't determined until the reward cycle begins, but this\n   method still requires stacking over the _absolute minimum_ amount, which can be obtained by calling `get-stacking-minimum`.\n\nThe tokens will unlock and be returned to the Stacker (tx-sender) automatically."
+      }
+    ],
+    "read_only_functions": [
+      {
+        "name": "can-stack-stx",
+        "input_type": "(tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint, uint",
+        "output_type": "(response bool int)",
+        "signature": "(can-stack-stx pox-addr amount-ustx first-reward-cycle num-cycles)",
+        "description": "Evaluate if a participant can stack an amount of STX for a given period."
+      },
+      {
+        "name": "get-pox-info",
+        "input_type": "",
+        "output_type": "(response (tuple (current-rejection-votes uint) (first-burnchain-block-height uint) (min-amount-ustx uint) (prepare-cycle-length uint) (rejection-fraction uint) (reward-cycle-id uint) (reward-cycle-length uint) (total-liquid-supply-ustx uint)) UnknownType)",
+        "signature": "(get-pox-info)",
+        "description": "Returns information about PoX status."
+      },
+      {
+        "name": "get-pox-rejection",
+        "input_type": "principal, uint",
+        "output_type": "(optional (tuple (amount uint)))",
+        "signature": "(get-pox-rejection stacker reward-cycle)",
+        "description": "Returns the amount of uSTX that a given principal used to reject a PoX cycle."
+      },
+      {
+        "name": "get-stacker-info",
+        "input_type": "principal",
+        "output_type": "(optional (tuple (amount-ustx uint) (first-reward-cycle uint) (lock-period uint) (pox-addr (tuple (hashbytes (buff 20)) (version (buff 1))))))",
+        "signature": "(get-stacker-info stacker)",
+        "description": "Returns the _current_ stacking information for `stacker.  If the information\nis expired, or if there's never been such a stacker, then returns none."
+      },
+      {
+        "name": "get-stacking-minimum",
+        "input_type": "",
+        "output_type": "uint",
+        "signature": "(get-stacking-minimum)",
+        "description": "Returns the absolute minimum amount that could be validly Stacked (the threshold to Stack in\na given reward cycle may be higher than this"
+      },
+      {
+        "name": "get-total-ustx-stacked",
+        "input_type": "uint",
+        "output_type": "uint",
+        "signature": "(get-total-ustx-stacked reward-cycle)",
+        "description": "Returns the amount of currently participating uSTX in the given cycle."
+      },
+      {
+        "name": "is-pox-active",
+        "input_type": "uint",
+        "output_type": "bool",
+        "signature": "(is-pox-active reward-cycle)",
+        "description": "Returns whether or not PoX has been rejected at a given PoX cycle."
+      }
+    ],
+    "error_codes": [
+      {
+        "name": "ERR_DELEGATION_EXPIRES_DURING_LOCK",
+        "type": "int",
+        "value": "21"
+      },
+      {
+        "name": "ERR_DELEGATION_POX_ADDR_REQUIRED",
+        "type": "int",
+        "value": "23"
+      },
+      {
+        "name": "ERR_DELEGATION_TOO_MUCH_LOCKED",
+        "type": "int",
+        "value": "22"
+      },
+      {
+        "name": "ERR_NOT_ALLOWED",
+        "type": "int",
+        "value": "19"
+      },
+      {
+        "name": "ERR_STACKING_ALREADY_DELEGATED",
+        "type": "int",
+        "value": "20"
+      },
+      {
+        "name": "ERR_STACKING_ALREADY_REJECTED",
+        "type": "int",
+        "value": "17"
+      },
+      {
+        "name": "ERR_STACKING_ALREADY_STACKED",
+        "type": "int",
+        "value": "3"
+      },
+      {
+        "name": "ERR_STACKING_EXPIRED",
+        "type": "int",
+        "value": "5"
+      },
+      {
+        "name": "ERR_STACKING_INSUFFICIENT_FUNDS",
+        "type": "int",
+        "value": "1"
+      },
+      {
+        "name": "ERR_STACKING_INVALID_AMOUNT",
+        "type": "int",
+        "value": "18"
+      },
+      {
+        "name": "ERR_STACKING_INVALID_LOCK_PERIOD",
+        "type": "int",
+        "value": "2"
+      },
+      {
+        "name": "ERR_STACKING_INVALID_POX_ADDRESS",
+        "type": "int",
+        "value": "13"
+      },
+      {
+        "name": "ERR_STACKING_NO_SUCH_PRINCIPAL",
+        "type": "int",
+        "value": "4"
+      },
+      {
+        "name": "ERR_STACKING_PERMISSION_DENIED",
+        "type": "int",
+        "value": "9"
+      },
+      {
+        "name": "ERR_STACKING_POX_ADDRESS_IN_USE",
+        "type": "int",
+        "value": "12"
+      },
+      {
+        "name": "ERR_STACKING_STX_LOCKED",
+        "type": "int",
+        "value": "6"
+      },
+      {
+        "name": "ERR_STACKING_THRESHOLD_NOT_MET",
+        "type": "int",
+        "value": "11"
+      },
+      {
+        "name": "ERR_STACKING_UNREACHABLE",
+        "type": "int",
+        "value": "255"
+      }
+    ]
+  }
+}

src/common/data/stacking-ref.ts

@@ -0,0 +1,118 @@
+import { renderMdx } from '@common/data/mdx';
+import STACKING_REFERENCE from '../../_data/boot-contracts-reference.json';
+
+const wrapInClarityTicks = (string: string) => {
+  let newString = '```clarity';
+  newString += `
+`;
+  newString += string.trim();
+  newString += `
+`;
+  newString += '```';
+  return newString;
+};
+
+const inlineCode = (string: string) => {
+  let newString = '`';
+  newString += string.trim();
+  newString += '`';
+
+  if (newString === '``') {
+    newString = '';
+  }
+
+  return newString;
+};
+
+const generateMarkdown = () => {
+  let publicFunctions = '';
+  let readonlyFunctions = '';
+  let errorCodes = '';
+
+  STACKING_REFERENCE.pox.public_functions.forEach(entry => {
+    publicFunctions += `
+### ${entry.name}
+
+**Signature:** ${inlineCode(entry.signature)}
+
+
+**Input:** ${inlineCode(entry.input_type)}
+
+
+**Output:** ${inlineCode(entry.output_type)}
+
+${entry.description.trim()}
+`;
+  });
+
+  STACKING_REFERENCE.pox.read_only_functions.forEach(entry => {
+    readonlyFunctions += `
+### ${entry.name}
+
+**Signature:** ${inlineCode(entry.signature)}
+
+
+**Input:** ${inlineCode(entry.input_type)}
+
+
+**Output:** ${inlineCode(entry.output_type)}
+
+${entry.description.trim()}
+`;
+  });
+
+  STACKING_REFERENCE.pox.error_codes.forEach(entry => {
+    errorCodes += `### ${entry.name}
+
+**Type:** ${inlineCode(entry.type)}
+
+**Value:** ${inlineCode(entry.value)}
+`;
+  });
+
+  return {
+    publicFunctions,
+    readonlyFunctions,
+    errorCodes,
+  };
+};
+
+const getHeadings = arr =>
+  arr.map(entry => ({
+    content: entry.name,
+    level: 1,
+  }));
+
+export const convertStackingRefToMdx = async () => {
+  const markdown = generateMarkdown();
+  const [_publicFunctions, _readonlyFunctions, _errorCodes] = await Promise.all([
+    renderMdx(markdown.publicFunctions),
+    renderMdx(markdown.readonlyFunctions),
+    renderMdx(markdown.errorCodes),
+  ]);
+
+  const publicFunctions = {
+    content: _publicFunctions,
+    headings: getHeadings(STACKING_REFERENCE.pox.public_functions),
+  };
+
+  const readonlyFunctions = {
+    content: _readonlyFunctions,
+    headings: getHeadings(STACKING_REFERENCE.pox.read_only_functions),
+  };
+
+  const errorCodes = {
+    content: _errorCodes,
+    headings: getHeadings(STACKING_REFERENCE.pox.error_codes),
+  };
+
+  return {
+    props: {
+      mdx: {
+        publicFunctions,
+        readonlyFunctions,
+        errorCodes,
+      },
+    },
+  };
+};

src/common/navigation.yaml

@@ -110,6 +110,7 @@ sections:
         pages:
           - path: /blockstack-cli
           - path: /language-clarity
+          - path: /stacking-contract
           - path: /stacks-blockchain-api
           - external:
               href: 'https://blockstack.github.io/blockstack.js/'

src/components/stacking-ref.tsx

@@ -0,0 +1,27 @@
+import React from 'react';
+import { Components } from '@components/mdx/mdx-components';
+import { TableOfContents } from '@components/toc';
+import hydrate from 'next-mdx-remote/hydrate';
+import { space } from '@stacks/ui';
+
+export const StackingErrorcodeReference = React.memo(({ content, headings }: any) => {
+  return (
+    <>
+      <TableOfContents mb={space('extra-loose')} label="Contents" headings={headings} />
+      {hydrate(content, { components: Components })}
+    </>
+  );
+});
+export const StackingFunctionReference = React.memo(({ content, headings }: any) => {
+  return (
+    <>
+      <TableOfContents
+        mb={space('extra-loose')}
+        columns={[2, 2, 3]}
+        label="Contents"
+        headings={headings}
+      />
+      {hydrate(content, { components: Components })}
+    </>
+  );
+});

src/pages/references/stacking-contract.md

@@ -0,0 +1,23 @@
+---
+title: Stacking Contract
+description: See a detailed list of all functions and error codes of the Stacking contract.
+---
+
+export { convertStackingRefToMdx as getStaticProps } from '@common/data/stacking-ref'
+import { StackingErrorcodeReference, StackingFunctionReference } from '@components/stacking-ref'
+
+Stacking is implemented as a smart contract using Clarity. On the testnet, you can always find the Stacking contract by this contract identifier: `ST000000000000000000002AMW42H.pox`.
+
+Below is a list of public and read-only functions as well as error codes that can be returned by those methods.
+
+## Public functions
+
+<StackingFunctionReference {...props.mdx.publicFunctions} />
+
+## Read-only functions
+
+<StackingFunctionReference {...props.mdx.readonlyFunctions} />
+
+## Error codes
+
+<StackingErrorcodeReference {...props.mdx.errorCodes} />

src/pages/stacks-blockchain/stacking.md

@@ -76,6 +76,4 @@ Stacking is a built-in capability of PoX and is realized through a set of action
 
 ## Stacking contract
 
-Stacking is implemented as a smart contract using Clarity. On the testnet, you can always find the Stacking contract by this contract identifier: `ST000000000000000000002AMW42H.pox`.
+Check out the [Stacking contract reference](/references/stacking-contract) to see available methods and error codes.
-
--> A PoX contract reference is coming soon!