lukechilds
/
docs
mirror of https://github.com/lukechilds/docs.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

feat: add stacking reference page 

fixing #812

in reference to: https://github.com/blockstack/stacks-blockchain/pull/1957/
feat/stacks-js-updates
Alexander Graebe 4 years ago
parent
245fc2097a
commit
d92e453345
6 changed files with 375 additions and 3 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 205
      src/_data/boot-contracts-reference.json
  2. 118
      src/common/data/stacking-ref.ts
  3. 1
      src/common/navigation.yaml
  4. 27
      src/components/stacking-ref.tsx
  5. 23
      src/pages/references/stacking-contract.md
  6. 4
      src/pages/stacks-blockchain/stacking.md

205
src/_data/boot-contracts-reference.json
View File

@ -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"
}
]
}
}

118
src/common/data/stacking-ref.ts
View File

@ -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,
},
},
};
};

1
src/common/navigation.yaml
View File

@ -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/'

27
src/components/stacking-ref.tsx
View File

@ -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 })}
</>
);
});

23
src/pages/references/stacking-contract.md
View File

@ -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} />

4
src/pages/stacks-blockchain/stacking.md
View File

@ -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`.
-> A PoX contract reference is coming soon!
Check out the [Stacking contract reference](/references/stacking-contract) to see available methods and error codes.

Write Preview
Loading…
Cancel
Save