diff --git a/.gitignore b/.gitignore index 502bcd81e..d94b8b952 100644 --- a/.gitignore +++ b/.gitignore @@ -6,4 +6,4 @@ node_modules .vscode/* out build - +_glossaryBuild diff --git a/docs/architecture/governance.md b/docs/architecture/governance.md index 29cd52bd4..aed2b6f71 100644 --- a/docs/architecture/governance.md +++ b/docs/architecture/governance.md @@ -23,7 +23,7 @@ If a quorum is met, the top-voted proposal moves to the next period. Each period lasts five blockchain cycles (40,960 blocks at 30-second intervals or roughly 14 days, 5 hours), comprising roughly 2 months and 10 days. -Only [delegates](../overview/glossary#delegate) can vote on proposals. +Only delegates can vote on proposals. A delegate's voting power is the amount of tez that it has staked plus the tez that delegators have delegated to it, also called its _staking balance_. ### 1. Proposal period diff --git a/docs/overview/glossary.md b/docs/overview/glossary.md index cc0f10bc3..d66c90903 100644 --- a/docs/overview/glossary.md +++ b/docs/overview/glossary.md @@ -1,372 +1,7 @@ --- title: Glossary -last_update: - date: 24 October 2023 --- -## Tezos and tez + -The following is adapted from this [Agora post](https://forum.tezosagora.org/t/nomenclature/2376) by Tezos Co-founder Arthur Breitman. As noted in the post, there is no official body that can authoritatively set Tezos' nomenclature, but the following is recommended: - -### Tezos - - Used either as a noun or an adjective to designate: - - * An open-source project and software (as in, "contributing to the Tezos codebase") - * A peer-to-peer network of nodes maintaining a blockchain (as in "a Tezos node") - * The specific Tezos chain with the most economic relevance (as in "the Tezos chain"). In particular, the chain whose [millionth block](https://tzkt.io/BKtC4QCWoF73kxLj773vFpQuuwrnye6PS7T1aM3XEPvFXiQbNu7/endorsements) had hash `BKtC4QCWoF73kxLj773vFpQuuwrnye6PS7T1aM3XEPvFXiQbNu7`. - -### Tez - - A unit of the cryptocurrency native to a Tezos chain, such as in "I sent you 2 tez." Tez is invariable. It is not capitalized except at the beginning of a sentence or when you would otherwise capitalize a noun. "I sent you 2 tez" and not "2 Tez". - -### XTZ - - XTZ, tez, or ꜩ (`\ua729`, "Latin small letter tz") is the native currency of Tezos. - - "XTZ" is an ISO-4217-compatible code for representing tez on the most economically relevant Tezos chain. Unless there is a very specific reason to use an ISO code for it, the term tez is preferred. Situations where the ISO code might be useful typically involve accounting systems, exchange rates with other currencies, and anything that might need some sort of standardized code. - - - -## Tezos terms - -### Block - - The Tezos blockchain is a linked list of blocks (or actually, a tree when several competing branches exist). - Blocks conceptually contain a header and a list of operations, - which are specific to the economic protocol. - - The header itself decomposes into a shell header (common to all Tezos economic protocols), and a protocol-specific header. - The shell header contains protocol-agnostic data such as the predecessor's block hash and the block's timestamp. - -### Context - - The state of the blockchain. The context is defined by the - economic protocol and typically includes information such as - "this account is credited with this many tez" and "this is the - code for that smart contract." - - The context is modified by operations. For example, an - operation can transfer tez from one account to another, which modifies the - part of the context that tracks account credit. - -### Economic protocol - - The economic protocol is the set of rules defining valid operations and blocks, how the network agrees on the next block to build (the consensus algorithm), - and how operations update the blockchain state, also called context. - - In Tezos, the economic protocol can be upgraded without interruption or - forking of the blockchain. This is because the procedure for an upgrade is also defined within the economic protocol, which can thus update itself. - -### Fitness - - (a.k.a. score, weight) - For each block, the consensus algorithm can compute a score called fitness which determines the quality of the chain leading to that block. - The shell changes the head of the chain to the valid block that has the highest fitness. - -### Height - - See level. - -### Level - - (a.k.a. block height) - The position of a block in the blockchain, that is, the number of blocks - since the genesis block, where the genesis block is at level 0. - -### Mempool - - A (block or operation) metadata is a piece of data - computed as a result of the application of the - block or operation on an associated context. The metadata - consists of many pieces of information such as the operation receipts, - rewards updates, voting period, etc. - - A block's metadata is the collections of operations metadata for all the operations included in the block (if the validation was successful). - -### Node - - A peer in the P2P network. It maintains a local state and propagates blocks - and operations. - -### Operation - - An operation transforms the context; this is what makes the state of the chain - change. Operations are grouped into blocks; thus, the chain progresses in - batches. - -### Score - - See fitness. - -### Shell - - The shell is a software component of the node. It is parameterized by a - specific economic protocol. It serves as the bridge between the P2P layer - (handling communication between nodes) and the economic protocol layer - (handling the context, operation application, scoring, etc.). - -### Weight - - See fitness. - -## Protocol terms - -### Accuser - - When a delegate attempts double signing (or when it tries - to abuse the network in another similar way), another delegate can make an - accusation, by providing evidence of the offense. The delegate injecting the accusation in a newly baked block is called the accuser. - - The accuser is awarded some funds from the security deposit of the accused. - - When using Octez, accusation operations are emitted by the - accuser daemon. Note that this daemon is not associated to a delegate: accusation operations are anonymous, and any delegate can include them in a block. - -### Account - - An account is an address managed by the protocol. - In the context, each account is associated with a balance (an amount of - tez available). - - An account can be a user account or a smart contract. - -### Baker - - When a delegate creates a new block, it is called the baker of this block. - Baking rights are distributed to different delegates based on their - available stake. Only a delegate with baking rights - is allowed to bake. - The baker selects transactions from the mempool to be included in the block it bakes. - - When using Octez, baking and other consensus actions are handled by the baker - daemon, on behalf of one or more delegate accounts. - By extension, a baker designates the owner of such a delegate account, typically running the baker daemon on its behalf. - -### Baking - - The act of creating a new block by a baker. - -### Baking rights - - Baking/endorsing a block can only be done by a delegate who holds the - baking/endorsing right for that block level and round. At the start of a cycle, - baking and endorsing rights are computed for all the block levels and rounds in the - cycle, based on the proportion of the stake of each delegate. - - For each block level and round, there is exactly one account that is allowed to bake, but several accounts are allowed to endorse. - -### Burn - - To ensure responsible use of the storage space on the public blockchain, - there are some costs charged to users for consuming storage. These - costs are burnt (i.e., the amount of tez is destroyed). For example, - a per-byte storage cost is burnt for increasing the storage space of a - smart contract; a fixed amount is burnt for allocating a new contract - (which consumes space by storing its address on the blockchain). - - See also fee. - -### Constant - - Protocols are parameterized by several parameters called protocol constants, which may vary from one protocol to another or from one network to another. - -### Contract - - See account. - -### Cycle - - A cycle is a sequence of consecutive blocks of fixed length (given by a protocol constant). E.g., cycle 12 started at block - level 49152 and ended at block level 53248. - - Cycles are used as a unit of "time" in the block chain. For example, the - different phases in the amendment voting procedures are defined based on - numbers of cycles. - - The length of a cycle is a (parametric) protocol - constant, and thus might change across different - Tezos protocols. - -### Delegate - - A user account that can participate in consensus and in governance. - Actual participation is under further provisions, like having a minimal stake. - A user account becomes a delegate by registering as such. - Through delegation, other accounts can delegate their rights to a delegate account. - The delegate's rights are calculated based on its stake. - Note that `tz4` accounts cannot be delegates. - -### Delegation - - An operation in which an account designates a - delegate. The delegating account's balance increases the delegate's stake and consequently - its baking rights and endorsing rights. However, the delegate does not control the funds of - the delegating account, e.g., it can not spend them. - -### Double signing - - The situation when a baker signs two different blocks at the same level and same round, - is called double baking. Double baking is detrimental to the network and might be - indicative of an attempt to double spend. - The same goes for signing two different endorsements at the same level and the same round. - As such, double signing (i.e., double baking or double endorsing) is punished by the - network: an accuser can provide proof of the double signing to be awarded - part of the double signer's deposit -- see Slashing. - -### Failing Noop - - The `Failingnoop` operation implements a *No-op*, which always - fails at application time, and - should never appear in applied - blocks. This operation allows end-users to - sign arbitrary messages which have no - computational semantics. - -### Endorsing - - When a block is created and propagated on the network, delegates that have - endorsing rights for the matching block level and round can emit an endorsement operation. - Endorsement operations are included in the next block. - -### Endorsing rights - - See baking rights. - -### Fee - - To ensure responsible use of computation resources of other nodes, and also to encourage active participation in the consensus protocol, - users pay fees to bakers for including their operations in blocks. - For example, fees are paid to a baker for operations such as a transaction or a revelation of a public key. - - Currently, only manager operations - require collecting fees from its sender account. - - See also burn. - -### Gas - - A measure of the number of elementary steps performed during - the execution of a smart contract. Gas is used to measure how - much computing power is used to execute a smart contract. - -### Implicit account - - See [User account](#user-account). - -### Layer 1 - - The primary blockchain i.e. the Tezos chain. Within any blockchain ecosystem, Layer 1 (L1) refers to the main chain to - which side chains, rollups, or other protocols connect and settle to. The Layer 1 chain is deemed to be most - secure, since it has the most value (or stake) tied to it, and be most decentralized and censorship resistant. - However, transaction space is limited leading to low throughput and possibly high transaction costs. - See Layer 2. - -### Layer 2 - - Layer 2 (L2) includes sidechains, rollups, payment channels, etc. that batch their transactions and - write to the layer 1 chain. By processing transactions on layer 2 networks, - greater scalability in speed and throughput can be achieved by the ecosystem overall, since the number of transactions - the layer 1 can process directly is limited. By cementing transactions from a L2 to L1, - the security of the L1 chain backs those operations. In Tezos there are a number of layer 2 solutions, - including Smart Optimistic Rollups, - validity or ZK-Rollups [Epoxy](https://research-development.nomadic-labs.com/files/cryptography.html) , - zkChannels, and sidechains such as [Deku](https://deku.marigold.dev/). - -### Michelson - - The built-in language used by a smart contract. - -### Minimal stake - - An amount of tez (e.g., 6000ꜩ) serving as a minimal amount for a - delegate to have baking rights and voting rights in a cycle. - -### Operation kinds - - The main kinds of operations in the protocol are transactions (to transfer funds - or to execute smart contracts), accusations, activations, delegations, - endorsements, and originations. - -### Originated account - - See smart contract. - -### Origination - - A manager operation whose purpose is to create -- that - is, to deploy -- a smart contract on the Tezos blockchain. - -### Round - - An attempt to reach consensus on a block at a given level. - A round is represented by an index, starting with 0. - Each round corresponds to a time span. - A baker with baking rights at a given round is only allowed to bake during - the round's corresponding time span. Baking outside of one's designated - round results in an invalid block. - -### Roll - - deprecated; see minimal stake. - -### Smart contract - - Account which is associated to a Michelson script. - They are created with an - explicit origination operation and are therefore sometimes called - originated accounts. The address of a smart contract always starts - with the letters `KT1`. - -### Smart Optimistic Rollups - - Smart optimistic rollups constitute a layer 2 solution that can be used to deploy either a general-purpose polyvalent layer 2 blockchain - (e.g., an EVM-compatible one), or an application-specific DApp. - -### Stake - - The amount of tokens that determines a delegate's weight in the - governance process and in the selection of its baking and - endorsing rights. A delegate's stake is usually given by the - delegate's own tokens plus the sum of tokens delegated to - it. However, there are cases when this is not the case, see - [here](https://tezos.gitlab.io/active/consensus.html#active-stake-nairobi) for details. - -### Transaction - - An operation to transfer tez between two accounts, or to run the code of a - smart contract. - -### User account - - An account that is linked to a public key. Contrary to a smart - contract, a user account cannot include a script and it - cannot reject incoming transactions. - - If *registered*, a user account can act as a delegate. - - The address of a user account always starts with the - letters tz followed by 1, 2, 3, or 4 (depending on the - signature scheme) and finally the hash of the public key. - -### Validation pass - - An index (a natural number) associated with a particular kind of - operations, allowing to group them into classes. Validation passes - enable prioritizing the validation and - application of certain classes of - operations. - -### Voting period - - Any of the `proposal`, `exploration`, `cooldown`, - `promotion` or `adoption` stages in the voting procedure when - amending the economic protocol. - -### Voting listings - - The list calculated at the beginning of each voting period that contains - the staking balance (in number of mutez) of each delegate that owns more - than the minimal stake at that moment. For each delegate, the voting listings - reflect the weight of the vote emitted by the delegate when amending the - economic protocol. \ No newline at end of file +

For a glossary of Tezos terms, see Glossary.

diff --git a/package-lock.json b/package-lock.json index 22a53fb3a..96a3e1819 100644 --- a/package-lock.json +++ b/package-lock.json @@ -29,6 +29,7 @@ "@docusaurus/module-type-aliases": "3.2.1", "chai": "5.0.0", "glob": "10.3.10", + "jsdom": "^24.1.0", "mdast-util-from-markdown": "2.0.0", "mdast-util-mdx": "3.0.0", "micromark-extension-mdxjs": "3.0.0", @@ -4502,6 +4503,18 @@ "node": ">= 10.0.0" } }, + "node_modules/agent-base": { + "version": "7.1.1", + "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.1.tgz", + "integrity": "sha512-H0TSyFNDMomMNJQBn8wFV5YC/2eJ+VXECwOadZJT554xP6cODZHPX3H9QMQECxvrgiSOP1pHjy1sMWQVYJOUOA==", + "dev": true, + "dependencies": { + "debug": "^4.3.4" + }, + "engines": { + "node": ">= 14" + } + }, "node_modules/aggregate-error": { "version": "3.1.0", "resolved": "https://registry.npmjs.org/aggregate-error/-/aggregate-error-3.1.0.tgz", @@ -4709,6 +4722,12 @@ "astring": "bin/astring" } }, + "node_modules/asynckit": { + "version": "0.4.0", + "resolved": "https://registry.npmjs.org/asynckit/-/asynckit-0.4.0.tgz", + "integrity": "sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==", + "dev": true + }, "node_modules/at-least-node": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/at-least-node/-/at-least-node-1.0.0.tgz", @@ -5503,6 +5522,18 @@ "node": ">=10" } }, + "node_modules/combined-stream": { + "version": "1.0.8", + "resolved": "https://registry.npmjs.org/combined-stream/-/combined-stream-1.0.8.tgz", + "integrity": "sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg==", + "dev": true, + "dependencies": { + "delayed-stream": "~1.0.0" + }, + "engines": { + "node": ">= 0.8" + } + }, "node_modules/comma-separated-tokens": { "version": "2.0.3", "resolved": "https://registry.npmjs.org/comma-separated-tokens/-/comma-separated-tokens-2.0.3.tgz", @@ -6077,6 +6108,24 @@ "node": ">=8.0.0" } }, + "node_modules/cssstyle": { + "version": "4.0.1", + "resolved": "https://registry.npmjs.org/cssstyle/-/cssstyle-4.0.1.tgz", + "integrity": "sha512-8ZYiJ3A/3OkDd093CBT/0UKDWry7ak4BdPTFP2+QEP7cmhouyq/Up709ASSj2cK02BbZiMgk7kYjZNS4QP5qrQ==", + "dev": true, + "dependencies": { + "rrweb-cssom": "^0.6.0" + }, + "engines": { + "node": ">=18" + } + }, + "node_modules/cssstyle/node_modules/rrweb-cssom": { + "version": "0.6.0", + "resolved": "https://registry.npmjs.org/rrweb-cssom/-/rrweb-cssom-0.6.0.tgz", + "integrity": "sha512-APM0Gt1KoXBz0iIkkdB/kfvGOwC4UuJFeG/c+yV7wSc7q96cG/kJ0HiYCnzivD9SB53cLV1MlHFNfOuPaadYSw==", + "dev": true + }, "node_modules/csstype": { "version": "3.1.2", "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.1.2.tgz", @@ -6562,6 +6611,19 @@ "lodash-es": "^4.17.21" } }, + "node_modules/data-urls": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/data-urls/-/data-urls-5.0.0.tgz", + "integrity": "sha512-ZYP5VBHshaDAiVZxjbRVcFJpc+4xGgT0bK3vzy1HLN8jTO975HEbuYzZJcHoQEY5K1a0z8YayJkyVETa08eNTg==", + "dev": true, + "dependencies": { + "whatwg-mimetype": "^4.0.0", + "whatwg-url": "^14.0.0" + }, + "engines": { + "node": ">=18" + } + }, "node_modules/dayjs": { "version": "1.11.10", "resolved": "https://registry.npmjs.org/dayjs/-/dayjs-1.11.10.tgz", @@ -6595,6 +6657,12 @@ "url": "https://github.com/sponsors/sindresorhus" } }, + "node_modules/decimal.js": { + "version": "10.4.3", + "resolved": "https://registry.npmjs.org/decimal.js/-/decimal.js-10.4.3.tgz", + "integrity": "sha512-VBBaLc1MgL5XpzgIP7ny5Z6Nx3UrRkIViUkPUdtl9aya5amy3De1gsUUSB1g3+3sExYNjCAsAznmukyxCb1GRA==", + "dev": true + }, "node_modules/decode-named-character-reference": { "version": "1.0.2", "resolved": "https://registry.npmjs.org/decode-named-character-reference/-/decode-named-character-reference-1.0.2.tgz", @@ -6745,6 +6813,15 @@ "robust-predicates": "^3.0.0" } }, + "node_modules/delayed-stream": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/delayed-stream/-/delayed-stream-1.0.0.tgz", + "integrity": "sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ==", + "dev": true, + "engines": { + "node": ">=0.4.0" + } + }, "node_modules/depd": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/depd/-/depd-2.0.0.tgz", @@ -7842,6 +7919,20 @@ "node": ">=6" } }, + "node_modules/form-data": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/form-data/-/form-data-4.0.0.tgz", + "integrity": "sha512-ETEklSGi5t0QMZuiXoA/Q6vcnxcLQP5vdugSpuAyi6SVGi2clPPp+xgEhuMaHC+zGgn31Kd235W35f7Hykkaww==", + "dev": true, + "dependencies": { + "asynckit": "^0.4.0", + "combined-stream": "^1.0.8", + "mime-types": "^2.1.12" + }, + "engines": { + "node": ">= 6" + } + }, "node_modules/form-data-encoder": { "version": "2.1.4", "resolved": "https://registry.npmjs.org/form-data-encoder/-/form-data-encoder-2.1.4.tgz", @@ -8649,6 +8740,18 @@ "safe-buffer": "~5.1.0" } }, + "node_modules/html-encoding-sniffer": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/html-encoding-sniffer/-/html-encoding-sniffer-4.0.0.tgz", + "integrity": "sha512-Y22oTqIU4uuPgEemfz7NDJz6OeKf12Lsu+QC+s3BVpda64lTiMYCyGwg5ki4vFxkMwQdeZDl2adZoqUgdFuTgQ==", + "dev": true, + "dependencies": { + "whatwg-encoding": "^3.1.1" + }, + "engines": { + "node": ">=18" + } + }, "node_modules/html-entities": { "version": "2.4.0", "resolved": "https://registry.npmjs.org/html-entities/-/html-entities-2.4.0.tgz", @@ -8823,6 +8926,19 @@ "node": ">=8.0.0" } }, + "node_modules/http-proxy-agent": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/http-proxy-agent/-/http-proxy-agent-7.0.2.tgz", + "integrity": "sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig==", + "dev": true, + "dependencies": { + "agent-base": "^7.1.0", + "debug": "^4.3.4" + }, + "engines": { + "node": ">= 14" + } + }, "node_modules/http-proxy-middleware": { "version": "2.0.6", "resolved": "https://registry.npmjs.org/http-proxy-middleware/-/http-proxy-middleware-2.0.6.tgz", @@ -8869,6 +8985,19 @@ "node": ">=10.19.0" } }, + "node_modules/https-proxy-agent": { + "version": "7.0.5", + "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-7.0.5.tgz", + "integrity": "sha512-1e4Wqeblerz+tMKPIq2EMGiiWW1dIjZOksyHWSUm1rmuvw/how9hBHZ38lAGj5ID4Ik6EdkOw7NmWPy6LAwalw==", + "dev": true, + "dependencies": { + "agent-base": "^7.0.2", + "debug": "4" + }, + "engines": { + "node": ">= 14" + } + }, "node_modules/human-signals": { "version": "2.1.0", "resolved": "https://registry.npmjs.org/human-signals/-/human-signals-2.1.0.tgz", @@ -9237,6 +9366,12 @@ "node": ">=0.10.0" } }, + "node_modules/is-potential-custom-element-name": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/is-potential-custom-element-name/-/is-potential-custom-element-name-1.0.1.tgz", + "integrity": "sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ==", + "dev": true + }, "node_modules/is-reference": { "version": "3.0.2", "resolved": "https://registry.npmjs.org/is-reference/-/is-reference-3.0.2.tgz", @@ -9430,6 +9565,67 @@ "js-yaml": "bin/js-yaml.js" } }, + "node_modules/jsdom": { + "version": "24.1.0", + "resolved": "https://registry.npmjs.org/jsdom/-/jsdom-24.1.0.tgz", + "integrity": "sha512-6gpM7pRXCwIOKxX47cgOyvyQDN/Eh0f1MeKySBV2xGdKtqJBLj8P25eY3EVCWo2mglDDzozR2r2MW4T+JiNUZA==", + "dev": true, + "dependencies": { + "cssstyle": "^4.0.1", + "data-urls": "^5.0.0", + "decimal.js": "^10.4.3", + "form-data": "^4.0.0", + "html-encoding-sniffer": "^4.0.0", + "http-proxy-agent": "^7.0.2", + "https-proxy-agent": "^7.0.4", + "is-potential-custom-element-name": "^1.0.1", + "nwsapi": "^2.2.10", + "parse5": "^7.1.2", + "rrweb-cssom": "^0.7.0", + "saxes": "^6.0.0", + "symbol-tree": "^3.2.4", + "tough-cookie": "^4.1.4", + "w3c-xmlserializer": "^5.0.0", + "webidl-conversions": "^7.0.0", + "whatwg-encoding": "^3.1.1", + "whatwg-mimetype": "^4.0.0", + "whatwg-url": "^14.0.0", + "ws": "^8.17.0", + "xml-name-validator": "^5.0.0" + }, + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "canvas": "^2.11.2" + }, + "peerDependenciesMeta": { + "canvas": { + "optional": true + } + } + }, + "node_modules/jsdom/node_modules/ws": { + "version": "8.17.1", + "resolved": "https://registry.npmjs.org/ws/-/ws-8.17.1.tgz", + "integrity": "sha512-6XQFvXTkbfUOZOKKILFG1PDK2NDQs4azKQl26T0YS5CxqWLgXajbPZ+h4gZekJyRqFU8pvnbAbbs/3TgRPy+GQ==", + "dev": true, + "engines": { + "node": ">=10.0.0" + }, + "peerDependencies": { + "bufferutil": "^4.0.1", + "utf-8-validate": ">=5.0.2" + }, + "peerDependenciesMeta": { + "bufferutil": { + "optional": true + }, + "utf-8-validate": { + "optional": true + } + } + }, "node_modules/jsesc": { "version": "2.5.2", "resolved": "https://registry.npmjs.org/jsesc/-/jsesc-2.5.2.tgz", @@ -12911,6 +13107,12 @@ "url": "https://github.com/fb55/nth-check?sponsor=1" } }, + "node_modules/nwsapi": { + "version": "2.2.10", + "resolved": "https://registry.npmjs.org/nwsapi/-/nwsapi-2.2.10.tgz", + "integrity": "sha512-QK0sRs7MKv0tKe1+5uZIQk/C8XGza4DAnztJG8iD+TpJIORARrCxczA738awHrZoHeTjSSoHqao2teO0dC/gFQ==", + "dev": true + }, "node_modules/object-assign": { "version": "4.1.1", "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz", @@ -14099,6 +14301,12 @@ "node": ">= 0.10" } }, + "node_modules/psl": { + "version": "1.9.0", + "resolved": "https://registry.npmjs.org/psl/-/psl-1.9.0.tgz", + "integrity": "sha512-E/ZsdU4HLs/68gYzgGTkMicWTLPdAftJLfJFlLUAAKZGkStNU72sZjT66SnMDVOfOWY/YAoiD7Jxa9iHvngcag==", + "dev": true + }, "node_modules/punycode": { "version": "1.4.1", "resolved": "https://registry.npmjs.org/punycode/-/punycode-1.4.1.tgz", @@ -14132,6 +14340,12 @@ "url": "https://github.com/sponsors/ljharb" } }, + "node_modules/querystringify": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/querystringify/-/querystringify-2.2.0.tgz", + "integrity": "sha512-FIqgj2EUvTa7R50u0rGsyTftzjYmv/a3hO345bZNrqabNqjtgiDMgmo4mkUjd+nzU5oF3dClKqFIPUKybUyqoQ==", + "dev": true + }, "node_modules/queue": { "version": "6.0.2", "resolved": "https://registry.npmjs.org/queue/-/queue-6.0.2.tgz", @@ -15060,6 +15274,12 @@ "resolved": "https://registry.npmjs.org/robust-predicates/-/robust-predicates-3.0.2.tgz", "integrity": "sha512-IXgzBWvWQwE6PrDI05OvmXUIruQTcoMDzRsOd5CDvHCVLcLHMTSYvOK5Cm46kWqlV3yAbuSpBZdJ5oP5OUoStg==" }, + "node_modules/rrweb-cssom": { + "version": "0.7.1", + "resolved": "https://registry.npmjs.org/rrweb-cssom/-/rrweb-cssom-0.7.1.tgz", + "integrity": "sha512-TrEMa7JGdVm0UThDJSx7ddw5nVm3UJS9o9CCIZ72B1vSyEZoziDqBYP3XIoi/12lKrJR8rE3jeFHMok2F/Mnsg==", + "dev": true + }, "node_modules/rtl-detect": { "version": "1.1.2", "resolved": "https://registry.npmjs.org/rtl-detect/-/rtl-detect-1.1.2.tgz", @@ -15149,6 +15369,18 @@ "resolved": "https://registry.npmjs.org/sax/-/sax-1.3.0.tgz", "integrity": "sha512-0s+oAmw9zLl1V1cS9BtZN7JAd0cW5e0QH4W3LWEK6a4LaLEA2OTpGYWDY+6XasBLtz6wkm3u1xRw95mRuJ59WA==" }, + "node_modules/saxes": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/saxes/-/saxes-6.0.0.tgz", + "integrity": "sha512-xAg7SOnEhrm5zI3puOOKyy1OMcMlIJZYNJY7xLBwSze0UjhPLnWfj2GF2EpT0jmzaJKIWKHLsaSSajf35bcYnA==", + "dev": true, + "dependencies": { + "xmlchars": "^2.2.0" + }, + "engines": { + "node": ">=v12.22.7" + } + }, "node_modules/scheduler": { "version": "0.23.0", "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.23.0.tgz", @@ -16020,6 +16252,12 @@ "url": "https://github.com/fb55/entities?sponsor=1" } }, + "node_modules/symbol-tree": { + "version": "3.2.4", + "resolved": "https://registry.npmjs.org/symbol-tree/-/symbol-tree-3.2.4.tgz", + "integrity": "sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw==", + "dev": true + }, "node_modules/tapable": { "version": "2.2.1", "resolved": "https://registry.npmjs.org/tapable/-/tapable-2.2.1.tgz", @@ -16210,6 +16448,60 @@ "node": ">=6" } }, + "node_modules/tough-cookie": { + "version": "4.1.4", + "resolved": "https://registry.npmjs.org/tough-cookie/-/tough-cookie-4.1.4.tgz", + "integrity": "sha512-Loo5UUvLD9ScZ6jh8beX1T6sO1w2/MpCRpEP7V280GKMVUQ0Jzar2U3UJPsrdbziLEMMhu3Ujnq//rhiFuIeag==", + "dev": true, + "dependencies": { + "psl": "^1.1.33", + "punycode": "^2.1.1", + "universalify": "^0.2.0", + "url-parse": "^1.5.3" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/tough-cookie/node_modules/punycode": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.3.1.tgz", + "integrity": "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==", + "dev": true, + "engines": { + "node": ">=6" + } + }, + "node_modules/tough-cookie/node_modules/universalify": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/universalify/-/universalify-0.2.0.tgz", + "integrity": "sha512-CJ1QgKmNg3CwvAv/kOFmtnEN05f0D/cn9QntgNOQlQF9dgvVTHj3t+8JPdjqawCHk7V/KA+fbUqzZ9XWhcqPUg==", + "dev": true, + "engines": { + "node": ">= 4.0.0" + } + }, + "node_modules/tr46": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/tr46/-/tr46-5.0.0.tgz", + "integrity": "sha512-tk2G5R2KRwBd+ZN0zaEXpmzdKyOYksXwywulIX95MBODjSzMIuQnQ3m8JxgbhnL1LeVo7lqQKsYa1O3Htl7K5g==", + "dev": true, + "dependencies": { + "punycode": "^2.3.1" + }, + "engines": { + "node": ">=18" + } + }, + "node_modules/tr46/node_modules/punycode": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.3.1.tgz", + "integrity": "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==", + "dev": true, + "engines": { + "node": ">=6" + } + }, "node_modules/trim-lines": { "version": "3.0.1", "resolved": "https://registry.npmjs.org/trim-lines/-/trim-lines-3.0.1.tgz", @@ -16707,6 +16999,16 @@ "url": "https://opencollective.com/webpack" } }, + "node_modules/url-parse": { + "version": "1.5.10", + "resolved": "https://registry.npmjs.org/url-parse/-/url-parse-1.5.10.tgz", + "integrity": "sha512-WypcfiRhfeUP9vvF0j6rw0J3hrWrw6iZv3+22h6iRMJ/8z1Tj6XfLP4DsUix5MhMPnXpiHDoKyoZ/bdCkwBCiQ==", + "dev": true, + "dependencies": { + "querystringify": "^2.1.1", + "requires-port": "^1.0.0" + } + }, "node_modules/util-deprecate": { "version": "1.0.2", "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz", @@ -16819,6 +17121,18 @@ "url": "https://opencollective.com/unified" } }, + "node_modules/w3c-xmlserializer": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/w3c-xmlserializer/-/w3c-xmlserializer-5.0.0.tgz", + "integrity": "sha512-o8qghlI8NZHU1lLPrpi2+Uq7abh4GGPpYANlalzWxyWteJOCsr/P+oPBA49TOLu5FTZO4d3F9MnWJfiMo4BkmA==", + "dev": true, + "dependencies": { + "xml-name-validator": "^5.0.0" + }, + "engines": { + "node": ">=18" + } + }, "node_modules/watchpack": { "version": "2.4.0", "resolved": "https://registry.npmjs.org/watchpack/-/watchpack-2.4.0.tgz", @@ -16853,6 +17167,15 @@ "resolved": "https://registry.npmjs.org/web-worker/-/web-worker-1.2.0.tgz", "integrity": "sha512-PgF341avzqyx60neE9DD+XS26MMNMoUQRz9NOZwW32nPQrF6p77f1htcnjBSEV8BGMKZ16choqUG4hyI0Hx7mA==" }, + "node_modules/webidl-conversions": { + "version": "7.0.0", + "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-7.0.0.tgz", + "integrity": "sha512-VwddBukDzu71offAQR975unBIGqfKZpM+8ZX6ySk8nYhVoo5CYaZyzt3YBvYtRtO+aoGlqxPg/B87NGVZ/fu6g==", + "dev": true, + "engines": { + "node": ">=12" + } + }, "node_modules/webpack": { "version": "5.89.0", "resolved": "https://registry.npmjs.org/webpack/-/webpack-5.89.0.tgz", @@ -17187,6 +17510,52 @@ "node": ">=0.8.0" } }, + "node_modules/whatwg-encoding": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/whatwg-encoding/-/whatwg-encoding-3.1.1.tgz", + "integrity": "sha512-6qN4hJdMwfYBtE3YBTTHhoeuUrDBPZmbQaxWAqSALV/MeEnR5z1xd8UKud2RAkFoPkmB+hli1TZSnyi84xz1vQ==", + "dev": true, + "dependencies": { + "iconv-lite": "0.6.3" + }, + "engines": { + "node": ">=18" + } + }, + "node_modules/whatwg-encoding/node_modules/iconv-lite": { + "version": "0.6.3", + "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz", + "integrity": "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==", + "dev": true, + "dependencies": { + "safer-buffer": ">= 2.1.2 < 3.0.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/whatwg-mimetype": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/whatwg-mimetype/-/whatwg-mimetype-4.0.0.tgz", + "integrity": "sha512-QaKxh0eNIi2mE9p2vEdzfagOKHCcj1pJ56EEHGQOVxp8r9/iszLUUV7v89x9O1p/T+NlTM5W7jW6+cz4Fq1YVg==", + "dev": true, + "engines": { + "node": ">=18" + } + }, + "node_modules/whatwg-url": { + "version": "14.0.0", + "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-14.0.0.tgz", + "integrity": "sha512-1lfMEm2IEr7RIV+f4lUNPOqfFL+pO+Xw3fJSqmjX9AbXcXcYOkCe1P6+9VBZB6n94af16NfZf+sSk0JCBZC9aw==", + "dev": true, + "dependencies": { + "tr46": "^5.0.0", + "webidl-conversions": "^7.0.0" + }, + "engines": { + "node": ">=18" + } + }, "node_modules/which": { "version": "2.0.2", "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz", @@ -17374,6 +17743,21 @@ "xml-js": "bin/cli.js" } }, + "node_modules/xml-name-validator": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/xml-name-validator/-/xml-name-validator-5.0.0.tgz", + "integrity": "sha512-EvGK8EJ3DhaHfbRlETOWAS5pO9MZITeauHKJyb8wyajUfQUenkIg2MvLDTZ4T/TgIcm3HU0TFBgWWboAZ30UHg==", + "dev": true, + "engines": { + "node": ">=18" + } + }, + "node_modules/xmlchars": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/xmlchars/-/xmlchars-2.2.0.tgz", + "integrity": "sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw==", + "dev": true + }, "node_modules/y18n": { "version": "5.0.8", "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz", diff --git a/package.json b/package.json index 5ce291541..88278a3bf 100644 --- a/package.json +++ b/package.json @@ -5,7 +5,7 @@ "scripts": { "docusaurus": "docusaurus", "start": "docusaurus start", - "build": "docusaurus build", + "build": "node ./src/scripts/process_downloaded_glossary.js && docusaurus build", "swizzle": "docusaurus swizzle", "deploy": "docusaurus deploy", "clear": "docusaurus clear", @@ -36,6 +36,7 @@ "@docusaurus/module-type-aliases": "3.2.1", "chai": "5.0.0", "glob": "10.3.10", + "jsdom": "24.1.0", "mdast-util-from-markdown": "2.0.0", "mdast-util-mdx": "3.0.0", "micromark-extension-mdxjs": "3.0.0", diff --git a/src/components/GlossaryAnchorScript.jsx b/src/components/GlossaryAnchorScript.jsx new file mode 100644 index 000000000..18d5be5d4 --- /dev/null +++ b/src/components/GlossaryAnchorScript.jsx @@ -0,0 +1,10 @@ +import Head from '@docusaurus/Head'; +import useBaseUrl from '@docusaurus/useBaseUrl'; + +export default function GlossaryAnchorScript() { + return ( + + + + ); +} \ No newline at end of file diff --git a/src/css/custom.css b/src/css/custom.css index fb43c4ea9..b9ac48544 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -296,3 +296,7 @@ article a[target="_blank"]:after { .language-archetype .token.expr { font-style: italic; } + +#imported-glossary dt { + font-weight: bold; +} diff --git a/src/scripts/process_downloaded_glossary.js b/src/scripts/process_downloaded_glossary.js new file mode 100644 index 000000000..fd1f73b81 --- /dev/null +++ b/src/scripts/process_downloaded_glossary.js @@ -0,0 +1,96 @@ +// Convert the glossary downloaded from the Octez docs to something that can be shown on this site + +const fs = require('fs'); +const path = require('path'); +const https = require('https'); +const { spawn } = require('child_process'); +const jsdom = require('jsdom'); +const { JSDOM } = jsdom; + +// Utility function to download files +const download = async (url, filename) => { + const file = fs.createWriteStream(filename); + return new Promise((resolve, reject) => { + const request = https.get(url, (response) => { + response.pipe(file); + file.on('finish', () => { + file.close(); + console.log('Downloaded', url, 'and saved as', filename); + resolve(); + }); + file.on('error', (e) => { + reject(e); + }); + }); + }); +} + +const process_glossary = async () => { + + const repoRoot = path.resolve(__dirname, '../../'); + + const buildFolder = path.resolve(repoRoot, '_glossaryBuild/'); + if (!fs.existsSync(buildFolder)){ + fs.mkdirSync(buildFolder, { recursive: true }); + } + + // Download glossary and conversion script + const glossarySourceFileName = path.resolve(buildFolder, 'glossary.html'); + const glossaryFilePromise = download('https://tezos.gitlab.io/active/glossary.html', glossarySourceFileName); + await Promise.resolve(glossaryFilePromise); + + const downloadedGlossaryDom = new JSDOM(await fs.promises.readFile(glossarySourceFileName, 'utf8')); + + // Trim html header, body, and such out + const trimmed = downloadedGlossaryDom.window.document.querySelector('#glossary'); + + // Trim out H1 + const h1 = trimmed.querySelector('h1'); + h1.remove(); + + // External links in new window + const externalLinks = trimmed.querySelectorAll('a.external'); + externalLinks.forEach((link) => { + link.setAttribute('target', '_blank'); + }); + + // Internal links go to Octez docs + const internalLinks = trimmed.querySelectorAll('a.reference.internal'); + internalLinks.forEach((link) => { + if (link.getAttribute('href').startsWith('../')) { + const newHref = link.getAttribute('href').replace('../', 'https://tezos.gitlab.io/'); + link.setAttribute('href', newHref); + link.setAttribute('target', '_blank'); + } else if (!link.getAttribute('href').startsWith('#')) { + link.setAttribute('href', 'https://tezos.gitlab.io/active/' + link.getAttribute('href')); + link.setAttribute('target', '_blank'); + } + }); + + // Wrap with
to apply custom styles + const wrapper = new JSDOM('
'); + const imported_glossary = wrapper.window.document.querySelector('div#imported-glossary'); + imported_glossary.appendChild(trimmed); + + // Convert to string and remove line breaks to prevent MDX processing from making them into paragraph tags + let imported_glossary_str = imported_glossary.outerHTML; + imported_glossary_str = imported_glossary_str.replace(/([^>])$\n/gm, '$1 '); + imported_glossary_str = imported_glossary_str.replace(/>$\n/gm, '>'); + + // Convert class to className because we're in MDX now + imported_glossary_str = imported_glossary_str.replaceAll('class="', 'className="'); + + // Overwrite existing glossary.md file + let outputString = '---\ntitle: Glossary\n---\n\n'; + // Fix for anchor links taking you too far down the page + outputString += 'import GlossaryAnchorScript from \'@site/src/components/GlossaryAnchorScript\';\n\n\n\n'; + outputString += imported_glossary_str; + const glossaryFilePath = path.resolve(repoRoot, 'docs/overview/glossary.md'); + if (fs.existsSync(glossaryFilePath)){ + fs.unlinkSync(glossaryFilePath); + } + await fs.promises.writeFile(glossaryFilePath, outputString, 'utf8'); + console.log('Wrote new glossary to', glossaryFilePath); +} + +process_glossary(); diff --git a/static/scripts/anchorScript.js b/static/scripts/anchorScript.js new file mode 100644 index 000000000..4b66fa210 --- /dev/null +++ b/static/scripts/anchorScript.js @@ -0,0 +1,4 @@ +// Fix for anchor links taking you too far down the page +window.addEventListener("hashchange", function () { + window.scrollTo(window.scrollX, window.scrollY - 100); +}); \ No newline at end of file