diff --git a/.gitignore b/.gitignore index 3bf266c..73481fd 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,7 @@ # Production /build + # Generated files .docusaurus .cache-loader diff --git a/docs/developers/getting_started.md b/docs/developers/getting_started.md deleted file mode 100644 index 627eb44..0000000 --- a/docs/developers/getting_started.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Getting Started - -This quickstart is tailored for developers eager to connect with and explore the capabilities of the Stability Testnet and Global Trust Network (GTN) directly. This guide is designed for developers aiming to craft decentralized applications (dApps), enthusiasts keen on engaging with Stability's blockchain, and anyone interested in understanding what sets Stability apart from traditional EVMs and smart contracts. - -## Prerequisites - -This tutorial presumes a foundational understanding of blockchain technology and familiarity with tools that interact directly with the blockchain. For example, smart contracts and development tools such as Remix and Viem. - -## Register for an API Key - -Global Trust Network (GTN) and Stability Testnet employ API keys to manage transactions. On Global Trust Network, an API key is required to perform write transactions. On Stability Testnet, each address is given a limited number of free transactions without an API key using our public RPC. To increase the number of transactions that a certain user can execute on either chain, users are required to sign up with our [Account Manager](https://account.stabilityprotocol.com/keys) for their very own private RPC address. Only an e-mail is required. - -### 2. Sign Up For An API Key - -#### Step 1 - Navigate to [Stability Portal](https://portal.stabilityprotocol.com/) - -#### Step 2 - Select Your Preferred Registration - -![Stability Account Portal Screen with Login Options](../../static/img/Portal_Account_Register.png) - -On this screen, select your preferred method of registration. For this tutorial, we will be following the Google sign-in path. You may also similarly log in via Email. - -If you opt to register via email, ensure you can verify your email address. - -#### Step 3 - Select Your Preferred Network - -![Stability Account Portal Screen with Select Network Dropdown Highlighted](../../static/img/Portal_Select_Network.png) - -Using the dropdown menu on the top right, select the network you wish to generate an API Key on. Currently, you can choose GTN or Testnet. - -#### Step 4 - Click the `Create New Key` Button - -![Stability Account Portal Screen with Create API Key Button Highlighted](../../static/img/Portal_Create_API_Key.png) - -#### Step 5 - Congrats! You've created an API Key. - -![Stability Account Portal Screen with View Details Button Highlighted ](../../static/img/Portal_View_Details.png) - -To view your personal RPC URL, click the `View Details` button next to your API key, followed by the `Setup Instructions` button. - -Here, you will find your personal RPC URL, as well a link that will add either network to your Metamask in one click. - -### 3a. Add Network Automatically to Metamask + Other Compatible Wallets - -To add your custom RPC to your browser extension wallet, which will allow you to use Global Trust Network or Stability Testnet, click the `Add To Metamask` button. This will work with Metamask as well as many other browser extension based wallets. - -If you are not able to add the network to your wallet, you may have to add the network manually. Follow the instructions below. - -### 3b. Add Network Manually to Metamask - -In the event you are unable to add your wallet automatically via clicking the Metamask Fox Logo above, or you wish to add the network manually, simply follow the steps below. - -#### Step 1 - Navigate to `Settings` in Metamask. - -![Metamask Main Screen with Settings Highlighted](../../static/img/metamasksettings.png) - -#### Step 2 - Click on the `Networks` tab. - -![Metamask Settings Screen with Networks Highlighted](../../static/img/metamasknetworks.png) - -#### Step 3 - Click the `Add a network` button. - -![Metamask Networks Screen with 'Add a network' Button Highlighted](../../static/img/metamaskaddnetwork.png) - -#### Step 4 - Click the `Add a network manually` text link. - -![Metamask Add Network Screen with 'Add a network manually' Highlighted](../../static/img/metamaskaddanetworkmanually.png) - -#### Step 5 - Go to the [Stability Account Manager](https://account.stabilityprotocol.com/keys) and copy your API Key. - -![Stability Account Manager Screen with an Example API Key Highlighted](../../static/img/apikeyhighlight.png) - -#### Step 6 - Fill out the network settings using the details below. Be sure to replace the `YOUR_API_KEY` with your own API Key. Afterward, click Save. - -![Metamask Manual Network Screen with Details Filled and Save Button Highlighted](../../static/img/metamaskmanualnetworksave.png) - -| **Property** | **Global Trust Network** | **Stability Testnet** | -| ------------------ | ---------------------------------------------------- | ------------------------------------------------------------ | -| Network Name | Global Trust Network | Stability Test Net | -| New RPC URL | `https://rpc.stabilityprotocol.com/zgt/YOUR_API_KEY` | `https://rpc.testnet.stabilityprotocol.com/zgt/YOUR_API_KEY` | -| Chain ID | 101010 | 20180427 | -| Currency Symbol | FREE | FREE | -| Block Explorer URL | `https://stability.blockscout.com/` | `https://explorer.stble.io/testnet/blocks/` | -| Request Limit | 200 Per Minute / Higher Limits Available | 200 Per Minute / Higher Limits Available | -| Max Batch Size | 40 | 40 | - -### 4. Configure for Zero Fees - -It is important to note that Stability requires you to not set the `Max Base Fee` and `Max Priority Fee` to a non-zero number. When using libraries such as `ethers`, this must be coded into the transaction. A live example of where these values are explicitly coded to zero is available in the source code of our [Data Store App](https://github.com/stabilityprotocol/datastoredapp). - -To set this in Metamask, for the your first transaction, you will have to manually set these values to zero. It is advised that you save these values as the default setting for our network. - -![Adjust Gas Icon in Metamask](../../static/img/adjustgas.png) - -On your first transaction, A MetaMask popup will appear to confirm the transaction. Click the pencil icon in the estimated fee box. - -![Advanced Gas Fee Settings in Metamask](../../static/img/advancegasscreen.png) - -This will allow you to customize Metamask for zero gas transactions. Click the advanced gas fee icon. Set your `Max Base Fee` and `Priority Fee` to zero. Click the `Save these values as my default...` checkbox to avoid having to manually set the gas in the future. - -### 5. Review What Is Different With Stability - -We highly recommend reviewing the section on [What Is Different](./what_is_different.md) regarding Stability as opposed to traditional Ethereum Virtual Machine (EVM) blockchains. Understanding these distinctions is crucial for developers looking to create decentralized applications (dApps) on the Stability platform, especially since certain functionalities, like native token transfers, will not operate in the same way on Stability. It is important to note that Stablity supports Solidity version 0.8.24 or lower. - -It is highly recommended you check out [Example dApps](../how_stability_works/example_apps.md) for examples of coding with Stability's unique attributes. Many of our examples are open-sourced on [Github](https://github.com/stabilityprotocol). - -## Now Start Swimming - -Your free API key allows for 1,000 free transactions per a month, and 200 requests per minute to our API. You can track your usage on the `Account Portal` page. To increase your limits, click the `Increase Limits` button in the `Account Portal` to explore our plans. - -Armed with this knowledge and your API key, you're well-prepared to embark on your development journey with the Stability Network. Dive in and start innovating! Happy hacking! diff --git a/docs/developers/rate_limits.md b/docs/developers/rate_limits.md deleted file mode 100644 index 8425049..0000000 --- a/docs/developers/rate_limits.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -sidebar_position: 6 ---- - -# RPC Rate Limits - -Our RPC endpoint enforces a rate limit of **60 requests per minute** for the free tier. If your usage exceeds this limit, additional requests within the same rolling minute will be blocked, and return a 429 status code. The limit will reset at the end of the rolling minute. We also offer paid tiers with higher request allowances for high-volume or enterprise-level needs. - -## What is a Request? - -A “request” is any individual call made to the RPC endpoint. Each operation—whether retrieving the latest block number, submitting a transaction, or querying transaction details—counts toward this total. Even if your application is executing a single user action (e.g., sending a transaction on the blockchain), it may internally make multiple RPC calls. - -![Stability Portal Screen with Rate Limiter Information](../../static/img/rate_limiter.png) - -Keep an eye on your usage to avoid hitting the 60 requests-per-minute cap. You can track your current usage per a minute in your [Stability Portal](https://portal.stabilityprotocol.com/). If you anticipate higher throughput, please consider one of our paid tiers with enhanced rate limits. - -## How to Increase Limits? - -To increase your limits, click the **Increase Limits** button in the [Stability Portal](https://portal.stabilityprotocol.com/) to contact us. Our starting tier allows for **200 requests per minute**, with higher options available for customized plans. diff --git a/docs/developers/what_is_different.md b/docs/developers/what_is_different.md deleted file mode 100644 index 6d43f14..0000000 --- a/docs/developers/what_is_different.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -sidebar_position: 2 ---- - -# What Is Different In Stability - -## Introduction - -Stability is compatible with the EVM web3 development environments you're already familiar with, such as Ethers, Viem, Hardhat, Foundry, etc. This compatibility allows developers to seamlessly transition their existing skills and projects to Stability without having to navigate a steep learning curve associated with entirely new development environments. - -One of the key differences with Stability is its lack of a native token. This fundamental change affects the execution of transactions that typically involve the transfer of native tokens, which is a core functionality in many Ethereum-based applications. As a result, developers will find that some standard operations and Solidity functionalities will not work as expected on Stability. - -# What Is Different In Stability - -One of the key differences with Stability is its lack of a native token. This fundamental change affects the execution of transactions that typically involve the transfer of native tokens, which is a core functionality in many Ethereum-based applications. As a result, developers will find that some standard operations and Solidity functionalities will not work as expected on Stability. - -## Examples - -### Stability is an EVM Compatible with Solidity up to 0.8.24 - -Stability makes use of the Frontier EVM Pallet. Currently, Stability has not implemented the Cancun update. Developers must compile Solidity at version 0.8.24 or lower. - -### Gas Cost and Priority Fee Must Not Be Explicitly Set - -On Stability, gas costs and priority fees are not applicable in the same way they are on traditional EVM-based blockchains due to the absence of a native token. `gasPrice` and `maxPriorityFeePerGas` must not be explicitly set to a non-zero number. No definition, or explicit definition to 0, is required. - -Here is an example of how this can be achieved using ethers.js: - -Ethers v5 - -```javascript -const tx = { - ... - gasPrice: ethers.utils.parseUnits("0", "gwei"), - maxPriorityFeePerGas: ethers.utils.parseUnits("0", "gwei"), -}; -``` - -Ethers v6 - -```javascript -const tx = { - ... - maxFeePerGas: 0n - maxPriorityFeePerGas: 0n -}; -``` - -### Native Token Value Transfers - -On Stability, functions intended for transferring native gas tokens, such as `.transfer`, `.send`, and any operations involving `msg.value`, are not supported. Attempts to execute such transactions will automatically revert. This is a significant departure from traditional Ethereum-based smart contract interactions, where these methods are commonly used to manage and transfer Ether between accounts. For instance, the following Solidity code snippets illustrate transactions that would **fail** on Stability: - -```bash -function sendViaTransfer(address payable _to) public payable { - _to.transfer(msg.value); -} ->> FAIL - -function sendViaSend(address payable _to) public payable { - bool sent = _to.send(msg.value); - require(sent, "Failed to send Ether"); -} ->> FAIL - -function sendViaCall(address payable _to) public payable { - (bool sent, bytes memory data) = _to.call{value: msg.value}(""); - require(sent, "Failed to send Ether"); -} ->> FAIL -``` - -### Address Balance - -On Stability, the address.balance operation will not function as expected. This operation, which is used to retrieve the balance of Ether (or any native token) held by an address, relies on the existence of a native token. For example: - -```bash -function getBalance() public view returns (uint) { - return address(this).balance; - } ->> Returns the selected DNT balance -``` - -### Payable Declarations - -In the context of Stability, declaring functions and addresses as payable is unnecessary since the blockchain does not support native token transactions. Instead, developers should utilize the ERC-20 token standard for transactions involving token transfers. This approach involves first approving the transfer of tokens to a contract, followed by the contract executing the transfer, mirroring the functionality provided by ERC-20 tokens. - -### Receive() and Fallback() - -The receive() and fallback() functions in Solidity are designed to handle incoming transactions and unspecified function calls, respectively. However, without the capability to transfer native tokens, these functions lose their primary purpose on Stability. Developers will need to consider alternative methods for contract interactions that do not rely on direct value transfers. - -## Review - -While developing on Stability offers a familiar experience to working with other EVM-compatible blockchains, the absence of a native token introduces specific considerations that developers must account for. This unique characteristic of Stability necessitates a cautious approach to smart contract and backend development, ensuring that applications are designed with these limitations in mind. diff --git a/docs/developers/zkt.md b/docs/developers/zkt.md deleted file mode 100644 index 40242cf..0000000 --- a/docs/developers/zkt.md +++ /dev/null @@ -1,311 +0,0 @@ ---- -sidebar_position: 6 ---- - -# Zero-Knowledge Transactions (Beta) - -### Overview - -Zero-Knowledge Transactions, ZKT, is a feature built on the **Stability Blockchain** that simplifies blockchain interactions by enabling users to submit messages directly to the blockchain via HTTP POST requests. This is an experimental aspect of Stability, aimed at making blockchain interactions as simple as possible. - -An open-source GitHub repository, [Stability Publisher](https://github.com/stabilityprotocol/stability-publisher-dapp) is available for exploring this feature. There is a live demo available [here](https://stabilityprotocol.github.io/stability-publisher-dapp/). - -To start experimenting, we recommend signing up for a free API Key on the [Stability Portal](https://account.stabilityprotocol.com/keys). A public RPC is available for experimentation, though please note that it may be limited. - -- Mainnet: `https://rpc.stabilityprotocol.com/zkt/try-it-out` -- Testnet: `https://rpc.testnet.stabilityprotocol.com/zkt/try-it-out` - -### ZKT OpenAPI Specification - -Click [here](https://stabilityprotocol.github.io/stability-api-docs/) to go to our OpenAPI documentation site for the Zero-Knowledge Transactions (ZKT) API. This includes the request schemas (V1 and V2), response objects (success or error), and error fields. This link also contains a download link for the specification. - -### How to Use the Specification - -- You can copy the **OpenAPI YAML** above into a file named `openapi.yaml` (or similar). -- This specification is compatible with tools like Swagger UI, Redoc, or any OpenAPI v3.0.3-compatible library. -- It documents how to submit V1 and V2 style transactions, along with the standardized success and error response formats. - ---- - -**Tip**: If you want to keep a **separate file** for your OpenAPI definition, simply copy the YAML from the code block and store it in your repository (e.g., `docs/zkt-openapi.yaml`). Then you can reference it from your docs or integrate it into your CI/CD pipelines for automatic generation of client libraries, etc. - ---- - -### Architecture Overview - -The ZKT solution is designed around a RESTful service that accepts HTTP requests from clients, verifies and processes the data, and then submits it to the Stability Blockchain. - -The **API Gateway** serves as the entry point for all requests, responsible for: - -- **Authentication**: Verifies that the transaction is submitted using a private or public API key. Users are able to create their own API Key on the [Stability Portal](https://account.stabilityprotocol.com/keys) -- **Data Validation**: Verifying the structure of incoming JSON data, specifically checking the presence of required fields such as `arguments`. -- **Network**: This RPC endpoint API is available on both **Testnet** and **Mainnet**. - -**Endpoints**: - -- **POST /zkt/try-it-out**: Public endpoint for submitting messages to the blockchain. Note this endpoint may be limited. Any transactions submitted to this account are signed by a single account - `0x7f521250d3aacba194dbb33427ffea2c546b433d`. You can view this account on our [Testnet Explorer](https://explorer.stble.io/testnet/address/0x7f521250d3aacba194dbb33427ffea2c546b433d/) and our [Mainnet Explorer](https://stability.blockscout.com/address/0x7F521250d3AAcba194dBB33427fFEa2C546B433d). -- **POST /zkt/your-api-key**: An authenticated endpoint for submitting messages to the blockchain. To obtain a free API Key, please visit [Stability Portal](https://account.stabilityprotocol.com/keys). Transactions submitted via this endpoint are signed by a wallet exclusive to your API key. - -### Data Flow Example - -1. **Client Request**: - - ```json - { - "arguments": "Hello, Blockchain!" - } - ``` - -2. **API Gateway Validation**: - - Checks for `"arguments"` field. -3. **ZKT Processing**: - - - Constructs and signs a transaction. - -4. **Sequencer**: - - Broadcasts the transaction. - ---- - -### Security Considerations - -- **API Rate Limiting**: Enforced at the API Gateway to prevent spam or denial-of-service attacks. -- **Data Privacy**: Although messages are public, the initator of the transaction is unknown when using the public key. -- **Max Payload**: The maximum size of a ZKT transaction payload is 1 MB. - -### Error Handling - -- **Validation Errors**: Returned if the request body is missing required fields or contains incorrect formats. -- **Network Errors**: Handled gracefully with retry logic if the transaction fails to broadcast due to network issues. | - ---- - -### Basic Request Example - Write Message - -Below is an example of a POST request that posts a simple message to the blockchain using ZKT. - -Request: - -`Linux/macOS Shell` - -```bash -curl -X POST "https://rpc.stabilityprotocol.com/zkt/try-it-out" \ --H "Content-Type: application/json" \ ---data '{ "arguments": "Your message here" }' -``` - -`Windows Command Prompt` - -```bash -curl -X POST "https://rpc.stabilityprotocol.com/zkt/try-it-out" -H "Content-Type: application/json" --data "{ \"arguments\": \"Your message here\" }" -``` - -Response: - -```json -{ - "success": true, - "hash": "0x48b3861c7e04e82fd7bfcec4a1e370950abb65851b6a676515bbc8bee01b470d" -} -``` - ---- - -## Advanced Features - -ZKT extends its capabilities beyond simple message posting by allowing direct interaction with smart contracts on the Stability Blockchain. This feature enables users to perform complex operations such as: - -- **Executing Smart Contract Functions**: Invoke any function defined in a smart contract, whether it's to read data (view functions) or modify the blockchain state (transactional functions). -- **Custom Transactions**: Craft transactions that interact with decentralized applications (dApps) without the need for specialized blockchain development tools. -- **Simplified Interaction Model**: Use standard HTTP POST requests to perform actions that would typically require a blockchain client or wallet software. - ---- - -### Explanation of Advanced Request Parameters - -When interacting with smart contract functions via the ZKT endpoint, the request body should be a JSON object containing the following fields: - -| Field | Description | -| ----------- | ------------------------------------------------------------------------------------------------------ | -| `abi` | Array of ABI entries (functions/events) the service needs to encode / decode your call. | -| `to` | Address of the target smart contract. | -| `method` | Name of the contract function to invoke. | -| `arguments` | Array of arguments for `method` (empty array `[]` if none). | -| `id` | Optional request identifier for matching responses. | -| `wait` | Optional boolean; if `true`, the call blocks until the transaction is mined and a receipt is returned. | - ---- - -### Explanation of Advanced Response Parameters - -The response will be a JSON object containing: - -| Field | Description | -| :------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| success | A boolean indicating whether the request was successful. | -| transactionHash or output | Depending on whether the function is a state-changing (write) or view (read) operation, the response will contain either the transaction hash or the output data. | -| id | The identifier corresponding to the request. | - ---- - -### Advanced Request Example - Storage Contract - -Below is an example of a POST request that interacts with deployed smart contract on Stability Testnet. - -**_Smart Contract Read Request_**: - -This is a sample request that reads the `getFile` function of an example smart contract deployed on Stability Testnet. The smart contract is a simple storage contract that stores a file hash as well as a file name. The following request uses the file hash to retrieve the owner of the file, the file name, and confirmation of the file hash. - -Request: - -`Linux/macOS Shell` - -```bash -curl -X POST https://rpc.testnet.stabilityprotocol.com/zkt/try-it-out \ --H "Content-Type: application/json" \ --d '{ - "abi": [ - "function storeFile(string fileName, bytes32 fileHash)", - "function getFile(bytes32 fileHash) view returns (tuple(address owner, string fileName, bytes32 fileHash))", - "event FileStored(address indexed owner, string fileName, bytes32 fileHash)" - ], - "to": "0xaDf4a1165737b406aD510045d4562BE30C14C276", - "method": "getFile", - "id": 2, - "arguments": [ - "0x8e21513d95607300128ceb8bd985f87ea157a5e4cb416b070ca02e9689f9c26c" - ] -}' -``` - -`Windows Command Prompt` - -```bash -curl -X POST https://rpc.testnet.stabilityprotocol.com/zkt/try-it-out -H "Content-Type: application/json" -d "{ \"abi\": [ \"function storeFile(string fileName, bytes32 fileHash)\", \"function getFile(bytes32 fileHash) view returns (tuple(address owner, string fileName, bytes32 fileHash))\", \"event FileStored(address indexed owner, string fileName, bytes32 fileHash)\" ], \"to\": \"0xaDf4a1165737b406aD510045d4562BE30C14C276\", \"method\": \"getFile\", \"id\": 2, \"arguments\": [ \"0x8e21513d95607300128ceb8bd985f87ea157a5e4cb416b070ca02e9689f9c26c\" ] }" -``` - -Response: - -```json -{ - "success": true, - "output": [ - "0xFac55168086cfE3284b5874Ae2738a68eE6710D2", - "example.txt", - "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" - ], - "id": 2 -} -``` - -**_Smart Contract Write Request_**: - -This is a sample request that uses the `storeFile` function of an example smart contract deployed on Stability Testnet. Change the `arguments` parameter to store your own file. - -Request: - -`Linux/macOS Shell` - -```bash -curl -X POST https://rpc.testnet.stabilityprotocol.com/zkt/try-it-out \ --H "Content-Type: application/json" \ --d '{ - "abi": [ - "function storeFile(string fileName, bytes32 fileHash)", - "function getFile(bytes32 fileHash) view returns (tuple(address owner, string fileName, bytes32 fileHash))", - "event FileStored(address indexed owner, string fileName, bytes32 fileHash)" - ], - "to": "0xaDf4a1165737b406aD510045d4562BE30C14C276", - "method": "storeFile", - "id": 1, - "arguments": [ - "example.txt", - "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" - ], -}' -``` - -`Windows Command Prompt` - -```bash -curl -X POST https://rpc.testnet.stabilityprotocol.com/zkt/try-it-out -H "Content-Type: application/json" -d "{ \"abi\": [ \"function storeFile(string fileName, bytes32 fileHash)\", \"function getFile(bytes32 fileHash) view returns (tuple(address owner, string fileName, bytes32 fileHash))\", \"event FileStored(address indexed owner, string fileName, bytes32 fileHash)\" ], \"to\": \"0xaDf4a1165737b406aD510045d4562BE30C14C276\", \"method\": \"storeFile\", \"id\": 1, \"arguments\": [ \"example.txt\", \"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef\" ] }" -``` - -Response: - -```json -{ - "success": true, - "hash": "0xeebda882d3e48d1f28819b7439d109c2aeb398f657a8f99f55e9ad83233aa4b8", - "id": 1 -} -``` - -**_Smart Contract Deploy Request_**: - -This is a sample request that deploys a new smart contract to Stability Testnet. Change the code parameter to your actual Solidity smart contract, and optionally supply constructor arguments via the arguments array if your contract requires them. - -`Linux/macOS Shell` - -```bash -curl -X POST 'https://rpc.testnet.stabilityprotocol.com/zkt/try-it-out' \ - -H "Content-Type: application/json" \ - --data '{ -"code": "// SPDX-License-Identifier: MIT\npragma solidity ^0.8.0;\n\ncontract GreetingContract {\n string private greeting;\n uint256 private value;\n\n constructor(string memory _greeting, uint256 _initialValue) {\n greeting = _greeting;\n value = _initialValue;\n }\n\n function getGreeting() external view returns (string memory) {\n return greeting;\n }\n\n function getValue() external view returns (uint256) {\n return value;\n }\n\n function setValue(uint256 _newValue) external {\n value = _newValue;\n }\n}", -"arguments": ["Hello, world!", "123"] -}' -``` - -`Windows Command Prompt` - -```bash -curl -X POST https://rpc.testnet.stabilityprotocol.com/zkt/try-it-out -H "Content-Type: application/json" -d "{ \"code\": \"// SPDX-License-Identifier: MIT\\npragma solidity ^0.8.0;\\n\\ncontract GreetingContract {\\n string private greeting;\\n uint256 private value;\\n\\n constructor(string memory _greeting, uint256 _initialValue) {\\n greeting = _greeting;\\n value = _initialValue;\\n }\\n\\n function getGreeting() external view returns (string memory) {\\n return greeting;\\n }\\n\\n function getValue() external view returns (uint256) {\\n return value;\\n }\\n\\n function setValue(uint256 _newValue) external {\\n value = _newValue;\\n }\\n}\", \"arguments\": [ \"Hello, world!\", \"123\" ] }" -``` - -Response: - -```json -{ - "success": true, - "contractAddress": "0x983b2221EE0f21E076CD0A12DE484D974bBa2b4E", - "abi": [ - { - "inputs": [ - { "internalType": "string", "name": "_greeting", "type": "string" }, - { - "internalType": "uint256", - "name": "_initialValue", - "type": "uint256" - } - ], - "stateMutability": "nonpayable", - "type": "constructor" - }, - { - "inputs": [], - "name": "getGreeting", - "outputs": [{ "internalType": "string", "name": "", "type": "string" }], - "stateMutability": "view", - "type": "function" - }, - { - "inputs": [], - "name": "getValue", - "outputs": [{ "internalType": "uint256", "name": "", "type": "uint256" }], - "stateMutability": "view", - "type": "function" - }, - { - "inputs": [ - { "internalType": "uint256", "name": "_newValue", "type": "uint256" } - ], - "name": "setValue", - "outputs": [], - "stateMutability": "nonpayable", - "type": "function" - } - ], - "hash": "0x7435da85e2af649fbaf6b4e06cb963f502992931217f0b31f91cd1c547619918", - "id": 1 -} -``` diff --git a/docs/developers/_category_.json b/docs/developing_on_stability/_category_.json similarity index 73% rename from docs/developers/_category_.json rename to docs/developing_on_stability/_category_.json index 6040543..d994a07 100644 --- a/docs/developers/_category_.json +++ b/docs/developing_on_stability/_category_.json @@ -1,8 +1,8 @@ { - "label": "Developers", - "position": 5, + "label": "Developing on Stability", + "position": 3, "link": { "type": "generated-index", "description": "Documentation for anybody looking to interact directly and build on Stability Blockchain." } -} \ No newline at end of file +} diff --git a/docs/developing_on_stability/web2_developers/_category_.json b/docs/developing_on_stability/web2_developers/_category_.json new file mode 100644 index 0000000..db41302 --- /dev/null +++ b/docs/developing_on_stability/web2_developers/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Web 2 Developers", + "position": 1, + "link": { + "type": "generated-index", + "description": "Guides for Web 2 developers getting started with blockchain." + } +} diff --git a/docs/developing_on_stability/web2_developers/intro.md b/docs/developing_on_stability/web2_developers/intro.md new file mode 100644 index 0000000..cd46f70 --- /dev/null +++ b/docs/developing_on_stability/web2_developers/intro.md @@ -0,0 +1,26 @@ +--- +sidebar_position: 1 +--- + +# Introduction + +Welcome, Web 2 developers! If you're new to blockchain development, Stability provides unique features that simplify blockchain interactions without requiring deep Web 3 knowledge. + +## What Makes Stability Different? + +Stability offers innovative solutions that lower the barrier to entry for traditional developers: + +- **Zero-Knowledge Transactions (ZKT)**: Interact with the blockchain using simple `HTTP POST` requests +- **No wallet required**: Build applications without requiring users to manage crypto wallets +- **Free transactions**: No gas fees to worry about +- **Familiar tools**: Use standard REST APIs instead of specialized blockchain libraries + +## Zero-Knowledge Transactions (ZKT) + +The easiest way to get started with Stability is through our **Zero-Knowledge Transactions (ZKT)** feature. This allows you to: + +- Submit messages to the blockchain via HTTP requests +- Deploy and interact with smart contracts using simple JSON +- Build decentralized applications with familiar web development tools + +Learn more about [Zero-Knowledge Transactions](./zkt/overview) to start building. diff --git a/docs/developing_on_stability/web2_developers/zkt/_category_.json b/docs/developing_on_stability/web2_developers/zkt/_category_.json new file mode 100644 index 0000000..19dfa33 --- /dev/null +++ b/docs/developing_on_stability/web2_developers/zkt/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Zero-Knowledge Transactions", + "position": 2, + "link": { + "type": "generated-index", + "description": "Learn how to use Zero-Knowledge Transactions (ZKT) to interact with the Stability blockchain using simple HTTP requests." + } +} diff --git a/docs/developing_on_stability/web2_developers/zkt/api_reference.md b/docs/developing_on_stability/web2_developers/zkt/api_reference.md new file mode 100644 index 0000000..8f4bb7c --- /dev/null +++ b/docs/developing_on_stability/web2_developers/zkt/api_reference.md @@ -0,0 +1,389 @@ +--- +sidebar_position: 2 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# API Reference + +## ZKT OpenAPI Specification + +Click [here](https://stabilityprotocol.github.io/stability-api-docs/) to go to our OpenAPI documentation site for the Zero-Knowledge Transactions (ZKT) API. This includes the request schemas (V1 and V2), response objects (success or error), error fields and an OpenAPI YAML download link. + +### How to Use the Specification + +- You can copy the **OpenAPI YAML** above into a file named `openapi.yaml` (or similar). +- This specification is compatible with tools like Swagger UI, Redoc, or any OpenAPI v3.0.3-compatible library. +- It documents how to submit V1 and V2 style transactions, along with the standardized success and error response formats. + +--- + +## Request Types + +:::tip Select a Tab Below +ZKT supports three different request types. **Use the tabs below** to toggle between them: + +::: + + + + +## ZktV1: Write Message to Blockchain + +Use ZktV1 to post simple messages to the blockchain without interacting with smart contracts. + +--- +## Parameters + + + +
+ +| Field | Type | Description | Required | +|-------------|--------|-----------------------------------------|----------| +| `arguments` | string | The message you want to post to the blockchain | Yes | + +
+ + + + + +
+ +| Field | Type | Description | +|-------------|---------|------------------------------------------------------------------| +| `success` | boolean | A boolean indicating whether the request was successful. | +| `hash` | string | The transaction hash of the submitted message on the blockchain. | + +
+ + + + +--- + +## Request Example + + + + +```bash +curl -X POST "https://rpc.stabilityprotocol.com/zkt/try-it-out" \ +-H "Content-Type: application/json" \ +--data '{ "arguments": "Your message here" }' +``` + + + + +```bash +curl -X POST "https://rpc.stabilityprotocol.com/zkt/try-it-out" -H "Content-Type: application/json" --data "{ \"arguments\": \"Your message here\" }" +``` + + + + +Response: + +```json +{ + "success": true, + "hash": "0x48b3861c7e04e82fd7bfcec4a1e370950abb65851b6a676515bbc8bee01b470d" +} +``` + + + + + +## ZktV2Simple: Smart Contract Interaction + +Use ZktV2Simple to interact with existing smart contracts on the Stability blockchain. This enables you to: + +- **Execute Smart Contract Functions**: Invoke any function defined in a smart contract, whether it's to read current data or write a new state on the blockchain. +- **Custom Transactions**: Craft and send transactions that interact with decentralized applications (dApps) without the need for specialized blockchain development tools. +- **Simplified Interaction Model**: Use standard `HTTP POST` requests to perform actions that would typically require a blockchain client or wallet software. + +:::info Need Help with ABIs? +If you're unfamiliar with smart contract ABIs (Application Binary Interfaces), check out the [Solidity documentation](https://docs.soliditylang.org/en/) for guidance on contract interfaces and function signatures. +::: +--- +## Parameters + + + +
+ +| Field | Type | Description | Required | +|-------------|---------|--------------------------------------------------------------------------------------------------------|----------| +| `abi` | array | Array of ABI entries (functions/events) the service needs to encode / decode your call. | Yes | +| `to` | string | Address of the target smart contract. | Yes | +| `method` | string | Name of the contract function to invoke. | Yes | +| `arguments` | array | Array of arguments for `method` (empty array `[]` if none). | Yes | +| `id` | string | Optional request identifier for matching responses. | No | +| `wait` | boolean | Optional; if `true`, the call blocks until the transaction is mined and a receipt is returned. | No | + +
+ + + + + +
+ +| Field | Type | Description | Appears In | +|--------------------|------------------|--------------------------------------------------------------------------------|-----------------| +| `success` | boolean | Indicates whether the request was successful. | Read, Write | +| `output` | string \| array | Contract read result. Only for read operations. | Read | +| `queueId` | string | UUID for polling transaction status. Only for write operations. | Write | +| `transactionHash` | string \| null | Transaction hash. May be null initially. | Write | +| `hash` | string \| null | Alternative field name for transaction hash. May be null initially. | Write | +| `id` | string | Request ID (echoed from request). | Read, Write | + +
+ +**Note:** Read operations return `output`, while write operations return `queueId` and either `transactionHash` or `hash` (both may be null initially). + + + + +--- + +## Request Examples + + + + +This sample request reads the `getFile` function of an example smart contract deployed on Stability Testnet. The smart contract is a simple storage contract that stores a file hash as well as a file name. The following request uses the file hash to retrieve the owner of the file, the file name, and confirmation of the file hash. + + + + +```bash +curl -X POST https://rpc.testnet.stabilityprotocol.com/zkt/try-it-out \ +-H "Content-Type: application/json" \ +-d '{ + "abi": [ + "function storeFile(string fileName, bytes32 fileHash)", + "function getFile(bytes32 fileHash) view returns (tuple(address owner, string fileName, bytes32 fileHash))", + "event FileStored(address indexed owner, string fileName, bytes32 fileHash)" + ], + "to": "0xaDf4a1165737b406aD510045d4562BE30C14C276", + "method": "getFile", + "id": 2, + "arguments": [ + "0x8e21513d95607300128ceb8bd985f87ea157a5e4cb416b070ca02e9689f9c26c" + ] +}' +``` + + + + +```bash +curl -X POST https://rpc.testnet.stabilityprotocol.com/zkt/try-it-out -H "Content-Type: application/json" -d "{ \"abi\": [ \"function storeFile(string fileName, bytes32 fileHash)\", \"function getFile(bytes32 fileHash) view returns (tuple(address owner, string fileName, bytes32 fileHash))\", \"event FileStored(address indexed owner, string fileName, bytes32 fileHash)\" ], \"to\": \"0xaDf4a1165737b406aD510045d4562BE30C14C276\", \"method\": \"getFile\", \"id\": 2, \"arguments\": [ \"0x8e21513d95607300128ceb8bd985f87ea157a5e4cb416b070ca02e9689f9c26c\" ] }" +``` + + + + +**Response:** + +```json +{ + "success": true, + "output": [ + "0xFac55168086cfE3284b5874Ae2738a68eE6710D2", + "example.txt", + "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" + ], + "id": 2 +} +``` + + + + +This sample request uses the `storeFile` function of an example smart contract deployed on Stability Testnet. Change the `arguments` parameter to store your own file. + + + + +```bash +curl -X POST https://rpc.testnet.stabilityprotocol.com/zkt/try-it-out \ +-H "Content-Type: application/json" \ +-d '{ + "abi": [ + "function storeFile(string fileName, bytes32 fileHash)", + "function getFile(bytes32 fileHash) view returns (tuple(address owner, string fileName, bytes32 fileHash))", + "event FileStored(address indexed owner, string fileName, bytes32 fileHash)" + ], + "to": "0xaDf4a1165737b406aD510045d4562BE30C14C276", + "method": "storeFile", + "id": 1, + "arguments": [ + "example.txt", + "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" + ] +}' +``` + + + + +```bash +curl -X POST https://rpc.testnet.stabilityprotocol.com/zkt/try-it-out -H "Content-Type: application/json" -d "{ \"abi\": [ \"function storeFile(string fileName, bytes32 fileHash)\", \"function getFile(bytes32 fileHash) view returns (tuple(address owner, string fileName, bytes32 fileHash))\", \"event FileStored(address indexed owner, string fileName, bytes32 fileHash)\" ], \"to\": \"0xaDf4a1165737b406aD510045d4562BE30C14C276\", \"method\": \"storeFile\", \"id\": 1, \"arguments\": [ \"example.txt\", \"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef\" ] }" +``` + + + + +**Response:** + +```json +{ + "success": true, + "queueId": "4aafa29b-763b-41c3-8d5b-8a1ed8d20260", + "id": 1 +} +``` + + + + + + + + +## ZktV2Contract: Deploy Smart Contract + +Use ZktV2Contract to deploy new smart contracts to the Stability blockchain. This allows you to: + +- Deploy Solidity smart contracts without specialized blockchain tools +- Provide constructor arguments for contract initialization +- Receive the deployed contract address and ABI in the response + +:::info New to Smart Contracts? +Learn how to write smart contracts in the [Solidity documentation](https://docs.soliditylang.org/en/), or follow our [Deploy Contract Using Remix](../../../tutorials/contract_deploy/deploy_contract_with_remix.md) tutorial to get started with a visual IDE. + +_Note: Ensure Your smart contracts meet our [EVM Compatability Requirements](docs/developing_on_stability/web3_developers/evm_compatibility.md)_ +::: + +--- +## Parameters + + + +
+ +| Field | Type | Description | Required | +|-------------|--------|-----------------------------------------------------------------|----------| +| `code` | string | The Solidity source code of the contract you want to deploy. | Yes | +| `arguments` | array | Optional constructor arguments for contract initialization. | No | +| `id` | string | Optional request identifier for matching responses. | No | + +
+ + + + + +
+ +| Field | Type | Description | +|--------------------|------------------|--------------------------------------------------------------------| +| `success` | boolean | A boolean indicating whether the deployment was successful. Always `true` for successful responses. | +| `contractAddress` | string | The blockchain address where the contract was deployed. | +| `abi` | array | Full ABI JSON array of the deployed contract. | +| `hash` | string | The transaction hash of the deployment. | +| `id` | string | Request ID (echoed from request). | + +
+ + + + +--- + +## Request Example + +This sample request deploys a new smart contract to Stability Testnet. Change the code parameter to your actual Solidity smart contract, and optionally supply constructor arguments via the arguments array if your contract requires them. + + + + +```bash +curl -X POST 'https://rpc.testnet.stabilityprotocol.com/zkt/try-it-out' \ + -H "Content-Type: application/json" \ + --data '{ +"code": "// SPDX-License-Identifier: MIT\npragma solidity ^0.8.0;\n\ncontract GreetingContract {\n string private greeting;\n uint256 private value;\n\n constructor(string memory _greeting, uint256 _initialValue) {\n greeting = _greeting;\n value = _initialValue;\n }\n\n function getGreeting() external view returns (string memory) {\n return greeting;\n }\n\n function getValue() external view returns (uint256) {\n return value;\n }\n\n function setValue(uint256 _newValue) external {\n value = _newValue;\n }\n}", +"arguments": ["Hello, world!", "123"] +}' +``` + + + + +```bash +curl -X POST https://rpc.testnet.stabilityprotocol.com/zkt/try-it-out -H "Content-Type: application/json" -d "{ \"code\": \"// SPDX-License-Identifier: MIT\\npragma solidity ^0.8.0;\\n\\ncontract GreetingContract {\\n string private greeting;\\n uint256 private value;\\n\\n constructor(string memory _greeting, uint256 _initialValue) {\\n greeting = _greeting;\\n value = _initialValue;\\n }\\n\\n function getGreeting() external view returns (string memory) {\\n return greeting;\\n }\\n\\n function getValue() external view returns (uint256) {\\n return value;\\n }\\n\\n function setValue(uint256 _newValue) external {\\n value = _newValue;\\n }\\n}\", \"arguments\": [ \"Hello, world!\", \"123\" ] }" +``` + + + + +**Response:** + +```json +{ + "success": true, + "contractAddress": "0x983b2221EE0f21E076CD0A12DE484D974bBa2b4E", + "abi": [ + { + "inputs": [ + { "internalType": "string", "name": "_greeting", "type": "string" }, + { + "internalType": "uint256", + "name": "_initialValue", + "type": "uint256" + } + ], + "stateMutability": "nonpayable", + "type": "constructor" + }, + { + "inputs": [], + "name": "getGreeting", + "outputs": [{ "internalType": "string", "name": "", "type": "string" }], + "stateMutability": "view", + "type": "function" + }, + { + "inputs": [], + "name": "getValue", + "outputs": [{ "internalType": "uint256", "name": "", "type": "uint256" }], + "stateMutability": "view", + "type": "function" + }, + { + "inputs": [ + { "internalType": "uint256", "name": "_newValue", "type": "uint256" } + ], + "name": "setValue", + "outputs": [], + "stateMutability": "nonpayable", + "type": "function" + } + ], + "hash": "0x7435da85e2af649fbaf6b4e06cb963f502992931217f0b31f91cd1c547619918", + "id": 1 +} +``` + + + + +--- + +After submitting a transaction, you may want to check its status. The next section covers how to [monitor your transactions](./transaction_status). diff --git a/docs/developing_on_stability/web2_developers/zkt/overview.md b/docs/developing_on_stability/web2_developers/zkt/overview.md new file mode 100644 index 0000000..c53b828 --- /dev/null +++ b/docs/developing_on_stability/web2_developers/zkt/overview.md @@ -0,0 +1,67 @@ +--- +sidebar_position: 1 +--- + +# Overview + +**Zero-Knowledge Transactions (ZKT)** is an experimental feature of the Stability Blockchain that simplifies blockchain interactions by allowing users to submit data directly via standard `HTTP POST` requests. This removes the need for complex Web3 libraries, enabling any application capable of making a web request to interact with the blockchain. + +- Explore the [Stability Publisher](https://github.com/stabilityprotocol/stability-publisher-dapp) Github repository +- View the Live [Demo](https://stabilityprotocol.github.io/stability-publisher-dapp/) to see ZKT in action. + + +## Architecture + +The **ZKT** solution is architected as a **RESTful service** that acts as a bridge between standard web clients and the Stability Blockchain. This simplifies on-chain interactions for Web2 developers. + +Below is a high-level diagram of the ZKT architecture: + +![ZKT Architecture Overview](../../../../static/img/zktoverview.png) + +**Components:** + +- **API Gateway:** Serves as the secure entry point for all ZKT requests, handling: + - **Authentication:** Verifies requests using your Stability API Key. + - **Data Validation:** Ensures incoming `JSON` structure is correct and contains required arguments. + - **Network Routing:** Directs traffic to either the `Testnet` or `GTN (Mainnet)` based on the endpoint used. +- **ZKT Service:** Handles transaction construction, signing, and communication with the blockchain sequencer. +- **Sequencer** Orders and finalizes transactions on the Stability blockchain. + +## Getting Started + +To start experimenting, we recommend signing up for a free API Key on the [Stability Portal](https://account.stabilityprotocol.com/keys). While a public RPC is available for testing, the private endpoints offer dedicated resources for your application. + +**Public RPC Endpoints (limited):** +- **Mainnet**: `https://rpc.stabilityprotocol.com/zkt/try-it-out` +- **Testnet**: `https://rpc.testnet.stabilityprotocol.com/zkt/try-it-out` + +### Available Endpoints + +- **`POST /zkt/try-it-out`** + + Public endpoint for submitting messages to the blockchain. Note this endpoint may be limited. Transactions submitted here are signed by a single account: `0x7f521250d3aacba194dbb33427ffea2c546b433d`. + _You can view this account on our [Testnet Explorer](https://explorer.stble.io/testnet/address/0x7f521250d3aacba194dbb33427ffea2c546b433d/) and [Mainnet Explorer](https://stability.blockscout.com/address/0x7F521250d3AAcba194dBB33427fFEa2C546B433d)._ + +- **`POST /zkt/{your-api-key}`** + + An authenticated endpoint. Transactions submitted here are signed by a unique wallet exclusive to your API Key. + +- **`GET /gtn/v1/transaction/{queueId}`** + + Endpoint for checking the status of a submitted transaction. This will be discussed in further detail in [Checking Transaction Status](./transaction_status). + +## Security Considerations + +- **API Rate Limiting:** Enforced at the API Gateway to prevent spam or denial-of-service attacks. +- **Data Privacy:** Although messages are public, the initiator of the transaction is unknown when using the public key. +- **Max Payload:** The maximum size of a ZKT transaction payload is 1 MB. + +## Error Handling + +- **Validation Errors:** Returned if the request body is missing required fields or contains incorrect formats. +- **Network Errors:** Handled gracefully with retry logic if the transaction fails to broadcast due to network issues. + +--- + +Now that you understand how ZKT works, let's explore the API and start making requests in the [API Reference](./api_reference) section. +Now that you understand how ZKT works, let's explore the API and start making requests in the [API Reference](./api_reference) section. diff --git a/docs/developing_on_stability/web2_developers/zkt/transaction_status.md b/docs/developing_on_stability/web2_developers/zkt/transaction_status.md new file mode 100644 index 0000000..1ad06b9 --- /dev/null +++ b/docs/developing_on_stability/web2_developers/zkt/transaction_status.md @@ -0,0 +1,152 @@ +--- +sidebar_position: 3 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Checking Transaction Status + +After submitting a ZKT transaction, you may want to verify its status and retrieve transaction details. This is especially useful for monitoring **asynchronous transactions** and ensuring they have been successfully processed on the blockchain. + +- Verify that your transaction has been successfully processed +- Retrieve the on-chain transaction hash for blockchain explorers +- Debug any errors that may have occurred during processing +- Track the timestamp of when your transaction was created and processed + +## Endpoint + +To check the status of a ZKT transaction, send a `HTTP GET` request to: + +``` +GET https://api.stabilityprotocol.com/gtn/v1/zkt/transaction/{queueId} +``` + +When you submit a ZKT transaction, the API returns a `queueId` in the response. This identifier is used to track your transaction through the processing queue. + +For example, when you submit a transaction, you might receive: +```json +{ + "queueId": "98a793a2-f8df-454f-90f5-681f3e9fc7c9" +} +``` + +Replace `{queueId}` with the queue ID you received from your initial ZKT transaction to check the transaction status + +## Request Example + + + + +```bash +curl -X GET "https://api.stabilityprotocol.com/gtn/v1/zkt/transaction/98a793a2-f8df-454f-90f5-681f3e9fc7c9" \ +-H "Content-Type: application/json" +``` + + + + +```bash +curl -X GET "https://api.stabilityprotocol.com/gtn/v1/zkt/transaction/98a793a2-f8df-454f-90f5-681f3e9fc7c9" -H "Content-Type: application/json" +``` + + + + +## Response Fields + +The response format varies depending on the transaction status: + +| Field | Type | Description | Appears When | +|--------------------|--------|-----------------------------------------------------------------------------|------------------------| +| `status` | string | Current status: `pending`, `processing`, `completed`, or `error`. | All statuses | +| `queueId` | string | Unique identifier for the transaction in the processing queue. | All statuses | +| `transactionHash` | string | The on-chain transaction hash. | `completed` only | +| `errorMessage` | string | Error details describing what went wrong. | `error` only | +| `createdAt` | string | ISO 8601 timestamp of when the transaction was submitted. | `completed`, `error` | +| `processedAt` | string | ISO 8601 timestamp of when the transaction was processed. | `completed` only | + +## Response Examples + + + + +When the transaction has been successfully processed: + +```json +{ + "queueId": "98a793a2-f8df-454f-90f5-681f3e9fc7c9", + "status": "completed", + "transactionHash": "0x6caac320855880061c105c83b51b09a1e30331efebcae9d2a2b2b5f80f8a1bbe", + "errorMessage": null, + "createdAt": "2026-01-20T07:57:35.220Z", + "processedAt": "2026-01-20T07:57:38.295Z" +} +``` + + + + + +When the transaction encounters an error you can expect these fields in the response: + +```json +{ + "status": "error", + "queueId": "3c9d2ec0-e24c-41be-9f37-d348f6027c1b", + "errorMessage": "reason why the transaction failed", + "createdAt": "2026-01-27T03:27:44.329Z" +} +``` + +If the requested transaction cannot be found, the API will respond with: + +```json +{ + "error": "Transaction not found" +} +``` + + + + + +When the transaction is still being processed: + +```json +{ + "status": "pending", + "queueId": "98a793a2-f8df-454f-90f5-681f3e9fc7c9" +} +``` + +or + +```json +{ + "status": "processing", + "queueId": "98a793a2-f8df-454f-90f5-681f3e9fc7c9" +} +``` + + + + +## Understanding Status Values + +| Status | Description | +|--------------|----------------------------------------------------------------------------------| +| `pending` | The transaction is queued and waiting to be processed. | +| `processing` | The transaction is currently being processed. | +| `completed` | The transaction has been successfully processed and confirmed on the blockchain. | +| `error` | The transaction encountered an error during processing. | + +## Next Steps + +Now that you understand how to submit transactions and monitor their status, you can: + +- Explore the [Stability Portal](https://account.stabilityprotocol.com/keys) to manage your API keys +- Check out the [Stability Publisher](https://github.com/stabilityprotocol/stability-publisher-dapp) repository for more examples +- View your transactions on the blockchain explorers: + - [GTN Explorer](https://stability.blockscout.com/) + - [Testnet Explorer](https://explorer.stble.io/testnet/) diff --git a/docs/developing_on_stability/web3_developers/_category_.json b/docs/developing_on_stability/web3_developers/_category_.json new file mode 100644 index 0000000..c93af2a --- /dev/null +++ b/docs/developing_on_stability/web3_developers/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Web 3 Developers", + "position": 2, + "link": { + "type": "generated-index", + "description": "Comprehensive guides for Web 3 developers building on Stability." + } +} diff --git a/docs/developers/ATM/_category_.json b/docs/developing_on_stability/web3_developers/atm/_category_.json similarity index 100% rename from docs/developers/ATM/_category_.json rename to docs/developing_on_stability/web3_developers/atm/_category_.json diff --git a/docs/developers/ATM/bsr.md b/docs/developing_on_stability/web3_developers/atm/bsr.md similarity index 68% rename from docs/developers/ATM/bsr.md rename to docs/developing_on_stability/web3_developers/atm/bsr.md index 011d7f0..68d8aeb 100644 --- a/docs/developers/ATM/bsr.md +++ b/docs/developing_on_stability/web3_developers/atm/bsr.md @@ -2,6 +2,9 @@ sidebar_position: 1 --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # Business Share Revenue (Beta) ## Overview @@ -12,7 +15,7 @@ In traditional blockchains, validators (or miners) keep all transaction fees; BS Validators may choose which tokens would be used for the fee payment. This opens up numerous possibilities and incentives for projects to utilize STABILITY. -Note: BSR is currently in Beta. Implementation and parameters may evolve based on governance and ecosystem feedback. +_Note: BSR is currently in **Beta**. Implementation and parameters may evolve based on governance and ecosystem feedback._ ## How It Works @@ -22,46 +25,63 @@ For instance, if the split is 50/50 by default, half the fee goes to the `valida ## BSR and the Ethereum Virtual Machine -STABILITY is an EVM-compatible blockchain (built on Substrate), which means developers interact with BSR through familiar Ethereum-like interfaces. +STABILITY is an EVM-compatible blockchain (built on Substrate), which means developers interact with BSR through familiar Ethereum tools (Ethers.js, Web3.js, or Solidity). The logic is exposed via a precompiled System Contract. + +- Precompile Name: `FeeRewardsVaultController` +- Precompile Address: `0x0000000000000000000000000000000000000807` +- Source Code: Available [on Github](https://github.com/stabilityprotocol/stability/blob/master/precompiles/fee-rewards-vault-controller/FeeRewardsVaultController.sol) + +For example, calling `FeeRewardsVaultController.getValidatorPercentage()` will return the current fee split percentage allocated to validators​. More importantly, the precompile allows claiming and querying accumulated fee shares through standard function calls, making BSR easy to use. -The fee-sharing logic runs in the chain’s runtime, but it’s exposed to smart contracts and external applications via a precompiled system contract called the `FeeRewardsVaultController`. This precompile lives at[`0x0000000000000000000000000000000000000807`](https://explorer.stabilityprotocol.com/address/0x0000000000000000000000000000000000000807). The smart contract code is available [on Github](https://github.com/stabilityprotocol/stability/blob/master/precompiles/fee-rewards-vault-controller/FeeRewardsVaultController.sol). -All BSR functions are accessible via the precompiled contract interface. Developers can use web3.js, ethers.js, or Solidity to call these functions exactly like a normal contract. For example, calling `FeeRewardsVaultController.getValidatorPercentage()` will return the current fee split percentage allocated to validators​. More importantly, the precompile allows claiming and querying accumulated fee shares through standard function calls, making BSR easy to use. +## Earning & Claiming Fees -## Earning and Claiming Fees as a Developer + + When a transaction involving a smart contract executes, the BSR mechanism will automatically allocate the validator's and the smart contract's share of the fee into the `FeeRewardsVaultController`. -To claim your funds, your smart contract and dApp must be whitelisted. What this means for a developer is that after deploying a contract, you should apply for or await whitelisting by the protocol’s governance or admin. All contracts accrue their fee share regardless of whitelist status. Your dapp’s share is still recorded. However, only whitelisted contracts are permitted to actually withdraw the funds​. +To claim your funds, your smart contract and dApp must be whitelisted. What this means for a developer is that after deploying a contract, you should apply for or await whitelisting by the protocol's governance or admin. All contracts accrue their fee share regardless of whitelist status. Your dapp's share is still recorded. However, only whitelisted contracts are permitted to actually withdraw the funds​. -If your dapp gets whitelisted later, you won’t lose past fees – the accumulated rewards that were held will become claimable once whitelisting is in place​. +If your dapp gets whitelisted later, you won't lose past fees – the accumulated rewards that were held will become claimable once whitelisting is in place​. -From a developer perspective, whitelisting is essentially an approval step ensuring your contract is recognized as a legitimate participant in BSR. The act of whitelisting is done via an admin function (`setWhitelisted(address dapp, bool`) on the same `FeeRewardsVaultController` precompile, and it emits an event `WhitelistStatusUpdated` for transparency. This function is restricted to the contract’s owner – typically a governance or core team address – so developers themselves cannot arbitrarily whitelist. +From a developer perspective, whitelisting is essentially an approval step ensuring your contract is recognized as a legitimate participant in BSR. The act of whitelisting is done via an admin function (`setWhitelisted(address dapp, bool`) on the same `FeeRewardsVaultController` precompile, and it emits an event `WhitelistStatusUpdated` for transparency. This function is restricted to the contract's owner – typically a governance or core team address – so developers themselves cannot arbitrarily whitelist. Claimable rewards can be checked by calling the `FeeRewardsVaultController` using the `getClaimableReward(address dapp, address token)` function. There are two methods for a contract to claim fees that developers should be mindful of when deploying. -### The Contract Itself Claims + + -Your smart contract can call the precompile’s `claimReward(address dapp, address token)` function, passing its own address as the dapp parameter and the fee token address. This will transfer any accumulated fee revenue (for that contract and token) from the protocol’s vault to the contract’s account. This approach requires the contract to invoke the claim (which could be done in a function or via a privileged call in your contract logic). +Your smart contract can call the precompile's `claimReward(address dapp, address token)` function, passing its own address as the dapp parameter and the fee token address. This will transfer any accumulated fee revenue (for that contract and token) from the protocol's vault to the contract's account. This approach requires the contract to invoke the claim (which could be done in a function or via a privileged call in your contract logic). -### The Contract Owner Claims + + + -If your smart contract implements a standard `owner()` function (e.g., as in OpenZeppelin Ownable), the precompile can use it to determine the contract’s owner. The owner (EOA or multisig) can then call `claimReward(contractAddress, token)` from their external account. The precompile will recognize that the caller is the owner of the given contract (by internally calling `owner()` on the contract to verify)​. +If your smart contract implements a standard `owner()` function (e.g., as in OpenZeppelin Ownable), the precompile can use it to determine the contract's owner. The owner (EOA or multisig) can then call `claimReward(contractAddress, token)` from their external account. The precompile will recognize that the caller is the owner of the given contract (by internally calling `owner()` on the contract to verify)​. -This allows the owner to withdraw the accumulated fees on the contract’s behalf. +This allows the owner to withdraw the accumulated fees on the contract's behalf. + + + ### Important Note -If a contract doesn’t implement `owner()`, the protocol considers it to have no owner, meaning only the contract itself could claim its rewards (if it has some internal mechanism). If the project does not have an owner or a method for the contract itself to claim, then the funds are not retrievable. +If a contract doesn't implement `owner()`, the protocol considers it to have no owner, meaning only the contract itself could claim its rewards (if it has some internal mechanism). If the project does not have an owner or a method for the contract itself to claim, then the funds are not retrievable. -## Earning and Claiming Fees as a Validator + + + Validators also claim their portion through the same vault system. Unlike developers, validators do not need to be whitelisted or approved; any active validator can claim its earned fees freely​. A validator simply calls `claimReward(validatorAddress, token)` using its own address to withdraw the fees it has accumulated for that token. The protocol checks that the caller is indeed entitled (in other words, the address is currently an active validator in the consensus) and then pays out the amount. If a validator leaves the validator set, it can no longer claim new rewards. Any unclaimed rewards at that point remain in the vault inaccessible. Validators are expected to claim periodically while they are active. + + + ## Example Suppose a user calls a function on a DeFi contract on STABILITY and pays 10 XYZ token for the transaction fee. The network’s validator percentage is 50%. The runtime deducts 10 XYZ from the user and holds it in the vault. diff --git a/docs/developers/ATM/token_gating.md b/docs/developing_on_stability/web3_developers/atm/token_gating.md similarity index 83% rename from docs/developers/ATM/token_gating.md rename to docs/developing_on_stability/web3_developers/atm/token_gating.md index b0fdfef..3516881 100644 --- a/docs/developers/ATM/token_gating.md +++ b/docs/developing_on_stability/web3_developers/atm/token_gating.md @@ -2,6 +2,9 @@ sidebar_position: 2 --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # Token Gating (Beta) ## Overview @@ -18,35 +21,44 @@ Notably, users leveraging the Zero Gas Transaction or ZKT framework can bypass t ## How It Works -### Whitelisted Fee Tokens + + The set of tokens that can be used to pay fees is controlled by a whitelist called the **Supported Tokens List**. Only tokens on this approved list will be recognized for gas payment. If a token is not whitelisted, users cannot select it for fees. Any transaction attempting to use an unapproved token will be rejected or never included in a block. This ensures all fee tokens have been vetted by the STABILITY team. The list is updated by admins via the `SupportedTokensManager` precompile [(Code)](https://github.com/stabilityprotocol/stability/blob/master/precompiles/token-fee-controller/supported-tokens-manager/SupportedTokensManager.sol) to add or remove allowed tokens​. A default token is designated on this list – if a user does not explicitly choose a fee token, the network will use the default​ for ATM transactions. -### User Fee Token Selection + + + Each user can select which whitelisted token they wish to use to pay transaction fees. The user signals their choice by calling a precompiled contract function. STABILITY provides the `Fee Token Selector` precompile [(Code)](https://github.com/stabilityprotocol/stability/blob/master/precompiles/token-fee-controller/fee-token-selector/FeeTokenSelector.sol) for this purpose​. -By calling `FeeTokenSelector.setFeeToken(address tokenAddress)`, a user sets their preferred fee token. The chosen token must be one of the whitelisted tokens, otherwise the call will fail. If successful, the user’s preference is recorded on-chain and mapped to the user’s address. From that point on, any transaction sent via ATM by the user will be charged in the selected token. Users can query their current setting via `FeeTokenSelector.getFeeToken(address user)`, which returns the token address they have selected​. If a user never calls `setFeeToken`, the system assumes the default token for their ATM transactions​. Users may update their fee token selection at any time by calling `setFeeToken` again with a different allowed token. +By calling `FeeTokenSelector.setFeeToken(address tokenAddress)`, a user sets their preferred fee token. The chosen token must be one of the whitelisted tokens, otherwise the call will fail. If successful, the user's preference is recorded on-chain and mapped to the user's address. From that point on, any transaction sent via ATM by the user will be charged in the selected token. Users can query their current setting via `FeeTokenSelector.getFeeToken(address user)`, which returns the token address they have selected​. If a user never calls `setFeeToken`, the system assumes the default token for their ATM transactions​. Users may update their fee token selection at any time by calling `setFeeToken` again with a different allowed token. -### Validator Token Selection + + + For validators, each validator declares which of the whitelisted tokens they are willing to accept as gas payment. Validators use the `Validator Fee Token Selector` precompile [(Code)](https://github.com/stabilityprotocol/stability/blob/master/precompiles/token-fee-controller/validator-fee-selector/ValidatorFeeTokenSelector.sol) to manage their accepted tokens and fee conversion settings​. A validator calls `ValidatorFeeTokenSelector.setTokenAcceptance(address token, bool acceptance)` to indicate whether they accept a particular token as fees​. By default, a new validator is configured to accept the default token only​. They must explicitly opt in to each additional token they wish to collect fees in. If a validator has not accepted a certain token, that validator will not include transactions that pay fees in that token. -### Fee Matching and Mempool Gating + + + -When a user submits a transaction, the gas fee token address is not included in the transaction data. Instead, the network implicitly knows which token to use from the user’s stored preference. The transaction is propagated in the public mempool only if its fee token is on the global whitelist. Each validator’s mempool will filter or ignore transactions that use tokens the validator doesn’t accept. +When a user submits a transaction, the gas fee token address is not included in the transaction data. Instead, the network implicitly knows which token to use from the user's stored preference. The transaction is propagated in the public mempool only if its fee token is on the global whitelist. Each validator's mempool will filter or ignore transactions that use tokens the validator doesn't accept. In addition, to execute, the maxFeePerGas parameter set up by the user must meet the minimum the validator the validator will accept for this transaction. When a user sets their `base_Fee`. This dived into deeper in the next section. -In practice, a transaction paying with token X will only be picked up by validators who have set acceptance for X **_and_** and at the price point the validator will accept. If a validator that doesn’t support token X receives the transaction, or the transaction is underpriced, the validator will not include the transaction in a block. The transaction waits in the mempool until a compatible validator is the one to produce a block. +In practice, a transaction paying with token X will only be picked up by validators who have set acceptance for X **_and_** and at the price point the validator will accept. If a validator that doesn't support token X receives the transaction, or the transaction is underpriced, the validator will not include the transaction in a block. The transaction waits in the mempool until a compatible validator is the one to produce a block. -### Transaction Execution and Conversion + + + -Once a validator that supports the user’s fee token is producing a block, the transaction can be executed. STABILITY’s runtime still uses the EVM to execute transactions, but because there is no native currency, the gas price fields are handled differently. +Once a validator that supports the user's fee token is producing a block, the transaction can be executed. STABILITY's runtime still uses the EVM to execute transactions, but because there is no native currency, the gas price fields are handled differently. -This zero native gas price is possible because the network doesn’t charge any native coin during execution. Instead of charging native gas during execution, the protocol calculates the fee in the user’s chosen token after the transaction is run. Each validator has an associated `Conversion Rate Manager` contract which determines how to convert the abstract gas usage into an ERC-20 token amount​. +This zero native gas price is possible because the network doesn't charge any native coin during execution. Instead of charging native gas during execution, the protocol calculates the fee in the user's chosen token after the transaction is run. Each validator has an associated `Conversion Rate Manager` contract which determines how to convert the abstract gas usage into an ERC-20 token amount​. Validators set the address of its conversion contract via `ValidatorFeeTokenSelector.updateConversionRateController(address controller)​`. This is typically set to a default contract used by all validators, unless a validator chooses a custom strategy. @@ -56,13 +68,20 @@ The conversion manager implements `getConversionRate(address sender, address validator, address token) returns (uint256, uint256)​` ``` -This function called by the runtime for each transaction to fetch the conversion rate. The conversion rate is a factor that translates the network’s internal gas units into actual token amount. In simpler terms, it’s akin to a price or exchange rate for the fee token, where a each individual sets their own conversion rate, and the validator sets the conversion rate they will accept to process the transaction. +This function called by the runtime for each transaction to fetch the conversion rate. The conversion rate is a factor that translates the network's internal gas units into actual token amount. In simpler terms, it's akin to a price or exchange rate for the fee token, where a each individual sets their own conversion rate, and the validator sets the conversion rate they will accept to process the transaction. Put more simply, this function returns a conversion rate (e.g., as a numerator and denominator pair) that translates internal gas units into a fee amount in the specified token. +In STABILITY's current implementation of ATM, `baseFee + priorityFee` is effectively constant at 1 for `baseFee` and 0 for `priorityFee`, since the chain doesn't update a base fee per block as Ethereum does. This means the conversion rate directly determines the fee level. The `Conversion Rate Manager` returns a pair of values (numerator/denominator or similar) that the runtime uses to compute the multiplier for the token​. The protocol then charges the fee in the token by transferring tokens from the user to the validator upon transaction inclusion. + + + + +--- + ### Example: Token Conversion Fee -For example, suppose the network’s internal gas unit is notionally priced at 1 gwei, and the validator’s conversion rate for USDC is set to 5x. This 5x represents a price of 5 gwei. In this case, the effective gas price in USDC would be calculated as: gas_price_token = 1 \* 5 / 1e18 ≈ 5e-8 USDC per gas unit​. Let's assume USDC has 18 decimals, the transaction used 100,000 gas. The transaction contained no priority fee, as it is always ignored. +For example, suppose the network's internal gas unit is notionally priced at 1 gwei, and the validator's conversion rate for USDC is set to 5x. This 5x represents a price of 5 gwei. In this case, the effective gas price in USDC would be calculated as: gas_price_token = 1 \* 5 / 1e18 ≈ 5e-8 USDC per gas unit​. Let's assume USDC has 18 decimals, the transaction used 100,000 gas. The transaction contained no priority fee, as it is always ignored. ``` total_fee = gas_used * base_gas_price * conversion_rate @@ -79,8 +98,7 @@ total_fee = gas_used * base_gas_price * conversion_rate = 100,000 * (0.1e-9 MUFFIN) = 0.00001 MUFFIN. ``` - -In STABILITY’s current implementation of ATM, `baseFee + priorityFee` is effectively constant at 1 for `baseFee` and 0 for `priorityFee`, since the chain doesn’t update a base fee per block as Ethereum does. This means the conversion rate directly determines the fee level. The `Conversion Rate Manager` returns a pair of values (numerator/denominator or similar) that the runtime uses to compute the multiplier for the token​. The protocol then charges the fee in the token by transferring tokens from the user to the validator upon transaction inclusion. +--- ## Fee Distribution and BSR @@ -100,6 +118,8 @@ The more validators support a token, the smoother and faster the user’s transa In other words, the token gating system involves a handshake between user preferences and validator policies: users pick a token from the allowed list and validators indicate which tokens they’ll take and what rate they will accept it. The network only processes the transaction when there’s a match, then uses the validator’s conversion rate to charge the fee in that token. All of this occurs at the protocol level, allowing a user to effectively use a preferred token as the “native gas” for that transaction. +--- + ## How to Use - Developers ### Overview @@ -114,7 +134,10 @@ Developers will be primarily interacting with the following three contracts when These precompiles are built into the runtime at a fixed address. They can be called like any smart contract, using a web3 library or via Solidity interfaces. Below is a developer guide for typical use-cases. -### Example: Checking Supported Fee Tokens (Token Whitelist) +### Examples + + + Let's say you can you want to check what tokens are currently whitelisted by the ATM to be used as gas fees, if a validator accepts. @@ -148,7 +171,9 @@ async function getSupportedFeeTokens() { This would give you an array of allowed fee token addresses and the default token as a string. -### Example: Setting a User’s Fee Token + + + Let's say any end-user (EOA) or even a contract wants to pay its own fees in a specific token. Typically an EOA will call this from their account. To set the fee token, you simply call `setFeeToken` on the precompile, passing the desired token’s address. The precompile uses `msg.sender` as the user whose preference is being set, so you cannot set someone else’s preference – each user must call it for themselves. The call will revert if the token is not in the supported list. If it succeeds, the new preference takes effect immediately for subsequent transactions. @@ -192,6 +217,9 @@ After calling `setFeeToken`, the user’s future transactions will be charged in To query another address’s setting, anyone can call `getFeeToken(userAddr)`. This can be useful to know what token a particular account will use for gas. For instance, a dApp might check if a user has set a non-default token and warn if they have no balance of it. -**_Important_**: The first time a user uses STABILITY, their account will be set to the default fee token. If they want to switch to a different token, the user must use a framework such as `ZGT`, or must have a balance of the default token to pay for the `setFeeToken` transaction itself. This is because the initial call’s fee will be charged in the default token, as the preference change happens upon execution. +**_Important_**: The first time a user uses STABILITY, their account will be set to the default fee token. If they want to switch to a different token, the user must use a framework such as `ZGT`, or must have a balance of the default token to pay for the `setFeeToken` transaction itself. This is because the initial call's fee will be charged in the default token, as the preference change happens upon execution. For example, if the default token is `TOKENA` and the user wants to use `TOKENB` for future fees, the user needs to utilize STABILITY's API keys for Zero Gas Transaactions, or the user needs a small amount of `TOKENA` to call `setFeeToken(TokenBAddress)`. After that, they would pay fees in `TOKENB`. This bootstrap issue can be mitigated by funding new users with a bit of the default token or by having an onboarding process. Once set, a user can change to another token anytime by calling `setFeeToken` again. Each change will incur a fee in whatever token was currently active for that call. + + + diff --git a/docs/developing_on_stability/web3_developers/evm_compatibility.md b/docs/developing_on_stability/web3_developers/evm_compatibility.md new file mode 100644 index 0000000..62f3dd7 --- /dev/null +++ b/docs/developing_on_stability/web3_developers/evm_compatibility.md @@ -0,0 +1,130 @@ +--- +sidebar_position: 1 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# EVM Compatibility & Solidity Development + +## Introduction + +Stability provides a familiar environment for Web3 developers, supporting industry-standard tools like Ethers.js, Viem, Hardhat, and Foundry. You can deploy existing logic with minimal friction. As Stability is gasless, developers will find that some standard operations and Solidity functionalities will not work as expected on Stability. + + +:::info Important: EVM Compatibility Requirements +**Stability is EVM Compatible with Solidity up to 0.8.24** + +**Key Requirements:** +- **Solidity Version**: Must compile at version **0.8.24 or lower** +- **EVM Compiler Version**: Must be **Shanghai or lower** + +Currently, Stability has not implemented the Cancun update. Developers must ensure their contracts comply with these version requirements when developing on Stability. + +::: + +## Examples + + + + +### Gas Cost and Priority Fee Must Not Be Explicitly Set + +On Stability, gas costs and priority fees are not applicable in the same way they are on traditional EVM-based blockchains due to the absence of a native token. `gasPrice` and `maxPriorityFeePerGas` must not be explicitly set to a non-zero number. No definition, or explicit definition to 0, is required. + +Here is an example of how this can be achieved using ethers.js: + + + + +```javascript +const tx = { + ... + maxFeePerGas: 0n + maxPriorityFeePerGas: 0n +}; +``` + + + + + +```javascript +const tx = { + ... + gasPrice: ethers.utils.parseUnits("0", "gwei"), + maxPriorityFeePerGas: ethers.utils.parseUnits("0", "gwei"), +}; +``` + + + + + + + + +### Native Token Value Transfers + +On Stability, there is no native token. Solidity functions designed to move native token value will automatically revert. This is a significant departure from traditional Ethereum-based smart contract interactions, where these methods are commonly used to manage and transfer Ether between accounts. + +- Unsupported functions: `.transfer()`, `.send()`, and any call involving `msg.value`. + +The following Solidity code snippets illustrate transactions that would **fail** on Stability: + +```bash +function sendViaTransfer(address payable _to) public payable { + _to.transfer(msg.value); +} +>> FAIL + +function sendViaSend(address payable _to) public payable { + bool sent = _to.send(msg.value); + require(sent, "Failed to send Ether"); +} +>> FAIL + +function sendViaCall(address payable _to) public payable { + (bool sent, bytes memory data) = _to.call{value: msg.value}(""); + require(sent, "Failed to send Ether"); +} +>> FAIL +``` + + + + + +### Address Balance + +On Stability, the `address.balance` operation will not function as expected. This operation, which is used to retrieve the balance of Ether (or any native token) held by an address, relies on the existence of a native token. For example: + +```bash +function getBalance() public view returns (uint) { + return address(this).balance; + } +>> Returns the selected DNT balance +``` + + + + + +### Payable Declarations + +On Stabilty, declaring functions and addresses as payable is unnecessary since the blockchain does not support native token transactions. Instead, developers should utilize the ERC-20 token standard for transactions involving token transfers. This approach involves first approving the transfer of tokens to a contract, followed by the contract executing the transfer, mirroring the functionality provided by ERC-20 tokens. + + + + + +### `Receive()` and `Fallback()` + +The `receive()` and `fallback()` functions in Solidity are designed to handle incoming transactions and unspecified function calls, respectively. However, without the capability to transfer native tokens, these functions lose their primary purpose on Stability. Developers will need to consider alternative methods for contract interactions that do not rely on direct value transfers. + + + + +## Review + +While developing on Stability offers a familiar experience to working with other EVM-compatible blockchains, the absence of a native token introduces specific considerations that developers must account for. This unique characteristic of Stability necessitates a cautious approach to smart contract and backend development, ensuring that applications are designed with these limitations in mind. diff --git a/docs/developing_on_stability/web3_developers/getting_started/_category_.json b/docs/developing_on_stability/web3_developers/getting_started/_category_.json new file mode 100644 index 0000000..a380ce9 --- /dev/null +++ b/docs/developing_on_stability/web3_developers/getting_started/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Getting Started", + "position": 2, + "link": { + "type": "generated-index", + "description": "Quick start guides for Web 3 developers." + } +} diff --git a/docs/developing_on_stability/web3_developers/getting_started/metamask_api_config.md b/docs/developing_on_stability/web3_developers/getting_started/metamask_api_config.md new file mode 100644 index 0000000..5389c3b --- /dev/null +++ b/docs/developing_on_stability/web3_developers/getting_started/metamask_api_config.md @@ -0,0 +1,124 @@ +--- +sidebar_position: 1 +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# MetaMask & API Configuration + +This guide will help you set up MetaMask and configure your API key for use with Stability. + +## Prerequisites + +This tutorial presumes a foundational understanding of blockchain technology and familiarity with tools that interact directly with the blockchain. For example, smart contracts and development tools such as Remix and Viem. + +## Register for an API Key + +Global Trust Network (GTN) and Stability Testnet employ API keys to manage transactions. On Global Trust Network, an API key is required to perform write transactions. On Stability Testnet, each address is given a limited number of free transactions without an API key using our public RPC. To increase the number of transactions that a certain user can execute on either chain, users are required to sign up with our [Account Manager](https://account.stabilityprotocol.com/keys) for their very own private RPC address. Only an e-mail is required. + +For detailed instructions on creating your API key, see [Creating Your API Key](../../../stability_api/creating_api_key.md). + +### Quick Setup Steps + +#### Step 1 - Navigate to [Stability Portal](https://portal.stabilityprotocol.com/) + +#### Step 2 - Select Your Preferred Registration + +![Stability Account Portal Screen with Login Options](../../../../static/img/Portal_Account_Register.png) + +Select your preferred registration method. Stability supports **Google Sign-in** or **Email registration**. + +- _Note: If registering via email, ensure you can verify your address._ + +#### Step 3 - Select Your Preferred Network - GTN or Testnet + +![Stability Account Portal Screen with Select Network Dropdown Highlighted](../../../../static/img/Portal_Select_Network.png) + +Use the dropdown menu in the top-right corner to select your target environment: + +- **GTN (Mainnet)**: For production-ready applications. + +- **Testnet**: For development and experimental testing. + +#### Step 4 - Click the `Create New Key` Button + +![Stability Account Portal Screen with Create API Key Button Highlighted](../../../../static/img/Portal_Create_API_Key.png) + +#### Step 5 - Congrats! You've created an API Key + +![Stability Account Portal Screen with View Details Button Highlighted ](../../../../static/img/Portal_View_Details.png) + +To view your personal RPC URL, click the `View Details` button next to your API key, followed by the `Setup Instructions` button. + +Here, you will find your personal RPC URL, as well a link that will add either network to your Metamask in one click. + +### Add Network to Metamask + +#### Add Network Automatically +![Stability Account Portal Screen with Add to Metamask](../../../../static/img/Portal_Add_To_Metamask.png) + +To add your custom RPC to your browser extension wallet, which will allow you to use Global Trust Network or Stability Testnet, click the `Add To Metamask` button. This will work with Metamask as well as many other browser extension based wallets. + +If you are not able to add the network to your wallet, you may have to add the network manually. Follow the instructions below. + +#### Add Network Manually to Metamask + +In the event you are unable to add your wallet automatically via clicking the Metamask Fox Logo above, or you wish to add the network manually, simply follow the steps below. + + + + +| **Property** | **Value** | +| ------------------ | ---------------------------------------------------- | +| Network Name | Global Trust Network | +| New RPC URL | `https://rpc.stabilityprotocol.com/zgt/YOUR_API_KEY` | +| Chain ID | 101010 | +| Currency Symbol | FREE | +| Block Explorer URL | `https://stability.blockscout.com/` | +| Request Limit | 60 Per Minute. (Higher Limits Available) | +| Max Batch Size | 40 | + + + + +| **Property** | **Value** | +| ------------------ | ------------------------------------------------------------ | +| Network Name | Stability Test Net | +| New RPC URL | `https://rpc.testnet.stabilityprotocol.com/zgt/YOUR_API_KEY` | +| Chain ID | 20180427 | +| Currency Symbol | FREE | +| Block Explorer URL | `https://testnet.stability.blockscout.com/` | +| Request Limit | 60 Per Minute. (Higher Limits Available) | +| Max Batch Size | 40 | + + + + +**Step 1** - Navigate to `Settings` in Metamask. + +![Metamask Main Screen with Settings Highlighted](../../../../static/img/metamasksettings.png) + +**Step 2** - Click on the `Networks` tab. + +![Metamask Settings Screen with Networks Highlighted](../../../../static/img/metamasknetworks.png) + +**Step 3** - Click the `Add a network` button. + +![Metamask Networks Screen with 'Add a network' Button Highlighted](../../../../static/img/metamaskaddnetwork.png) + +**Step 4** - Click the `Add a network manually` text link. + +![Metamask Add Network Screen with 'Add a network manually' Highlighted](../../../../static/img/metamaskaddanetworkmanually.png) + +**Step 5** - Go to the [Stability Account Manager](https://account.stabilityprotocol.com/keys) and copy your API Key. + +![Stability Account Manager Screen with an Example API Key Highlighted](../../../../static/img/apikeyhighlight.png) + +**Step 6** - Fill out the network settings using the details below. Be sure to replace the `YOUR_API_KEY` with your own API Key. Afterward, click Save. + +![Metamask Manual Network Screen with Details Filled and Save Button Highlighted](../../../../static/img/metamaskmanualnetworksave.png) + +## Next Steps + +- [Configure MetaMask for Zero Fees](./zero_fees_config.md) +- Review [EVM Compatibility & Solidity Development](../evm_compatibility.md) diff --git a/docs/developing_on_stability/web3_developers/getting_started/zero_fees_config.md b/docs/developing_on_stability/web3_developers/getting_started/zero_fees_config.md new file mode 100644 index 0000000..39c7000 --- /dev/null +++ b/docs/developing_on_stability/web3_developers/getting_started/zero_fees_config.md @@ -0,0 +1,102 @@ +--- +sidebar_position: 3 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Configuring MetaMask for Zero Fees + +One of the unique features of Stability is zero-fee transactions. This guide shows you how to configure MetaMask to take advantage of this. + +## Understanding Zero Fees on Stability + +Stability requires that the `Max Base Fee` and `Max Priority Fee` be set to zero. This is different from traditional Ethereum chains where gas fees are required. + +## Configuring MetaMask + +### For MetaMask Users + +When making your first transaction, you will need to manually set the gas fees to zero. It is recommended to save these values as your default settings. + +#### Step 1 - Prepare Your Smart Contract + +Before initiating a transaction, navigate to a Web3 IDE of your choice, such as [Remix](https://remix.ethereum.org/). Compile the following example contract: + +```solidity +// SPDX-License-Identifier: MIT +// Compatible with OpenZeppelin Contracts ^5.0.0 +pragma solidity ^0.8.20; + +import "@openzeppelin/contracts/token/ERC20/ERC20.sol"; + +contract PossumToken is ERC20 { + constructor() ERC20("PossumToken", "POSSUM") { + _mint(msg.sender, 10000 * 10 ** decimals()); + } +} +``` + +_**Note:** Ensure you're using the correct [Solidity and EVM compiler version](../evm_compatibility.md)._ + +#### Step 2 - Initiate a Transaction + +When a MetaMask popup appears to confirm a transaction, click the pencil icon in the estimated fee box. + +![Adjust Gas Icon in Metamask](../../../../static/img/adjustgas.png) + +#### Step 3 - Set Gas Values to Zero + +Click the advanced gas fee icon. This will allow you to customize MetaMask for zero gas transactions. + +![Advanced Gas Fee Settings in Metamask](../../../../static/img/advancegasscreen.png) + +Set your `Max Base Fee` and `Priority Fee` to **zero**. + +#### Step 4 - Save as Default + +Click the `Save these values as my default...` checkbox to avoid having to manually set the gas in the future. + +## For Developers: Coding Zero Fees + +When using libraries such as `ethers` or `viem`, you must explicitly set gas fees to zero in your code. + + + + +```javascript +const tx = { + ... + maxFeePerGas: 0n, + maxPriorityFeePerGas: 0n +}; +``` + + + + + +```javascript +const tx = { + ... + gasPrice: ethers.utils.parseUnits("0", "gwei"), + maxPriorityFeePerGas: ethers.utils.parseUnits("0", "gwei"), +}; +``` + + + + +A live example of these values being explicitly set to zero is available in the source code of our [Data Store App](https://github.com/stabilityprotocol/datastoredapp). + +## Important Notes + +- **Always** set gas fees to zero on Stability +- Transactions with non-zero gas fees will revert +- This applies to all networks: GTN and Testnet + +## Next Steps + +- Review [EVM Compatibility & What's Different](../evm_compatibility.md) to understand other important differences +- Check out [Example Apps](../../../how_stability_works/example_apps.md) for coding examples +- Explore [Tutorials](../../../tutorials/contract_deploy/deploy_contract_with_remix.md) to start building diff --git a/docs/developers/precompiles.md b/docs/developing_on_stability/web3_developers/precompiles.md similarity index 96% rename from docs/developers/precompiles.md rename to docs/developing_on_stability/web3_developers/precompiles.md index 2250e40..4ba6fe7 100644 --- a/docs/developers/precompiles.md +++ b/docs/developing_on_stability/web3_developers/precompiles.md @@ -1,7 +1,10 @@ --- -sidebar_position: 8 +sidebar_position: 4 --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # Precompiles ## What are Precompiles? @@ -16,9 +19,11 @@ Blockchains deploy precompiled contracts for two main reasons. First, if the con To interact with a precompile contract, simply treat the precompile contract as if it was any other smart contract. Stability has their own precompile contracts on our network to manage permissioned validators, as well as standard Ethereum Virtual Machine (EVM) precompiles. + + + ## Stability Native Precompiles -Stability | Address | Name | Input | Output | Description | Source | |---------|-----------|------------------------------|--------------|-----------------------------------------------------------------------------|----------------------------| | 0x801 | supportedTokensManager | data | data | A precompile that stores and manages the ATM gas and ATM tokens. | [Code](https://github.com/stabilityprotocol/stability/blob/master/precompiles/token-fee-controller/supported-tokens-manager/SupportedTokensManager.sol) | @@ -28,6 +33,10 @@ Stability | 0x806 | UpgradeRuntimeControllerPrecompile | data | data | A precompile that enables Stability to manage runtime upgrades.| [Code](https://github.com/stabilityprotocol/stability/blob/master/precompiles/upgrade-runtime-controller/UpgradeRuntimeController.sol) | | 0x807 | FeeRewardsVaultController | data | data | A precompile that enables fee-sharing logic for the ATM.| [Code](https://github.com/stabilityprotocol/stability/blob/master/precompiles/fee-rewards-vault-controller/FeeRewardsVaultController.sol) | + + + + ## Ethereum Native Precompiles To Learn More About Ethereum Precompile Contracts, we highly recommend visiting [EVM Codes](https://www.evm.codes/precompiled?fork=shanghai) @@ -45,3 +54,6 @@ To Learn More About Ethereum Precompile Contracts, we highly recommend visiting | 0x09 | Blake2 | rounds, h, m, t, f | h | Implements the BLAKE2b hash function and other higher-round 64-bit BLAKE2 variants to run cheaply on the EVM. | | 0x400 | SHA3FIPS256 | data | hash | Implements the SHA-3 (Secure Hash Algorithm 3) cryptographic hashing function as specified in FIPS 202 (Federal Information Processing Standards Publication). This precompile takes an arbitrary length input and processes it to produce a fixed-length 256-bit (32 bytes) output hash. | | 0x402 | ECRecoverPublicKey | hash, v, r, s | hash | Similar to ecRecover, but returns the pubkey (not the corresponding Ethereum address) | + + + diff --git a/docs/developers/public_rpc.md b/docs/developing_on_stability/web3_developers/public_rpc.md similarity index 93% rename from docs/developers/public_rpc.md rename to docs/developing_on_stability/web3_developers/public_rpc.md index 58ffe5d..743f7f4 100644 --- a/docs/developers/public_rpc.md +++ b/docs/developing_on_stability/web3_developers/public_rpc.md @@ -1,5 +1,5 @@ --- -sidebar_position: 9 +sidebar_position: 5 --- # Public RPC Guide @@ -16,7 +16,7 @@ For Ethereum API specifics, refer to the [Ethereum API Documentation](https://et ### Stability Testnet Access -The Stability Public Testnet RPC is read-only for the blockchain. Users looking to perform transactions should acquire a free API key as detailed on our [Getting Started page](./getting_started.md). +The Stability Public Testnet RPC is read-only for the blockchain. Users looking to perform transactions should acquire a free API key as detailed on our [Creating Your API Key](../../stability_api/creating_api_key.md) page. - **RPC URL**: `https://rpc.testnet.stabilityprotocol.com/zgt/YOUR_API_KEY` - **Chain ID**: `20180427` @@ -25,7 +25,7 @@ The Stability Public Testnet RPC is read-only for the blockchain. Users looking ### Global Trust Network Mainnet Access -The Global Trust Network (GTN) Public RPC is read-only for the blockchain. Transaction execution is not available through the GTN Public RPC. Users looking to perform transactions should acquire a free API key as detailed on our [Getting Started page](./getting_started.md). +The Global Trust Network (GTN) Public RPC is read-only for the blockchain. Transaction execution is not available through the GTN Public RPC. Users looking to perform transactions should acquire a free API key as detailed on our [Creating Your API Key](../../stability_api/creating_api_key.md) page. - **RPC URL**: `https://rpc.stabilityprotocol.com/zgt/YOUR_API_KEY` - **Chain ID**: `101010` diff --git a/docs/how_stability_works/_category_.json b/docs/how_stability_works/_category_.json index 98632d4..d694d9e 100644 --- a/docs/how_stability_works/_category_.json +++ b/docs/how_stability_works/_category_.json @@ -1,6 +1,6 @@ { "label": "How Stability Works", - "position": 2, + "position": 1, "link": { "type": "generated-index" } diff --git a/docs/how_stability_works/architecture.md b/docs/how_stability_works/architecture.md index 395387c..2509acf 100644 --- a/docs/how_stability_works/architecture.md +++ b/docs/how_stability_works/architecture.md @@ -4,36 +4,43 @@ sidebar_position: 2 # Architecture -![Depication of Stability Architecture](../../static/img/arch.png) +![Depiction of Stability Architecture](../../static/img/arch.png) -## Overview : Let's Get Boring! +## Overview +Stability deviates from traditional blockchains by removing the token requirement for transaction validation. While traditional networks rely on volatile Proof of Work (PoW) or Proof of Stake (PoS) models, Stability utilizes **Proof of Authority (PoA)**. -Stability represents a pioneering approach in public blockchains by operating without the need for tokens to facilitate transactions. This is achieved through our innovative validator system. Traditional blockchains rely on consensus mechanisms like Proof of Work (PoW) or Proof of Stake (PoS). In contrast, Stability utilizes Proof of Authority (PoA) using known entities. This mechanism involves onboarding trusted entities to serve as validators. +This model leverages a network of known, trusted entities as validators, ensuring a stable environment for production-ready applications. -## Portal: Private RPCs to Submit Transactions -To submit transactions to Stability, a user must register through our Stability's [Account Manager](https://account.stabilityprotocol.com/keys) portal. Users begin by obtaining an API Key to unlock a private RPC. This RPC is allocated a certain number of credits, effectively determining the number of transactions a user can submit. To submit a transaction, a user consumes credits from their private RPC allotment. Using Stability's [Account Manager](https://account.stabilityprotocol.com/keys) portal, users can monitor their credit usage and obtain additional credits as needed, allowing for continuous and uninterrupted interaction with the network. Instructions for setting up an account and obtaining your own free RPC are available in the [User Section](../users/getting_started.md). +## Portal: Managed Access via Private RPCs +To interact with the network, developers use the Stability [Account Manager](https://account.stabilityprotocol.com/keys). Instead of managing a wallet with a fluctuating balance, you generate an **API Key** that unlocks a Private RPC. -## Sequencing: How Stability Prepares Submitted Transactions +- **Credit-Based Access**: Your RPC is allocated a set number of credits for transactions. + +- **Zero-Gas Execution**: Submitting a transaction simply consumes a credit from your private allotment. No native tokens required. + +- **Scalable Management**: Monitor usage and scale your credit limits through the dashboard to ensure uninterrupted service. -In conventional blockchain systems, transactions are broadcast to a public mempool, where validators and miners select transactions to compile into a new block. Typically, these actors prioritize transactions offering higher fees, as these are more profitable to validate and mine. +For setup details, see the [Stability API](../stability_api/creating_api_key.md) Guide. -Stability Protocol adopts a different approach to transaction sequencing. Our network only considers the chronological order of transaction submissions. This method ensures a fairer and more predictable processing time, as transactions are mined based on their submission time rather than their associated gas fees. As a result, users experience a more consistent and equitable transaction processing environment, with transactions typically being processed within a remarkably short timeframe of 2 seconds. +## Sequencing: How Stability Prepares Submitted Transactions +Unlike conventional blockchains where "gas wars" allow actors to prioritize more "profitable" transactions offering higher gas fees, Stability ensures a fairer, more equitable environment. + +- **Chronological Ordering**: Transactions are processed strictly by their submission time. This consistent and equitable environment ensures predictable transaction processing within approximately 2 seconds. -Furthermore, this sequencing mechanism ensures all transactions are private until they have been mined. Versus the public mempool of conventional blockchains, the mempool on Stability is private. The details of a transaction are not known until they have been finalized on our network. +- **Private Mempool**: Unlike the public mempools of traditional chains, Stability’s mempool is private; transaction details remain hidden until they are finalized on the network. -The network's infrastructure is robust, capable of handling approximately 10,000 transactions per second (TPS). This high throughput is indicative of the network's efficiency and scalability. The underlying architecture and technology enable the Stability Protocol to maintain high performance while offering the potential for further scalability. This scalability is crucial for accommodating an increasing volume of transactions as the network grows, ensuring that the system remains efficient and responsive even under heavy loads. +- **High Throughput**: The infrastructure handles approximately 10,000 transactions per second (TPS), maintaining high performance and potential for further scalability. ## Validators: Achieving Consensus Stability has created a novel consensus mechanism to facilitate our feeless blockchain. ### Aura: Block Creation -Aura is a slot-based, round-robin mechanism for block creation, performed by a predefined set of validator nodes. In this system, time is divided into distinct slots, and each slot is assigned to a specific validator. This ensures a predictable and fair block creation process, as each validator knows in advance when it will be their turn to create a block. The round-robin nature of Aura ensures that the opportunity to create blocks is evenly distributed among all validators, enhancing the decentralization and fairness of the process. +Aura is a slot-based, round-robin mechanism where time is divided into distinct slots, each assigned to a specific validator. This ensures a predictable and fair process, as each validator knows in advance when it is their turn to create a block. ### GRANDPA: Block Finality -Grandpa stands for GHOST-based Recursive Ancestor Deriving Prefix Agreement. It is a deterministic finality algorithm that employs the longest chain rule, necessitating a known, weighted set of validator nodes. GRANDPA is designed to work in tandem with a block production mechanism like Aura. It provides finality to blocks, meaning that once a block is deemed final by GRANDPA, it cannot be reverted, ensuring the integrity and continuity of the blockchain. In other words, GRANDPA's determination of the correct block is final. The combination of GRANDPA with a block production mechanism ensures both efficient block creation and robust finality, contributing to the overall security and stability of the blockchain. - -Together, Aura and GRANDPA form the backbone of the Stability Protocol's consensus mechanism, ensuring a highly secure and efficient blockchain. +GRANDPA (GHOST-based Recursive Ancestor Deriving Prefix Agreement) provides deterministic finality by employing the longest chain rule. Once a block is deemed final by GRANDPA, it cannot be reverted, ensuring the absolute integrity and continuity of the blockchain. +Together, Aura and GRANDPA form the backbone of the Stability Protocol's consensus mechanism, ensuring efficient block creation and robust finality, making Stability a highly secure and efficient blockchain. diff --git a/docs/how_stability_works/example_apps.md b/docs/how_stability_works/example_apps.md index be04ae3..58fd3ab 100644 --- a/docs/how_stability_works/example_apps.md +++ b/docs/how_stability_works/example_apps.md @@ -1,28 +1,40 @@ --- -sidebar_position: 3 +sidebar_position: 4 --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # Example Apps +Explore example dApps created by the Stability Team. -The following are a list of example dApps created by the Stability Team. + + ## Stability Account Portal - Mainnet & Testnet **Generates API Keys For Individual RPCs** / **Wallet Not Required** A platform for creating free accounts to allow you to interact and perform transactions on the Stability Testnet and Global Trust Network. You can create an API key to use with an RPC URL for wallets such as MetaMask or create an account with MagicLink for a wallet-free experience. -For a walkthrough on this process, please visit our [**Getting Started**](../users/getting_started.md) tutorial. If you wish to interact with these apps, be sure to register with Stability Testnet. +For a walkthrough on this process, please visit our [**Creating Your API Key**](../stability_api/creating_api_key.md) tutorial. If you wish to interact with these apps, be sure to register with Stability Testnet. [**Launch App**](https://account.stabilityprotocol.com) + + + ## Stability Publisher - Mainnet & Testnet **Demonstrates Data Publishing on Stability** / **Walletless** -A simple decentralized application (dApp) and React frontend that allows users to submit messages to the Stability Blockchain using our experimental [**ZKT RPC**](../developers/zkt.md), with the option to post to either the Testnet or Mainnet. +A simple decentralized application (dApp) and React frontend that allows users to submit messages to the Stability Blockchain using our experimental [**ZKT RPC**](../developing_on_stability/web2_developers/zkt/overview), with the option to post to either the Testnet or Mainnet. [**Launch App**](https://stabilityprotocol.github.io/stability-publisher-dapp/) | [**Github - Source Code**](https://github.com/stabilityprotocol/stability-publisher-dapp) + + + + ## Mintify - Testnet **Demonstrates Tokenization on Stability** / **Wallet Not Required** @@ -33,6 +45,10 @@ The Mintify app demonstrates the simplest web3 onboarding experience in the worl [**Launch App**](https://mintify.stabilityprotocol.com) | [**Github - Source Code**](https://github.com/stabilityprotocol/demo-fungibles) + + + + ## PayNow - Testnet **Demonstrates Secure P2P Token Transfers Using Magiclink on Stability** / **Walletless** @@ -41,3 +57,6 @@ The Mintify app demonstrates the simplest web3 onboarding experience in the worl The PayNow app demonstrates frictionless peer-to-peer stablecoin payments on Stability Testnet, using names as recipients. These transfers can occur with or without wallets by utilizing MagicLink. By using names as recipients, quick money transfers are as simple as your standard cash app. [**Launch App**](https://paynow.stabilityprotocol.com) + + + \ No newline at end of file diff --git a/docs/how_stability_works/intro_to_stability.md b/docs/how_stability_works/intro_to_stability.md index a100c48..db88ba4 100644 --- a/docs/how_stability_works/intro_to_stability.md +++ b/docs/how_stability_works/intro_to_stability.md @@ -4,31 +4,28 @@ sidebar_position: 1 # Intro to Stability Network -Welcome to the Stability Network, an innovative approach to blockchain technology that challenges the conventional norms. Stability stands out in the blockchain landscape as a feeless, open-source, decentralized, public, and highly scalable platform. This introduction aims to provide a high-level overview of Stability's unique features and how they collectively contribute to its distinct position in the blockchain ecosystem. +Stability Network challenges the conventional norms in the blockchain landscape as a public, feeless, open-sourced and decentralised network. Stability provides a high-throughput environment where Users and developers, both Web2 & web3, can build without friction. + --- -### Feeless +### 💳 Feeless -**Transactions without Gas Fees**: Unlike traditional blockchains that require tokens for transaction fees (often referred to as "gas"), Stability offers a groundbreaking alternative. Transactions on the Stability network do not require a token, eliminating the need for users to hold or manage any form of native cryptocurrency. This is made possible through the use of API keys, which allocate transactions to users through secure, unique RPC addresses. This feeless approach allows for an accessable, better user experience while reducing costs for all parties. +**No Crypto Required**: Stability replaces traditional "gas" fees with an API-key-based model. Transactions are allocated via secure, unique RPC addresses, allowing users to interact with applications built on Stability without holding or managing native cryptocurrency. This approach makes the user experience better while reducing costs for all parties -### Open-Source +### 🔓 Open-Source -**Transparent Codebase**: Emphasizing transparency and security, Stability's core codebase is fully accessible on GitHub. This open-source approach allows for complete visibility into the blockchain's workings, fostering a high level of trust and security among its users. By making its source code publicly available, Stability ensures that security experts and enthusiasts can review and audit the system, contributing to a more secure and robust blockchain infrastructure. +**Transparent Codebase**: Stability's core codebase is open-source and publicly accessible on GitHub. Our open-source approach ensures the network is auditable by the community, fostering a secure, robust infrastructure through collective contribution. -### Decentralized +### 🕸️ Decentralized -**Trusted Network Consensus**: Stability achieves decentralization through AuRa and GRANDPA consensus pallets using a diverse network of nodes. These nodes are operated by various trusted entities, ensuring that no single entity has control over the entire network. This decentralized architecture enhances security, promotes transparency, and ensures that the network remains resilient against attacks and failures. +**Trusted Network Consensus**: Stability utilizes a diverse network of nodes governed by **AuRa** and **GRANDPA** consensus mechanisms. Operated by trusted independent entities, this decentralized architecture ensures the network remains tamper-proof, transparent, and resilient against attacks and failures -### Public +### 🌍 Public -**Open Access for Everyone**: The Stability Network is a truly public platform, welcoming everyone to engage with it without restrictions. Unlike many public blockchains that necessitate cryptocurrencies for network interactions, or private blockchains that restrict access and user permissions, Stability ensures open participation. This inclusivity invites developers to create decentralized applications (dApps), enables users to delve into cutting-edge blockchain technologies, and empowers organizations to incorporate blockchain-based solutions. By providing an open and accessible environment, Stability fuels innovation and democratizes the use of blockchain technology, making it available to all. +**Open Access for Everyone**: Our network is truly public. Unlike private blockchains that restrict access or traditional public chains that require financial entry (tokens), Stability allows any developer or organization to deploy decentralized applications (dApps) and interact with the ledger instantly, feuling innovation and democratizing the use of blockchain technology. -### Highly Scalable +### ⚡ Highly Scalable -**Next Level Throughput**: One of the most significant challenges facing traditional blockchains is scalability. Stability addresses this head-on with its capability to process up to 10,000 transactions per second (tx/s), with potential to scale even further. This exceptional throughput is achieved through advanced architectural designs and optimization techniques, ensuring that Stability can accommodate the growing demands of modern applications without compromising speed or reliability. - ---- +**Enterprise-Grade Throughput**: Stability is engineered for performance, processing up to 10,000 transactions per second (tx/s) with potential to scale further. Stability's high-capacity architecture ensures your applications remain fast and reliable as demand grows. -# Stability is Different -The Stability Network represents a significant leap forward in blockchain technology, offering a unique blend of features that make it an attractive platform for a wide range of applications. Its feeless nature, open-source ethos, decentralized architecture, public accessibility, and high scalability set it apart as a forward-thinking solution for the future of decentralized systems. diff --git a/docs/how_stability_works/transactions.md b/docs/how_stability_works/transactions.md new file mode 100644 index 0000000..df677da --- /dev/null +++ b/docs/how_stability_works/transactions.md @@ -0,0 +1,17 @@ +--- +sidebar_position: 3 +--- + +# About Our Free Transactions + +## Overview +One of the standout features of our blockchain platform is the implementation of zero gas price transactions, reflecting our commitment to providing an efficient and cost-effective transaction experience. This initiative allows users to execute transactions without the burden of gas fees, a common expense in many other blockchain environments. + +### Free Transactions +Stability offers **unlimited transactions** on our networks, subject to a rate limit of **60 requests per minute**, available to every registered API key regardless of the account plan. This monthly allotment provides a risk-free environment for testing, development, and exploring the full capabilities of the network. + +Users can monitor their real-time transaction count and reset timing by visiting the **[Stability Portal](https://portal.stabilityprotocol.com)**. + +For detailed instructions on how to integrate your API key into your development workflow, please refer to the **[Developing On Stability](../category/developing-on-stability)** documentation. + + diff --git a/docs/resources/_category_.json b/docs/resources/_category_.json index adae13f..6373286 100644 --- a/docs/resources/_category_.json +++ b/docs/resources/_category_.json @@ -1,6 +1,6 @@ { "label": "Resources", - "position": 7, + "position": 5, "link": { "type": "generated-index" } diff --git a/docs/resources/audits.md b/docs/resources/audits.md index d8a49f1..4db9b4a 100644 --- a/docs/resources/audits.md +++ b/docs/resources/audits.md @@ -2,6 +2,9 @@ sidebar_position: 6 --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # Audit ## Executive Summary - SlowMist Audit Report Summary - Stability Pallets @@ -14,59 +17,36 @@ The audit targeted the Stability blockchain implemented in Substrate + Rust, foc ## Findings and Actions Taken -### High Severity Vulnerabilities - -1. **Arithmetic Accuracy Deviation Vulnerability**: - - - **Description**: Potential loss of precision or accuracy due to the use of `saturating_add`, `saturating_mul`, and `saturating_sub` in Rust. - - **Action Taken**: Replaced with checked arithmetic functions (`checked_add`, `checked_mul`, `checked_sub`) to handle overflows gracefully. - - **Status**: Fixed. - -2. **Integer Overflow Audit**: - - - **Description**: Risks of integer overflow in numeric variables without proper overflow checks. - - **Action Taken**: Implemented checked arithmetic functions. - - **Status**: Fixed. + + -3. **Error Unhandle Audit (Division by Zero)**: - - **Description**: Potential program panic due to division by zero in Rust. - - **Action Taken**: Added checks for division by zero. - - **Status**: Fixed. +| Description | Actions Taken | Status | +|-------------|--------------|--------| +| **Arithmetic Accuracy Deviation Vulnerability**
Potential loss of precision or accuracy due to the use of `saturating_add`, `saturating_mul`, and `saturating_sub` in Rust. | Replaced with checked arithmetic functions (`checked_add`, `checked_mul`, `checked_sub`) to handle overflows gracefully. | Fixed | +| **Integer Overflow Audit**
Risks of integer overflow in numeric variables without proper overflow checks. | Implemented checked arithmetic functions. | Fixed | +| **Error Unhandle Audit (Division by Zero)**
Potential program panic due to division by zero in Rust. | Added checks for division by zero. | Fixed | -### Low Severity Vulnerabilities + + -1. **Weights Audit (Unreasonable Pallet Weight)**: +| Description | Actions Taken | Status | +|-------------|--------------|--------| +| **Weights Audit (Unreasonable Pallet Weight)**
Operations having their weight set to 0, potentially leading to unreasonable resource allocation. | Reviewed and adjusted weights based on computational requirements. | Fixed | +| **Arithmetic Accuracy Deviation Vulnerability (Balance Precision Loss)**
Loss of balance precision when converting `U256` to `u128`. | Acknowledged as a known limitation; implemented fallback checks. | Acknowledged | - - **Description**: Operations having their weight set to 0, potentially leading to unreasonable resource allocation. - - **Action Taken**: Reviewed and adjusted weights based on computational requirements. - - **Status**: Fixed. - -2. **Arithmetic Accuracy Deviation Vulnerability (Balance Precision Loss)**: - - **Description**: Loss of balance precision when converting `U256` to `u128`. - - **Action Taken**: Acknowledged as a known limitation; implemented fallback checks. - - **Status**: Acknowledged. + + ### Suggested Improvements -1. **Unimplemented Function Logic**: - - - **Description**: Certain functions lacking full implementation. - - **Action Taken**: Acknowledged and reviewed; these functions were mocked as they are not utilized in the current logic. - - **Status**: Acknowledged. - -2. **Node Crash Risk (Use of `panic!()`)**: - - - **Description**: Potential node crash due to the use of `panic!()` in certain functions. - - **Action Taken**: Replaced `panic!()` with appropriate error handling. - - **Status**: Fixed. - -3. **Avoid Hardcoding Values**: - - **Description**: Hardcoded Ethereum addresses in the code. - - **Action Taken**: Refactored to use configuration files, environment variables, and parameterization for more flexibility. - - **Status**: Fixed. +| Description | Actions Taken | Status | +|-------------|--------------|--------| +| **Unimplemented Function Logic**
Certain functions are lacking full implementation. | Acknowledged and reviewed; these functions were mocked as they are not utilized in the current logic. | Acknowledged | +| **Node Crash Risk (Use of `panic!()`)**
Potential node crash due to the use of `panic!()` in certain functions. | Replaced `panic!()` with appropriate error handling. | Fixed | +| **Avoid Hardcoding Values**
Hardcoded Ethereum addresses in the code. | Refactored to use configuration files, environment variables, and parameterization for more flexibility. | Fixed | ## Conclusion The audit identified 4 high-risk, 4 low-risk, and 3 suggested vulnerability categories. The team has addressed most of the vulnerabilities, with some acknowledged due to their nature or current architecture limitations. -[Find the full report here](../../static/Slowmist-Audit.pdf). \ No newline at end of file +[Find the full report here](../../static/Slowmist-Audit.pdf). diff --git a/docs/resources/benchmark_tests.md b/docs/resources/benchmark_tests.md index b3a7d9e..b25629e 100644 --- a/docs/resources/benchmark_tests.md +++ b/docs/resources/benchmark_tests.md @@ -2,6 +2,9 @@ sidebar_position: 3 --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # Benchmark Tests The benchmark tests presented here offer an evaluation of Stability Testnet and Global Trust Network (GTN) in regards to latency and throughput. These tests have been designed to simulate real-world transaction loads. @@ -17,6 +20,9 @@ These tests occurred on March 11th, 2024 for Testnet, and March 12th, 2024 for G | Total Block Gas | The cumulative gas used by all transactions in a block. This metric gives an overview of the block's capacity utilization. | | Max Transactions Per Block | The maximum number of transactions that can be included in a single block, which is directly influenced by the block gas limit and the gas used per transaction. | + + + ## Testnet Results | TRANSACTIONS PER SECOND | GAS PER TRANSACTION | TOTAL BLOCK GAS | MAX TRANSACTIONS PER BLOCK | LINK | @@ -31,6 +37,10 @@ These tests occurred on March 11th, 2024 for Testnet, and March 12th, 2024 for G | 94.50 | 1,000,000.00 | 160,541,685.00 | 189 | [Link](https://stability-testnet.blockscout.com/block/345303) | | 152.50 | 1,000,000.00 | 296,552,763.00 | 305 | [Link](https://stability-testnet.blockscout.com/block/345376) | + + + + ## Global Trust Network (GTN) Results | TRANSACTIONS PER SECOND | GAS PER TRANSACTION | TOTAL BLOCK GAS | MAX TRANSACTIONS PER BLOCK | LINK | @@ -45,3 +55,6 @@ These tests occurred on March 11th, 2024 for Testnet, and March 12th, 2024 for G | 176.00 | 300,000.00 | 103,056,480 | 354 | [Link](https://stability.blockscout.com/block/355006) | | 174.50 | 500,000.00 | 171,445,552 | 349 | [Link](https://stability.blockscout.com/block/355037) | | 305.00 | 500,000.00 | 299,661,280 | 610 | [Link](https://stability.blockscout.com/block/355088) | + + + diff --git a/docs/resources/block_explorer.md b/docs/resources/block_explorer.md index 6c1dda1..14ad112 100644 --- a/docs/resources/block_explorer.md +++ b/docs/resources/block_explorer.md @@ -4,13 +4,12 @@ sidebar_position: 1 # Block Explorer -The Global Trust Network (GTN) Block Explorer can be accessed by the following URL: +You can explore the Global Trust Network (GTN) and Stability Testnet networks using the following block explorers: -[https://stability.blockscout.com/](https://stability.blockscout.com/) +- **[GTN (Mainnet) Block Explorer:](https:explorer.stabilityprotocol.com/)** +- **[Stability Testnet Block Explorer:](https:explorer.testnet.stabilityprotocol.com/)** -The Stability Testnet Block Explorer allows you to inspect, analyze, and interact with real-time data on Stability Chain Testnet. The block explorer can be accessed by the following URL: - -[https://explorer.stble.io/testnet/blocks/](https://explorer.stble.io/testnet/blocks/) +These explorers allow you to inspect, analyze, and interact with real-time data on the respective Stability networks. ## Transactions diff --git a/docs/resources/contact.md b/docs/resources/contact.md index 07d7889..06a1cc3 100644 --- a/docs/resources/contact.md +++ b/docs/resources/contact.md @@ -4,56 +4,22 @@ sidebar_position: 7 # Contact Us -## Ways to Reach Out 🤝 - -## Discord - -We're open to conversation and eager to hear from you! Our primary hub for chats, updates, and live interactions is our Discord server. Jump in to join our vibrant community. - -
- - discord_ico - Join us on Discord - Link Icon - -
- -## Direct Messages - -Feel free to reach out directly if you have specific inquiries or need support. Our inbox is always open. - -
- -📩 Send us a message directly here -Link Icon - - -
- -## Connect with Us on Social Media - -Stay updated with our latest news, insights, and activities by following us on social media. - -
- - linkdin_ico - LinkedIn - Link Icon - -
- -
- - x_ico - X (fka Twitter) - Link Icon - -
- -
- - medium_ico - Medium - Link Icon - -
+We're here to help! Reach out to us through the following channels: + +## 💬 Discord + +[Join](https://discord.com/invite/68j2XtTKY9) our active community for support, updates, and real-time discussions: + + +## 📩 Direct Message + +Have specific questions or need support? [Contact us](https://us21.list-manage.com/contact-form?u=8afbcbdb9e4fdad91bd87ce22&form_id=9e39027f0e20b64fe0eb9a79af776a0c) directly through our form: + + +## 🌐 Social Media + +Stay connected and follow us for news and updates: + +- [LinkedIn](https://www.linkedin.com/company/stabilitysolutions) +- [X (Twitter)](https://twitter.com/stabilityinc) +- [Medium](https://medium.com/stabilitynetwork) diff --git a/docs/resources/faq.md b/docs/resources/faq.md index 0136a0e..751212b 100644 --- a/docs/resources/faq.md +++ b/docs/resources/faq.md @@ -2,97 +2,150 @@ sidebar_position: 2 --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # FAQ _Frequently asked questions_ -## Using Stability + + + +
+How can a public blockchain work without cryptocurrency? -### How can a public blockchain work without cryptocurrency? +Stability sets all gas prices to zero, therefore there is no cost to perform a transaction. -Stability sets all gas prices to zero, therefore there is no cost to perform a transaction. +
-### Can I use my existing wallet app on Stability? +
+Can I use my existing wallet app on Stability? Yes, all EVM-compatible wallets, such as Metamask, work on Stability. -### Can I use my existing Ethereum address on Stability? +
+ +
+Can I use my existing Ethereum address on Stability? Yes. Private keys used on Ethereum, or any other EVM-based blockchain, will resolve to the same public address. -### How can I connect to Global Trust Network (GTN)? +
+ +
+How can I connect to Global Trust Network (GTN)? Global Trust Network (GTN) uses the same architecture for performing transactions as most blockchain networks. Simply connect to an RPC and you are able to perform transactions on GTN. -To perform transactions on GTN, you must sign up for an API key. This allows for up to 1,000 daily transactions per API Key on Global Trust Network, and only requires a sign on using your e-mail, Github, or Google account. It is completely free. For an easy step-by-step guide to doing so, please check out [Getting Started ](../users/getting_started.md) page. +To perform transactions on GTN, you must sign up for an API key. This allows for up to 1,000 daily transactions per API Key on Global Trust Network, and only requires a sign on using your e-mail, Github, or Google account. It is completely free. For an easy step-by-step guide to doing so, please check out [Creating Your API Key](../stability_api/creating_api_key.md) page. The connection details for GTN are as follows. Simply replace 'YOUR_API_KEY' with your API key. - - **Network Name:** Global Trust Network - - **New RPC URL:** `https://rpc.stabilityprotocol.com/zgt/YOUR_API_KEY` - - **Chain ID:** 101010 - - **Currency Symbol:** FREE - - **Block Explorer URL:** `https://stability.blockscout.com/` +- **Network Name:** Global Trust Network +- **New RPC URL:** `https://rpc.stabilityprotocol.com/zgt/YOUR_API_KEY` +- **Chain ID:** 101010 +- **Currency Symbol:** FREE +- **Block Explorer URL:** `https://stability.blockscout.com/` -### How can I connect to Stability Testnet? +
+ +
+How can I connect to Stability Testnet? Stability uses the same architecture for performing transactions as most blockchain networks. Simply connect to an RPC and you are able to perform transactions on Stability. - We currently offer two options for connecting to Stability Testnet. +We currently offer two options for connecting to Stability Testnet. -Our public RPC allows a limit of 25 transactions per address. Users wishing to go beyond 25 free daily transactions should register for a free API Key on our testnet. This provides a private RPC this allows for up to 1,000 monthly transactions per API Key on Stability Testnet, and only requires a sign on using your e-mail, Github, or Google account. It is completely free. For an easy step-by-step guide to doing so, please check out [Getting Started ](../users/getting_started.md) page. +Our public RPC allows a limit of 25 transactions per address. Users wishing to go beyond 25 free daily transactions should register for a free API Key on our testnet. This provides a private RPC this allows for up to 1,000 monthly transactions per API Key on Stability Testnet, and only requires a sign on using your e-mail, Github, or Google account. It is completely free. For an easy step-by-step guide to doing so, please check out [Creating Your API Key](../stability_api/creating_api_key.md) page. Our connection details for our public RPC is as follows - - - **Network Name:** Stability Test Net - - **New RPC URL:** `https://rpc.testnet.stabilityprotocol.com/zgt/YOUR_API_KEY` - - **Chain ID:** 20180427 - - **Currency Symbol:** FREE - - **Block Explorer URL:** `https://explorer.stble.io/testnet/` - - **Request Limit:** 200 Per Minute Free / 1500 Per Minute Tier 1 - - **Max Batch Size:** 40 +- **Network Name:** Stability Test Net +- **New RPC URL:** `https://rpc.testnet.stabilityprotocol.com/zgt/YOUR_API_KEY` +- **Chain ID:** 20180427 +- **Currency Symbol:** FREE +- **Block Explorer URL:** `https://explorer.stble.io/testnet/` +- **Request Limit:** 200 Per Minute Free / 1500 Per Minute Tier 1 +- **Max Batch Size:** 40 +
-### Will using the private RPC result in my transactions occurring on a different network? +
+Will using the private RPC result in my transactions occurring on a different network? No, all public and private transactions will occur on the same public testnet network. -### What happens if I run out of free transactions? +
+ +
+What happens if I run out of free transactions? If the daily free transactions exceed your allocated daily limit, your transactions will not be processed by Stability Testnet. Each transaction will return as 'Failed'. -### Why are there limits on the amount of transactions? +
+ +
+Why are there limits on the amount of transactions? We set limits to prevent spamming of the network. -## Developing on Stability +
+ + + + -### I am a developer - how do I develop on Stability? +
+I am a developer - how do I develop on Stability? -Developing on Stability uses the same tooling as Ethereum, or any other EVM-based blockchain. +Developing on Stability uses the same tooling as Ethereum, or any other EVM-based blockchain. -### Can I deploy and interact with smart contracts on Stability? Is it the same as Ethereum? +
-Yes. Stability is an EVM-based blockchain and most smart contract functionality remains the same. There are a few notable differences due to our feeless model. For further detail, view our [What is different on Stability](../developers/what_is_different.md) documentation. +
+Can I deploy and interact with smart contracts on Stability? Is it the same as Ethereum? -### Can I create and deploy my own tokens on the Stability? +Yes. Stability is an EVM-based blockchain and most smart contract functionality remains the same. There are a few notable differences due to our feeless model. For further detail, view our [EVM Compatibility & Solidity Development](../developing_on_stability/web3_developers/evm_compatibility.md) documentation. + +
+ +
+Can I create and deploy my own tokens on the Stability? Yes. Go nuts! The Stability Testnet is here for experimentation, and exploring the possiblities of zero-gas transactions. -### I would like to have a larger quota for Stability. How can I do this? +
+ +
+I would like to have a larger quota for Stability. How can I do this? Please contact us using the following [`Google Form`](https://docs.google.com/forms/d/e/1FAIpQLSfiBQOc0z9HtHyHCH1QCIZWQ0mdJ8koGaWysErJHJRylQy2Yw/viewform) -### What is the block time on Stability? +
+ +
+What is the block time on Stability? Our average block time is ~2secs. -### What is the current block size on Stability? +
+ +
+What is the current block size on Stability? Our current block size allows for 300,000,000 gas units per block. -### What is the maximum size of a transaction? +
+ +
+What is the maximum size of a transaction? The maximum size for a transaction is 260,000,000 gas units. +
+ + + +