From 5992f5e743a5f5c2cb16a623311e17c5ea81d81a Mon Sep 17 00:00:00 2001 From: Angela Gilhotra Date: Fri, 4 Sep 2026 22:27:47 -0400 Subject: [PATCH 1/2] docs: update v1.8 protocol documentation --- docs/pages/en/explanation/core-concepts.mdx | 9 +- docs/pages/en/explanation/execution.mdx | 10 +- .../en/explanation/guaranteed-blockspace.mdx | 29 +- docs/pages/en/explanation/stable-db.mdx | 16 +- docs/pages/en/explanation/staking-module.mdx | 6 +- .../explanation/system-modules-overview.mdx | 10 +- .../en/explanation/system-transactions.mdx | 24 +- docs/pages/en/explanation/tech-overview.mdx | 14 +- .../en/explanation/technical-roadmap.mdx | 18 +- docs/pages/en/how-to/track-unbonding.mdx | 101 ++++- docs/pages/en/how-to/upgrade-node.mdx | 331 ++++++-------- docs/pages/en/how-to/use-system-modules.mdx | 23 +- docs/pages/en/reference/network-upgrades.mdx | 48 +- .../en/reference/system-transactions-api.mdx | 413 +++++------------- .../en/reference/testnet-version-history.mdx | 25 +- 15 files changed, 462 insertions(+), 615 deletions(-) diff --git a/docs/pages/en/explanation/core-concepts.mdx b/docs/pages/en/explanation/core-concepts.mdx index 45b22f6..8af8d28 100755 --- a/docs/pages/en/explanation/core-concepts.mdx +++ b/docs/pages/en/explanation/core-concepts.mdx @@ -15,6 +15,7 @@ You pay transaction fees in USDT0, the same asset you're already holding and tra USDT0 is both the native gas asset (18 decimals, read via `address(x).balance`) and an ERC-20 token (6 decimals, read via `USDT0.balanceOf(x)`). Both interfaces operate on the same underlying balance, and the protocol reconciles the 12-digit precision gap automatically. ```solidity +// SAFE: both reads use Stable's canonical balance interfaces. // Both read the same balance: uint256 native = address(user).balance; // 18 decimals uint256 erc20 = IERC20(USDT0).balanceOf(user); // 6 decimals @@ -28,11 +29,11 @@ Read more: [USDT0 as gas](/en/explanation/usdt-as-gas-token) · [USDT0 behavior ## Guaranteed blockspace -Stable v1.4.0 can reserve a gas quota within each block for eligible priority workloads. Normal traffic cannot consume this VIP-lane capacity during congestion. +Stable v1.8.0 reserves a gas quota within each block for eligible priority workloads. Normal traffic cannot consume this Enterprise-lane capacity during congestion. -Standard EVM transactions keep using the default nonce channel, `NonceKey = 0`. Eligible priority flows use `CustomTx` type `0x3F` and a protocol-reserved `NonceKey` that identifies the VIP lane. +Standard EVM transactions keep using the default nonce channel, `NonceKey = 0`. Eligible priority flows use `CustomTx` type `0x3F` and a `NonceKey` with bit 63 set. -Governance configures the lanes and quotas. With no configuration, every transaction uses one normal lane. The feature is currently in the v1.4.0 Testnet release candidate, with its Mainnet schedule pending. +Governance configures the lanes and quotas. Guaranteed blockspace is live on Mainnet and Testnet, and `StableSystem.blockspaceLanes()` returns the active configuration. Read more: [Guaranteed blockspace](/en/explanation/guaranteed-blockspace). @@ -87,7 +88,7 @@ Stable has a planned feature for zero-knowledge transfers that hide amounts whil Read more: [Confidential transfer](/en/explanation/confidential-transfer). -## Next recommended +## Where to go next - [**Quick start**](/en/tutorial/quick-start): Connect to testnet and send a first transaction. - [**USDT0 behavior**](/en/explanation/usdt0-behavior): Port a contract to Stable without hitting dual-role gotchas. diff --git a/docs/pages/en/explanation/execution.mdx b/docs/pages/en/explanation/execution.mdx index 6fd36fc..4944b75 100755 --- a/docs/pages/en/explanation/execution.mdx +++ b/docs/pages/en/explanation/execution.mdx @@ -6,6 +6,8 @@ diataxis: "explanation" # Execution +Stable executes EVM transactions concurrently with Block-STM while preserving a deterministic final state. Precompiles connect that execution layer to Stable SDK modules. + ## Stable EVM { +stableSystem.on("UnbondingCompleted", (delegator, validator, originBlockHeight, amount, event) => { console.log("Unbonding completed:"); console.log(" Delegator:", delegator); console.log(" Validator:", validator); + console.log(" Origin block:", originBlockHeight.toString()); console.log(" Amount:", ethers.formatEther(amount), "tokens"); console.log(" Block:", event.log.blockNumber); console.log(" Tx Hash:", event.log.transactionHash); }); ``` +```text +Unbonding completed: + Delegator: 0xabcd... + Validator: 0x1234... + Origin block: 36975999 + Amount: 100.0 tokens + Block: 36976000 + Tx Hash: 0x12ab... +``` + ### Filter by user To only receive events for a particular delegator address, use the indexed event parameters to create a filter. @@ -81,14 +97,25 @@ import { stableSystem } from "./config"; const userAddress = "0xabcd..."; const filter = stableSystem.filters.UnbondingCompleted(userAddress); -stableSystem.on(filter, (delegator, validator, amount, event) => { - refreshUserBalance(userAddress); - showNotification( - `Your unbonding of ${ethers.formatEther(amount)} tokens completed!` - ); +stableSystem.on(filter, (delegator, validator, originBlockHeight, amount) => { + console.log("User unbonding completed:", { + delegator, + validator, + originBlockHeight, + amount: ethers.formatEther(amount), + }); }); ``` +```text +User unbonding completed: { + delegator: "0xabcd...", + validator: "0x1234...", + originBlockHeight: 36975999n, + amount: "100.0" +} +``` + ### Filter by validator ```typescript @@ -101,11 +128,25 @@ const validatorFilter = stableSystem.filters.UnbondingCompleted( validatorAddress ); -stableSystem.on(validatorFilter, (delegator, validator, amount) => { - updateValidatorStats(validator, amount); +stableSystem.on(validatorFilter, (delegator, validator, originBlockHeight, amount) => { + console.log("Validator unbonding completed:", { + delegator, + validator, + originBlockHeight, + amount, + }); }); ``` +```text +Validator unbonding completed: { + delegator: "0xabcd...", + validator: "0x1234...", + originBlockHeight: 36975999n, + amount: 100000000000000000000n +} +``` + ### Historical query If your dApp needs to show a history of past unbonding completions, query historical events using event filters with block ranges. @@ -126,6 +167,7 @@ async function getUnbondingHistory( return events.map((event) => ({ delegator: event.args.delegator, validator: event.args.validator, + originBlockHeight: event.args.originBlockHeight, amount: ethers.formatEther(event.args.amount), blockNumber: event.blockNumber, txHash: event.transactionHash, @@ -138,6 +180,21 @@ const history = await getUnbondingHistory( currentBlock - 1000, currentBlock ); + +console.log(history); +``` + +```text +[ + { + delegator: "0xabcd...", + validator: "0x1234...", + originBlockHeight: 36975999n, + amount: "100.0", + blockNumber: 36976000, + txHash: "0x12ab..." + } +] ``` ## Step 3: Handle connection issues @@ -152,8 +209,18 @@ import { STABLE_SYSTEM_ADDRESS, STABLE_SYSTEM_ABI } from "./config"; let reconnectAttempts = 0; const MAX_RECONNECT_ATTEMPTS = 5; -function handleUnbonding(delegator: string, validator: string, amount: bigint) { - console.log("Unbonding completed:", { delegator, validator, amount }); +function handleUnbonding( + delegator: string, + validator: string, + originBlockHeight: bigint, + amount: bigint +) { + console.log("Unbonding completed:", { + delegator, + validator, + originBlockHeight, + amount, + }); } function setupEventListener() { @@ -179,7 +246,11 @@ function setupEventListener() { setupEventListener(); ``` -## Next recommended +```text +No output until an unbonding completes or the provider reports an error. +``` + +## Where to go next - [**System transactions concept**](/en/explanation/system-transactions): Understand how protocol-level events reach the EVM. - [**Staking module concept**](/en/explanation/staking-module): Review the delegation and unbonding flow. diff --git a/docs/pages/en/how-to/upgrade-node.mdx b/docs/pages/en/how-to/upgrade-node.mdx index c05435b..e2f8ef3 100755 --- a/docs/pages/en/how-to/upgrade-node.mdx +++ b/docs/pages/en/how-to/upgrade-node.mdx @@ -1,260 +1,203 @@ --- -title: Upgrade guide -description: "Node upgrade procedures, upgrade types, and rollback strategies for Stable network version changes." +title: "Upgrade a node" +description: "Upgrade a Stable node safely by backing up its identity, replacing release files, and verifying synchronization." diataxis: "how-to" --- -This guide covers the upgrade process for Stable nodes, including upgrade procedures and rollback strategies. +# Upgrade a node -> For complete version history and upgrade details, see [Version History](/en/reference/testnet-version-history). - -## Upgrade types - -### Soft upgrades (non-breaking) -- Can be performed at any time -- Backward compatible - -### Hard upgrades (breaking) -- Requires upgrade at specific height -- Not backward compatible - -### Emergency upgrades -- Critical security fixes -- Immediate action required -- May require chain halt - -## v1.4.0 storage migration - -v1.4.0 replaces the LevelDB-backed state store with MemIAVL. This upgrade requires a data migration in addition to the normal binary replacement. - -Use a local snapshot export and restore unless the network-specific upgrade instructions choose another method. Benchmarking measured 19.4 seconds of average validator downtime for the standard restore and approximately 2.6 seconds for a parallel restore. - -Migrate validators in round-robin order so at least two-thirds of voting power stays online. Configure the RocksDB-backed VersionDB if your node must answer historical queries older than its earliest retained snapshot. +Use this procedure to upgrade a Stable node while preserving its node-specific configuration and validator state. Always take the version, binary, and activation height from the history page for your network. :::warning -Do not use the generic binary-only procedure below for v1.4.0. Wait for the final network-specific binary, upgrade height, backup path, and restore commands in [Network upgrades](/en/reference/network-upgrades). +A state-breaking upgrade requires every node to switch at the coordinated height. Confirm the network, release, and upgrade height before stopping or replacing anything. ::: -## Standard upgrade procedure +## Before you start -### Step 1: preparation +You need: -```bash -# Check current version -stabled version --long +- Shell access to the node and permission to manage its service. +- Enough disk space for a protected backup outside the active data directory. +- The node home, service name, and installed binary path for your deployment. +- The release entry from the [Mainnet version history](/en/reference/mainnet-version-history) or [Testnet version history](/en/reference/testnet-version-history). -# Backup critical data -cp -r ~/.stabled/config ~/stable-backup-$(date +%Y%m%d)/ +The examples below use these paths. Change them to match your deployment: -# For validators only: Backup validator state -cp ~/.stabled/data/priv_validator_state.json ~/stable-backup-$(date +%Y%m%d)/ +```bash +export STABLED_HOME="/var/lib/stabled" +export STABLED_SERVICE="stabled" +export STABLED_BIN="/usr/local/bin/stabled" +export STABLED_ARCH="amd64" # Use arm64 on ARM hosts. +``` -# Check disk space (need 2x current data size) -df -h ~/.stabled +```text +No output. ``` -### Step 2: download new binary +## 1. Check the running node + +Record the current build and synchronization state before changing the node: ```bash -# For v1.2.0-rc1 upgrade (January 22, 2026) -# Choose your architecture: +"$STABLED_BIN" version --long +curl -fsS http://localhost:26657/status \ + | jq '{catching_up: .result.sync_info.catching_up, latest_block_height: .result.sync_info.latest_block_height}' +``` -# Linux AMD64 -BINARY_URL="https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.2.0-rc1-linux-amd64-testnet.tar.gz" +```text + +{ + "catching_up": false, + "latest_block_height": "" +} +``` -# OR Linux ARM64 -BINARY_URL="https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.2.0-rc1-linux-arm64-testnet.tar.gz" +Do not continue until `catching_up` is `false`. -# Download new binary -wget $BINARY_URL +## 2. Back up identity and configuration -# Extract to temporary location -tar -xvzf stabled-1.2.0-rc1-linux-*.tar.gz -C /tmp/ +Keep validator keys and signing state private. Store this backup on encrypted storage with permissions limited to the node operator. -# Verify new version -/tmp/stabled version --long +```bash +export STABLED_BACKUP="/var/backups/stabled/pre-upgrade" +sudo install -d -m 0700 "$STABLED_BACKUP" +sudo cp -a "$STABLED_HOME/config" "$STABLED_BACKUP/config" +sudo cp -a "$STABLED_HOME/data/priv_validator_state.json" \ + "$STABLED_BACKUP/priv_validator_state.json" +sudo cp -a "$STABLED_BIN" "$STABLED_BACKUP/stabled" +printf 'Backup stored at %s\n' "$STABLED_BACKUP" ``` -### Step 3: perform upgrade - -#### For soft upgrades - -```bash -# Stop node -sudo systemctl stop ${SERVICE_NAME} +```text +Backup stored at /var/backups/stabled/pre-upgrade +``` -# Backup current binary -sudo mv /usr/bin/stabled /usr/bin/stabled.backup +:::danger +Never run two validators with the same private validator key. A duplicated key can cause double-signing and slashing. +::: -# Install new binary -sudo mv /tmp/stabled /usr/bin/stabled -sudo chmod +x /usr/bin/stabled +## 3. Download and inspect the release -# Verify installation -stabled version --long +Stable Mainnet activated v1.8.0 at block `36,976,000`. Download the archive for your host architecture and inspect the reported build before installation: -# Start node -sudo systemctl start ${SERVICE_NAME} +```bash +export STABLED_RELEASE="v1.8.0" +export STABLED_ARCHIVE="/tmp/stabled-1.8.0-linux-${STABLED_ARCH}-mainnet.tar.gz" +export STABLED_STAGE="/tmp/stabled-v1.8.0" + +curl -fL \ + "https://stable-data-dist.s3.us-east-1.amazonaws.com/mainnet/binary/stabled-1.8.0-linux-${STABLED_ARCH}-mainnet.tar.gz" \ + -o "$STABLED_ARCHIVE" +mkdir -p "$STABLED_STAGE" +tar -xzf "$STABLED_ARCHIVE" -C "$STABLED_STAGE" +"$STABLED_STAGE/stabled" version --long +``` -# Monitor logs -sudo journalctl -u ${SERVICE_NAME} -f +```text + ``` -#### For hard upgrades +For another release or Testnet, copy the exact binary URL from the corresponding version-history table. -```bash -# Monitor for upgrade height -while true; do - HEIGHT=$(curl -s localhost:26657/status | jq -r '.result.sync_info.latest_block_height') - echo "Current height: $HEIGHT" - if [ $HEIGHT -ge $UPGRADE_HEIGHT ]; then - break - fi - sleep 10 -done - -# Node will halt automatically at upgrade height -# Wait for halt message in logs -sudo journalctl -u ${SERVICE_NAME} -f | grep "UPGRADE" - -# Once halted, perform upgrade -sudo systemctl stop ${SERVICE_NAME} -sudo mv /usr/bin/stabled /usr/bin/stabled.backup -sudo mv /tmp/stabled /usr/bin/stabled - -# Start with new binary -sudo systemctl start ${SERVICE_NAME} -``` +## 4. Prepare the v1.8.0 configuration -### Step 4: post-upgrade verification +v1.8.0 adds required settings to both `config.toml` and `app.toml`. Download the Mainnet templates into a staging directory: ```bash -# Check node status -curl -s localhost:26657/status | jq '.result' - -# Verify version -curl -s localhost:26657/status | jq '.result.node_info.version' +export STABLED_CONFIG_STAGE="/tmp/stable-v1.8.0-config" +mkdir -p "$STABLED_CONFIG_STAGE" +curl -fL \ + "https://stable-data-dist.s3.us-east-1.amazonaws.com/mainnet/configuration/v1.8.0/partners/config.toml" \ + -o "$STABLED_CONFIG_STAGE/config.toml" +curl -fL \ + "https://stable-data-dist.s3.us-east-1.amazonaws.com/mainnet/configuration/v1.8.0/partners/app.toml" \ + -o "$STABLED_CONFIG_STAGE/app.toml" +printf 'Configuration staged at %s\n' "$STABLED_CONFIG_STAGE" +``` -# Check peers -curl -s localhost:26657/net_info | jq '.result.n_peers' +```text +Configuration staged at /tmp/stable-v1.8.0-config +``` -# Monitor sync status -watch -n 2 'curl -s localhost:26657/status | jq ".result.sync_info"' +Start from these templates, then restore every node-specific value from your backup. Check at least: -# Check for errors -sudo journalctl -u ${SERVICE_NAME} --since "10 minutes ago" | grep -i error -``` +- `moniker` and `external_address`. +- Persistent peers, seeds, and private-peer settings. +- API, JSON-RPC, gRPC, and metrics settings. +- Organization-specific timeouts and resource limits. +- Pruning settings for archive nodes. -## Cosmovisor setup (automated upgrades) +The distributed `app.toml` uses default pruning. Pruned history cannot be reconstructed from the local node. v1.8.0 also forces `inter-block-cache` off. -Cosmovisor automates the upgrade process for coordinated upgrades. +## 5. Stop the node and install the files -### Installation +For a coordinated future upgrade, wait until the node halts at the published height. The v1.8.0 Mainnet height is historical, so an older Mainnet node can be stopped before this installation. ```bash -# Install cosmovisor -go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest +sudo systemctl stop "$STABLED_SERVICE" +systemctl is-active "$STABLED_SERVICE" || true +``` -# Or download binary -wget https://github.com/cosmos/cosmos-sdk/releases/download/cosmovisor%2Fv1.7.0/cosmovisor-v1.7.0-linux-amd64.tar.gz -tar -xzf cosmovisor-v1.7.0-linux-amd64.tar.gz -sudo mv cosmovisor /usr/bin/ +```text +inactive ``` -### Configuration +Install the staged binary and the completed configuration files: ```bash -# Set environment variables -cat >> ~/.bashrc < /dev/null < +{ + "catching_up": false, + "latest_block_height": "" +} +``` -```bash -# Stop node -sudo systemctl stop ${SERVICE_NAME} +Check service logs for repeated panics, consensus failures, or configuration parsing errors before returning the node to normal operations. -# Backup current state (in case needed) -cp -r ~/.stabled/data ~/.stabled/data.failed +## Automate future upgrades with Cosmovisor -# Restore from snapshot before upgrade -cd ~/.stabled -rm -rf data/ -tar -I lz4 -xf ~/snapshots/pre-upgrade-snapshot.tar.lz4 +Cosmovisor can switch binaries when the on-chain upgrade handler reaches its configured height. Follow the [Cosmovisor documentation](https://docs.cosmos.network/main/build/tooling/cosmovisor) and use the upgrade name from the applicable governance proposal. -# Restore previous binary -sudo mv /usr/bin/stabled.backup /usr/bin/stabled +Keep automatic binary downloads disabled unless your operating policy explicitly trusts the configured source. Stage and verify release binaries before the activation height. -# Start node -sudo systemctl start ${SERVICE_NAME} -``` +## Roll back only with release-specific instructions -## Emergency procedures +:::danger +Do not delete the active data directory or restore an older snapshot unless Stable's release instructions require it. Starting an old binary against state written by a newer release can corrupt the node or make it follow the wrong chain. +::: -```bash -# If chain halts unexpectedly -# 1. Check Discord for instructions -# 2. Export state at last known good height -stabled export --height > export.json +If the new process fails before it executes an upgraded block, keep the service stopped and inspect the error. Restore the previous binary and configuration only when the release notes say that rollback is safe. -# 3. Wait for coordinated restart instructions -``` +If the node has executed an upgraded block, coordinate recovery with the network operators. Recovery may require a release-specific binary or a trusted snapshot at an agreed height. -## Next steps +## Where to go next -- [Version History](/en/reference/testnet-version-history) - Complete upgrade history and release notes -- [Monitor your node](/en/how-to/monitor-node) after upgrades -- Review [Troubleshooting](/en/how-to/troubleshoot-node) for common issues +- [**Network upgrades**](/en/reference/network-upgrades): Identify the compatibility and operator impact of each protocol release. +- [**Monitor a node**](/en/how-to/monitor-node): Verify synchronization, peers, resource use, and service health after an upgrade. +- [**Troubleshoot a node**](/en/how-to/troubleshoot-node): Diagnose startup, networking, consensus, and storage failures. diff --git a/docs/pages/en/how-to/use-system-modules.mdx b/docs/pages/en/how-to/use-system-modules.mdx index cfd6ec4..fb55bfe 100755 --- a/docs/pages/en/how-to/use-system-modules.mdx +++ b/docs/pages/en/how-to/use-system-modules.mdx @@ -1,14 +1,12 @@ --- title: "Use system modules" -description: "Call Stable's Bank, Distribution, and Staking precompiles from Solidity and ethers.js with minimal ABIs and working examples." +description: "Call Stable's protocol precompiles from Solidity and ethers.js with minimal ABIs and working examples." diataxis: "how-to" --- # Use system modules -Stable exposes protocol-level settlement logic through **precompiled contracts** at fixed addresses. The precompiles let EVM code call Stable SDK modules (staking, reward distribution, STABLE token operations) without re-implementing them. They're significantly more gas efficient than equivalent Solidity implementations because they run at the protocol level. - -This guide shows how to call a precompile from both Solidity and ethers.js, and when to use one over a regular contract. +Stable exposes protocol-level logic through **precompiled contracts** at fixed addresses. You can call these precompiles from Solidity or ethers.js instead of reimplementing Stable SDK behavior in application contracts. :::note **Concept**: For what system modules do and why they're precompiles, see [System modules](/en/explanation/system-modules-overview). For per-module method signatures and events, see the [System modules reference](/en/reference/system-modules-api-overview). @@ -23,9 +21,9 @@ This guide shows how to call a precompile from both Solidity and ethers.js, and | Staking | `0x0000000000000000000000000000000000000800` | Delegation, undelegation, redelegation, validator queries | | Gov | `0x0000000000000000000000000000000000000805` | Proposals, tally results, and on-chain vote records | | Slashing | `0x0000000000000000000000000000000000000806` | Validator signing info and uptime | -| StableSystem | `0x0000000000000000000000000000000000009999` | EVM event emission for system transactions (unbonding completions) | +| StableSystem | `0x0000000000000000000000000000000000009999` | Guaranteed blockspace lane queries and EVM event emission for system transactions | -All of these are callable from any EVM contract or off-chain client. The addresses are stable and identical on mainnet and testnet. +Read methods are callable from any EVM contract or off-chain client. Some state-changing methods enforce caller authorization, and `notifySystemTxLogs()` accepts only protocol-generated system transactions. The addresses are identical on Mainnet and Testnet. ## When to call a precompile vs a regular contract @@ -39,6 +37,7 @@ Precompiles are not a replacement for application contracts. They're a stable in Declare an interface for the methods you need, then call the precompile as if it were a deployed contract. ```solidity +// SAFE: the precompile address is fixed on Stable. // SPDX-License-Identifier: MIT pragma solidity ^0.8.24; @@ -87,10 +86,6 @@ contract StakingHelper { Compile and deploy with Foundry or Hardhat. The precompile address is burned into the contract at the constant slot, so there's nothing to wire up post-deployment. -```solidity -// SAFE: precompile address is fixed on Stable and never changes. -``` - ## Call from ethers.js For off-chain clients, declare the same interface as a minimal ABI and instantiate a contract pointed at the precompile address. @@ -146,13 +141,14 @@ const STABLE_SYSTEM = "0x0000000000000000000000000000000000009999"; const stableSystem = new ethers.Contract( STABLE_SYSTEM, [ - "event UnbondingCompleted(address indexed delegator, address indexed validator, uint256 amount)", + "event UnbondingCompleted(address indexed delegator, address indexed validator, uint64 indexed originBlockHeight, uint256 amount)", ], provider ); -stableSystem.on("UnbondingCompleted", (delegator, validator, amount, event) => { +stableSystem.on("UnbondingCompleted", (delegator, validator, originBlockHeight, amount, event) => { console.log("Unbonding completed for:", delegator); + console.log("Origin block:", originBlockHeight.toString()); console.log("Amount:", ethers.formatEther(amount), "STABLE"); console.log("Tx:", event.log.transactionHash); }); @@ -167,6 +163,7 @@ npx tsx watchUnbonding.ts ```text Listening for UnbondingCompleted events... Unbonding completed for: 0xabcd... +Origin block: 36975999 Amount: 100.0 STABLE Tx: 0x12ab... ``` @@ -182,7 +179,7 @@ Each precompile's full method list, events, and authorization rules live in its - [Staking precompile](/en/reference/staking-module-api): delegate, undelegate, redelegate, validator queries. - [System transactions](/en/reference/system-transactions-api): StableSystem event format and authorization. -## Next recommended +## Where to go next - [**Track unbonding completions**](/en/how-to/track-unbonding): Subscribe to the UnbondingCompleted event emitted via the StableSystem precompile. - [**System modules reference**](/en/reference/system-modules-api-overview): Jump to the per-module ABI, method signatures, and event schemas. diff --git a/docs/pages/en/reference/network-upgrades.mdx b/docs/pages/en/reference/network-upgrades.mdx index cdcb426..5f1fc33 100755 --- a/docs/pages/en/reference/network-upgrades.mdx +++ b/docs/pages/en/reference/network-upgrades.mdx @@ -1,6 +1,6 @@ --- title: "Network upgrades" -description: "Release notes for Stable network protocol versions: what changed in each release and who needs to act." +description: "Identify what changed in each Stable release and whether your node or application needs an update." diataxis: "reference" --- @@ -25,24 +25,24 @@ stabled version ``` ```text -v1.3.1 +v1.8.0 ``` -## v1.4.0 (upcoming) :badge[Testnet]{warning} +## v1.8.0 :badge[Current]{success} -A performance and predictability release, currently live on Testnet as a release candidate and not yet on Mainnet. It groups four changes under two themes: making blocks process faster, and making transaction inclusion more predictable for priority traffic. +A state-machine-breaking Mainnet upgrade activated at block `36,976,000` on August 26, 2026. It groups four changes under two themes: faster block processing and predictable inclusion for priority traffic. | **Initiative** | **Block stage** | **What changes** | **Intended result** | | :--- | :--- | :--- | :--- | | Optimistic parallel execution (OPE) | Execution | Block-STM replaces sequential transaction execution. | Multicore execution, targeting approximately 10,000 TPS. | | Selective RecheckTx | Post-commit mempool recheck | The node rechecks transactions only from accounts changed by the committed block. | Up to twice the sustained throughput in the measured best case, with 31–34% less node CPU use. | | MemIAVL | State persistence | A memory-mapped snapshot and write-ahead log (WAL) replace the LevelDB-backed store. | Write amplification falls from 10–50 times to approximately one write. | -| 2D nonce and guaranteed blockspace | Submission and block proposal | Independent nonce channels combine with reserved per-lane gas capacity. | Deterministic next-block inclusion for eligible VIP transactions. | +| 2D nonce and Enterprise blockspace | Submission and block proposal | Independent nonce channels combine with reserved per-lane gas capacity. | Deterministic next-block inclusion for eligible Enterprise transactions. | These changes address different stages of one block lifecycle: 1. **Submission**: a 2D nonce lets an account submit transactions through independent nonce channels. A stuck transaction on one channel does not block the others. -2. **Proposal**: guaranteed blockspace divides a block into VIP, transaction-type, and normal lanes. Each lane has a reserved gas budget enforced during proposal and validation. +2. **Proposal**: guaranteed blockspace divides a block into Enterprise, transaction-type, and normal lanes. Each lane has a reserved gas budget enforced during proposal and validation. 3. **Execution**: OPE runs transactions concurrently through Block-STM, then validates them against a fixed in-block order. Every node still produces the same state. 4. **Commit**: MemIAVL appends changes to a WAL against one memory-mapped snapshot. This avoids LevelDB compaction and its repeated disk writes. 5. **Post-commit recheck**: Selective RecheckTx uses the block's state-change delta to recheck only affected senders instead of scanning the full mempool. @@ -59,30 +59,38 @@ MemIAVL removes LevelDB from the state-store path. Writes become sequential WAL A 2D nonce gives each account multiple independent nonce channels. `NonceKey` selects the channel. `NonceKey = 0` preserves the normal EVM-compatible sequence, while the protocol reserves the upper half of the `uint64` range for its own use. `MaxUint64` marks an unordered transaction, which uses `TimeoutTimestamp` for replay protection. -The release adds `CustomTx`, transaction type `0x3F`, alongside existing EVM transaction formats. The protocol-reserved `NonceKey` range also identifies VIP-lane transactions. +The release adds `CustomTx`, transaction type `0x3F`, alongside existing EVM transaction formats. A `NonceKey` with bit 63 set identifies Enterprise-lane transactions, except `MaxUint64`. -Guaranteed blockspace divides each block into VIP, transaction-type, and normal lanes with separate gas quotas. Governance controls the lane parameters through one `MsgUpdateParams` proposal, and an accepted update takes effect in the next block. With no lane configuration, the chain behaves as one normal lane. +Guaranteed blockspace divides each block into Enterprise, transaction-type, and normal lanes with separate gas quotas. Governance controls the lane parameters through one `MsgUpdateParams` proposal, and an accepted update takes effect in the next block. -Eligible VIP transactions receive deterministic next-block inclusion when validators behave honestly and the network remains synchronous. Read [Guaranteed blockspace](/en/explanation/guaranteed-blockspace) for the lane and nonce model. +The Mainnet activation seeded `max_blockspace_gas_weight = 20` and one Enterprise lane with weight `50`. It did not seed a transaction-type lane. Eligible Enterprise transactions receive deterministic next-block inclusion when validators behave honestly and the network remains synchronous. -### Node rollout +The `StableSystem` precompile now exposes `blockspaceLanes()`. Any client can query the active lane registry through `eth_call` and reproduce the protocol's classification rules. -MemIAVL changes the state store, so node operators must migrate their existing data. The recommended method is a local snapshot export and restore. Benchmarks measured an average of 19.4 seconds of downtime per validator. A parallel restore variant reduced that average to approximately 2.6 seconds. +Read [Guaranteed blockspace](/en/explanation/guaranteed-blockspace) for the lane model or the [StableSystem reference](/en/reference/system-transactions-api) for the query ABI. -Validators can migrate in round-robin order to preserve at least two-thirds of voting power. Follow the network-specific upgrade instructions rather than treating the benchmark procedure as a fixed runbook. +### Activation and node configuration -### Deferred work +The v1.8.0 handler runs module migrations, enables the NonceKey precompile, installs EIP-2935 history storage, and sets `max_gas_per_tx` to `40,000,000`. -- **Gas-waiving transaction-type lane**: a zero-gas lane needs trusted mempool admission control. Without it, an attacker could submit unlimited free transactions. -- **Sender-matching optimization**: a later release may let full nodes send precomputed sender addresses with transactions, avoiding repeated signature recovery during block proposal. +The release adds configuration keys to both `config.toml` and `app.toml`. Operators had to install the v1.8.0 templates before activation, then restore their node-specific settings. No state export, import, or snapshot reset was required for the documented Mainnet upgrade. -:::note -v1.4.0 is still in audit and testing. Scope and timing may change before the Mainnet upgrade. Track the [Testnet version history](/en/reference/testnet-version-history) for the latest release candidate. -::: +The binary forces `inter-block-cache` off. Archive-node operators must restore their original pruning settings after installing the default `app.toml` template. -## v1.3.1 :badge[Current]{success} +### Reliability and security changes -A backward-compatible patch and the current Mainnet version. It ships with no coordinated upgrade height, so node operators can adopt it by replacing the binary at any time. +- Nonces are checked against finalized state, closing cross-block transaction replay. +- Proposal processing enforces lane budgets and the per-transaction gas cap at admission and consensus. +- Sequential and Block-STM execution now produce the same cumulative EVM log indices and `LastResultsHash`. +- JSON-RPC applies limits to expensive requests, WebSocket subscriptions, proof storage keys, and trace output. +- Streamed block results and `BlockResultsForLogs` bound memory use during large log queries. +- MemIAVL and VersionDB fail closed on version gaps and recover safely from interrupted WAL or snapshot writes. + +**Who needs to act:** nodes joining or upgrading after activation must use the v1.8.0 binary and configuration templates. Follow [Upgrade a node](/en/how-to/upgrade-node) and confirm the current binary in the [Mainnet version history](/en/reference/mainnet-version-history). + +## v1.3.1 + +A backward-compatible patch. It shipped with no coordinated upgrade height, so node operators could adopt it by replacing the binary at any time. ## v1.3.0 diff --git a/docs/pages/en/reference/system-transactions-api.mdx b/docs/pages/en/reference/system-transactions-api.mdx index 14ee7e0..a8f5d4c 100755 --- a/docs/pages/en/reference/system-transactions-api.mdx +++ b/docs/pages/en/reference/system-transactions-api.mdx @@ -1,358 +1,177 @@ --- title: "System transactions reference" -description: "StableSystem precompile reference: interface, sender authorization, batch limits, and gas accounting." +description: "Query guaranteed blockspace lanes and consume protocol events through the StableSystem precompile." diataxis: "reference" --- # System transactions reference +The `StableSystem` precompile exposes Stable protocol data and events through a fixed EVM contract interface. In v1.8.0, any client can query the guaranteed blockspace registry, while only protocol-generated transactions can emit system logs. + :::note -**Concept:** For how system transactions bridge SDK events to the EVM and why this matters, see [System transactions](/en/explanation/system-transactions). +For the system-transaction flow and its security model, see [System transactions](/en/explanation/system-transactions). ::: -## Abstract - -System transactions provide a way for the Stable protocol to emit EVM events for Stable SDK operations. When staking events like unbonding completions occur in the SDK layer, the protocol automatically generates EVM transactions that emit corresponding events. This makes these operations fully visible to EVM tooling and applications. - -## Motivation - -You and your applications on Stable expect to monitor blockchain events through standard EVM interfaces like `eth_getLogs`. But critical operations happen in Stable SDK modules that don't naturally emit EVM events. This creates a visibility gap: EVM dApps can't easily track when a user's tokens finish unbonding. - -System transactions bridge this gap. When the staking module completes an unbonding operation, Stable's x/stable module detects the event and generates a system transaction that calls the StableSystem precompile ( `0x0000000000000000000000000000000000009999`). And then, the precompile emits proper EVM events that any dApp can subscribe to. System transactions run with a special sender address (`0x8888888888888888888888888888888888888888`) that only the protocol can use. This prevents anyone from spoofing protocol events while keeping the event emission trustless and verifiable on-chain. - -## Specification +## Contract -System transactions work through three main components: the x/stable module's EndBlocker, the PrepareProposal handler, and the StableSystem precompile. +The precompile uses the same address on Mainnet and Testnet: -### Architecture overview +`0x0000000000000000000000000000000000009999` -system-transaction-architecture +| **Method** | **Selector** | **Access** | **Gas limit** | **Purpose** | +| :--- | :--- | :--- | :--- | :--- | +| `blockspaceLanes()` | `0x2c0ac3be` | Anyone, read-only | `10,000` | Return the active Enterprise and transaction-type lane registry. | +| `notifySystemTxLogs()` | `0xe8e983b7` | System transaction sender only | `50,000` | Process up to 100 queued system log entries. | -### StableSystem precompile - -The StableSystem precompile lives at `0x0000000000000000000000000000000000009999` and handles protocol-level operations that need to emit EVM events. Currently it supports unbonding completion notifications. +Use this Solidity interface for the v1.8.0 ABI: ```solidity -interface IStableSystem { - /// @notice Processes queued unbonding completions and emits EVM events - /// @param blockHeight The block height at which to process completions - /// @dev Only callable by system transactions (from = 0x8888888888888888888888888888888888888888) - /// @dev Processes up to 100 completions per call - /// @dev Automatically deletes processed completions from the queue - function notifyUnbondingCompletions(int64 blockHeight) external; - - /// @notice Emitted when an unbonding operation completes - /// @param delegator The address that delegated the tokens - /// @param validator The validator address the tokens were delegated to - /// @param amount The amount of tokens that finished unbonding (in uusdc) - event UnbondingCompleted( - address indexed delegator, - address indexed validator, - uint256 amount - ); - - /// @notice The caller is not authorized (not system transaction sender) - error Unauthorized(); +// SAFE: This interface matches the Stable v1.8.0 StableSystem ABI. +struct EnterpriseLane { + uint64 id; + string name; + uint32 weight; } -``` - -### System transaction sender - -System transactions use `0x8888888888888888888888888888888888888888` as the sender address. This address: - -- Requires no signature verification -- Can only be used by transactions created in PrepareProposal -- Cannot be spoofed by users or contracts -- Skips fee deduction via the SystemTxDecorator ante handler - -The EVM recognizes system transactions by checking `msg.sender == 0x8888888888888888888888888888888888888888`. Precompiles can use this to gate protocol-only operations. - -### Event-driven flow - -When a user's unbonding period completes, here's what happens: - -1. **Stable SDK Layer:** The staking module's EndBlocker completes the unbonding and emits EventTypeCompleteUnbonding with the delegator address, validator address, and amount. -2. **Detection:** The x/stable module's EndBlocker runs after staking and scans for unbonding events in the block's event log. For each completion, it queues an entry in state with the delegator address, validator address, amount, and block height. -3. **System TX Generation**: In the next block's PrepareProposal, the app queries all queued completions. If any exist, it creates a system transaction calling StableSystem.notifyUnbondingCompletions(blockHeight) with the current block height. This transaction goes at the front of the block, before any user transactions. -4. **Execution:** During block execution, the system transaction runs first. The precompile queries state for queued completions at that block height, emits an UnbondingCompleted event for each one (up to 100), and deletes them from the queue. -5. **EVM Visibility:** The events appear in transaction receipts and logs, visible to eth\_getLogs queries, block explorers, and any application monitoring the StableSystem precompile. - -### Batch processing -To prevent blocks from becoming too large, the system processes at most 100 unbonding completions per block. If 150 completions queue up: - -- Block N: Creates system tx processing completions 0-99 -- Block N+1: Creates system tx processing completions 100-149 - -The precompile queries state directly rather than receiving completion data in calldata. This keeps transaction size predictable and moves the data from expensive calldata to cheaper state reads. - -## Usage examples - -The most common use case is a staking dashboard that needs to notify users when their unbonding periods complete. Here's how to set up a listener for unbonding completions. - -```javascript -import { ethers } from 'ethers'; - -// StableSystem precompile address -const STABLE_SYSTEM_ADDRESS = '0x0000000000000000000000000000000000009999'; - -// ABI for the UnbondingCompleted event -const STABLE_SYSTEM_ABI = [ - 'event UnbondingCompleted(address indexed delegator, address indexed validator, uint256 amount)' -]; - -// Connect to the Stable network -const provider = new ethers.JsonRpcProvider('https://rpc.testnet.stable.xyz'); -const stableSystem = new ethers.Contract( - STABLE_SYSTEM_ADDRESS, - STABLE_SYSTEM_ABI, - provider -); - -// Subscribe to all unbonding completions -stableSystem.on('UnbondingCompleted', (delegator, validator, amount, event) => { - console.log('Unbonding completed!'); - console.log('Delegator:', delegator); - console.log('Validator:', validator); - console.log('Amount:', ethers.formatEther(amount), 'tokens'); - console.log('Block:', event.log.blockNumber); - console.log('Tx Hash:', event.log.transactionHash); -}); - -``` - -This listener fires every time any user's unbonding completes. For a production dApp, filter events for specific users as shown below. - -### Filtering events for specific users - -To only receive events for a particular delegator address, use the indexed event parameters to create a filter: - -```javascript -// Only watch unbondings for a specific user -const userAddress = '0xabcd...'; - -const filter = stableSystem.filters.UnbondingCompleted(userAddress); - -stableSystem.on(filter, (delegator, validator, amount, event) => { - // This only fires for the specified user's unbondings - showNotification(`Your unbonding of ${ethers.formatEther(amount)} tokens completed!`); - refreshUserBalance(userAddress); -}); -``` - -You can also filter by validator if you're building a validator-specific dashboard: - -```javascript -// Watch all unbondings from a specific validator -const validatorAddress = '0x1234...'; - -const validatorFilter = stableSystem.filters.UnbondingCompleted(null, validatorAddress); - -stableSystem.on(validatorFilter, (delegator, validator, amount) => { - updateValidatorStats(validator, amount); -}); -``` - -### Querying historical events - -If your dApp needs to show a history of past unbonding completions, you can query historical events using event filters with block ranges: - -```javascript -// Get all unbondings for a user in the last 1000 blocks -const currentBlock = await provider.getBlockNumber(); -const filter = stableSystem.filters.UnbondingCompleted(userAddress); - -const events = await stableSystem.queryFilter( - filter, - currentBlock - 1000, - currentBlock -); - -const unbondingHistory = events.map(event => ({ - delegator: event.args.delegator, - validator: event.args.validator, - amount: ethers.formatEther(event.args.amount), - blockNumber: event.blockNumber, - txHash: event.transactionHash -})); - -console.log('Recent unbondings:', unbondingHistory); - -``` - -## Integration guide - -### Step 1: Add the Stable System contract interface +struct TxTypeLane { + uint64 id; + string name; + address[] toAddrs; + bytes4[] methods; + uint8[] txTypes; + uint64[] nonceKeys; + address[] senders; + uint32 weight; + bool noOverflow; +} -First, add the StableSystem precompile interface to your project. If you're using Foundry or Hardhat, create a new interface file: +struct BlockspaceLanes { + uint32 maxBlockspaceGasWeight; + EnterpriseLane[] enterpriseLanes; + TxTypeLane[] txTypeLanes; +} -```solidity interface IStableSystem { event UnbondingCompleted( address indexed delegator, address indexed validator, + uint64 indexed originBlockHeight, uint256 amount ); -} -``` - -If you're building a pure frontend dApp without Solidity contracts, you just need the ABI fragment for the event: - -```javascript -const STABLE_SYSTEM_ABI = [ - 'event UnbondingCompleted(address indexed delegator, address indexed validator, uint256 amount)' -]; -``` - -### Step 2: Set up event listeners - -Initialize your ethers.js provider and create a contract instance pointing to the StableSystem precompile address. The precompile is always deployed at `0x00000000000....0000009999` on both Stable Testnet and Stable Mainnet. - -*Note: The precompile is not deployed on Stable Mainnet yet, it will be provided after v1.2.0 upgrade.* - -```javascript -const provider = new ethers.JsonRpcProvider(RPC_URL); -const stableSystem = new ethers.Contract( - '0x0000000000000000000000000000000000009999', - STABLE_SYSTEM_ABI, - provider -); -``` -### Step 3: Handle events in your application logic + function notifySystemTxLogs() external; -Subscribe to events and update your application state accordingly. Common patterns include: - -- **Balance Updates**: When an unbonding completes, refresh the user's token balance -- **Notification System**: Show toast notifications when the user's unbondings complete -- **Dashboard Statistics**: Update staking metrics and charts in real-time -- **Transaction History**: Add completed unbondings to the user's activity feed - -### Step 4: Handle connection issues - -Since event subscriptions rely on persistent websocket connections, implement reconnection logic for production dApps: - -```javascript -let reconnectAttempts = 0; -const MAX_RECONNECT_ATTEMPTS = 5; - -function setupEventListener() { - const provider = new ethers.WebSocketProvider('wss://rpc.testnet.stable.xyz'); - - provider.on('error', (error) => { - console.error('Provider error:', error); - if (reconnectAttempts < MAX_RECONNECT_ATTEMPTS) { - reconnectAttempts++; - setTimeout(() => setupEventListener(), 5000); - } - }); - - const stableSystem = new ethers.Contract( - '0x0000000000000000000000000000000000009999', - STABLE_SYSTEM_ABI, - provider - ); - - stableSystem.on('UnbondingCompleted', handleUnbonding); + function blockspaceLanes() + external + view + returns (BlockspaceLanes memory lanes); } ``` -## Why this approach? - -### Compared to custom indexers - -Previously, Stable SDK required you to run custom indexers that watch for SDK events and store them in a database. This adds operational overhead and introduces potential points of failure. - -With system transactions, there's no need for separate indexer infrastructure. Events are natively available through the EVM's log system, which every RPC node already indexes and serves. Any standard web3 library can subscribe to these events without additional tooling. +## `blockspaceLanes()` -### Compared to polling SDK endpoints +`blockspaceLanes()` returns the governance-controlled lane registry used during block proposal and validation. It is a normal `eth_call`, not a custom JSON-RPC method, and it does not require an Enterprise gateway. -Without system transactions, EVM dApps would need to periodically call Stable SDK REST endpoints to check if unbonding periods have completed. This creates several problems: +Both lane arrays are sorted by `id` in ascending order. Lower IDs have higher match priority. -- **Increased latency**: Polling intervals of 5-10 seconds mean users might wait that long before seeing updates -- **Higher load**: Every dApp instance polling endpoints increases load on RPC infrastructure -- **Complexity**: dApps need to handle both web3 providers (for EVM interactions) and Stable SDK REST clients (for SDK queries) -- **No real-time updates**: Polling inherently can't provide instant notifications +### Return value -System transactions provide real-time event notifications through the same websocket connections dApps already use for EVM interactions. This simplifies the developer experience and reduces infrastructure costs. +| **Field** | **Type** | **Description** | +| :--- | :--- | :--- | +| `maxBlockspaceGasWeight` | `uint32` | Percentage from 0 to 100 of the block gas limit reserved across all configured lanes. | +| `enterpriseLanes` | `EnterpriseLane[]` | Enterprise lane definitions. Governance allows at most one Enterprise lane. | +| `txTypeLanes` | `TxTypeLane[]` | Lanes whose match rules inspect transaction fields. | -## Security guarantees +### Enterprise lane -### Trustless event emission +Any `CustomTx` whose `NonceKey` has bit 63 set routes to the configured Enterprise lane, except `MaxUint64`. The lower 63 bits select an independent nonce channel, not a lane. -System transactions are created during the `PrepareProposal` ABCI phase, which only validators can execute. User-submitted transactions cannot spoof the system sender address (`0x8888888888888888888888888888888888888888`). The EVM's state transition logic enforces that only transactions to the StableSystem precompile address can skip signature verification. +| **Field** | **Type** | **Description** | +| :--- | :--- | :--- | +| `id` | `uint64` | Drain-order priority and identifier. | +| `name` | `string` | Human-readable lane name. | +| `weight` | `uint32` | Percentage from 0 to 100 of the reserved blockspace pool assigned to the lane. | -This means: +### Transaction-type lanes -- Users cannot forge unbonding completion events -- Users cannot call `notifyUnbondingCompletions` from their own transactions -- The only way to emit an `UnbondingCompleted` event is for an actual unbonding to complete in the Stable SDK staking module +A transaction must match every populated matcher field. Entries within one field are alternatives, and an empty matcher is a wildcard. -### No additional trust assumptions +| **Field** | **Type** | **Description** | +| :--- | :--- | :--- | +| `id` | `uint64` | Lane priority and identifier. Lower IDs match first. | +| `name` | `string` | Human-readable lane name. | +| `toAddrs` | `address[]` | Allowed destination addresses. Empty matches any destination. | +| `methods` | `bytes4[]` | Allowed four-byte function selectors. Empty matches any selector. | +| `txTypes` | `uint8[]` | Allowed transaction formats. Empty or an entry of `0` matches any format. | +| `nonceKeys` | `uint64[]` | Allowed nonce keys. Empty or an entry of `0` matches any key. | +| `senders` | `address[]` | Allowed sender addresses. Empty matches any sender. | +| `weight` | `uint32` | Percentage from 0 to 100 of the reserved blockspace pool assigned to the lane. | +| `noOverflow` | `bool` | When `true`, unused capacity does not cascade to later lanes. | -System transactions don't introduce new security assumptions beyond what's already required for blockchain consensus. If you trust that validators are correctly executing blocks, you can trust that system transaction events accurately reflect Stable SDK state changes. +`txTypes` uses these `TxFormat` values: -The event emission process is deterministic: given the same SDK events in `EndBlock`, all honest validators will produce identical system transactions during `PrepareProposal`. The consensus mechanism ensures validators agree on which system transactions to include. +| **Value** | **Transaction format** | **EVM type** | +| :--- | :--- | :--- | +| `0` | Wildcard | Any | +| `1` | Legacy | `0x00` | +| `2` | Access list | `0x01` | +| `3` | Dynamic fee | `0x02` | +| `4` | Set code | `0x04` | +| `5` | Two-dimensional nonce | `0x3F` | -### Block finality +### Query the registry -The Stable blockchain uses fast finality through StableBFT's consensus mechanism. Once a block is committed, it's immediately final and cannot be reorganized. This means that once you receive an `UnbondingCompleted` event, you can trust it's permanent. +Call the precompile with Foundry's `cast` command: -There's no need to wait for multiple confirmations like on probabilistic finality chains. dApps can update user balances and display notifications immediately upon receiving the event. - -## Performance & limitations - -### Batch size constraints - -Each block processes at most 100 unbonding completions through system transactions. This limit exists to prevent unbounded block sizes during periods of high unbonding activity. - -In practice, 100 completions per block provides throughput of \~9000 completions per minute assuming the average block time of 0.7 seconds. Normal staking activity rarely reaches this limit. During exceptional circumstances, completions might queue for several blocks before fully processing. - -### Gas consumption - -System transactions consume gas during execution, which is accounted for in the block's gas limit. The gas cost scales linearly with the number of completions being processed: - -- Base function call: \~21,000 gas -- Per-event emission: \~3,000 gas -- Reading state: \~2,000 gas per completion - -A full batch of 100 completions consumes approximately 521,000 gas. As Stable’s block gas limit is 100,000,000, this represents less than 0.6% of available block space. - -### Notification latency +```bash +cast call \ + 0x0000000000000000000000000000000000009999 \ + "blockspaceLanes()((uint32,(uint64,string,uint32)[],(uint64,string,address[],bytes4[],uint8[],uint64[],address[],uint32,bool)[]))" \ + --rpc-url https://rpc.stable.xyz +``` -When an unbonding period completes during block N: +The v1.8.0 Mainnet activation seeded a 20% reserved pool and one Enterprise lane with 50% of that pool. Governance can change this output. -1. The Stable module's `EndBlock` queues the completion in block N's state -2. Block N+1's `PrepareProposal` creates a system transaction -3. The system transaction executes during block N+1, emitting the event +```text +(20, [(1, "enterprise", 50)], []) +``` -This means there's a one-block delay (approximately 0.7 seconds) between the unbonding completing and the EVM event being emitted. For most use cases, this latency is acceptable since the unbonding period itself is 7 days. +## `notifySystemTxLogs()` -### High load scenarios +`notifySystemTxLogs()` reads queued protocol log entries from state and processes up to 100 per call. It takes no arguments and returns no value. -If unbonding completions arrive faster than 100 per block, they accumulate in the queue. The queue is processed in FIFO order, so the oldest completions are always notified first. +Only a system transaction with sender `0x0000000000000000000000000000000000000001` can call this method. Calls from users or contracts revert. -During sustained high load, the queue could grow temporarily. However, once the spike subsides, subsequent blocks with fewer completions will gradually drain the queue. The system is designed to handle bursts without dropping events. +When an unbonding completes, the flow is: -## Future extensions +1. The staking module completes the operation and records its SDK event. +2. The `x/stable` module queues the event data and its original block height. +3. The next block proposer creates a system transaction that calls `notifySystemTxLogs()`. +4. The precompile emits EVM logs for up to 100 queued entries. +5. Clients read the logs with `eth_getLogs`, a WebSocket subscription, or a block explorer. -The system transaction mechanism provides a general pattern for bridging any Stable SDK operation into the EVM event space. While currently used only for unbonding completions, the architecture can be extended to cover additional use cases: +Entries above the batch limit stay queued for a later block. -### Staking operations +## `UnbondingCompleted` event -Beyond unbonding, other staking events could emit EVM notifications: +| **Parameter** | **Type** | **Indexed** | **Description** | +| :--- | :--- | :--- | :--- | +| `delegator` | `address` | Yes | Address whose delegated tokens finished unbonding. | +| `validator` | `address` | Yes | Validator address derived from its validator-operator address. | +| `originBlockHeight` | `uint64` | Yes | Block height at which the SDK-layer unbonding originally completed. | +| `amount` | `uint256` | No | Amount that finished unbonding. | -- Commission rate changes by validators -- Validator jailing and unjailing +The EVM log appears in the block containing the system transaction. Use `originBlockHeight` when you need the height of the original SDK event. -### Governance execution +## Security model -When governance proposals pass and execute, system transactions could emit events with proposal IDs and execution results. This would allow dApps to react to parameter changes or upgrades without polling the governance module. +- The protocol creates system transactions during block proposal. +- EVM state-transition rules reserve sender `0x0000000000000000000000000000000000000001` for system transactions. +- User transactions cannot forge the sender or call `notifySystemTxLogs()` successfully. +- `blockspaceLanes()` is intentionally public and cannot change state. -### Generic event bridge +## Where to go next -The pattern could be generalized into a configurable event bridge where each module registers which SDK events should be mirrored to the EVM. This would provide comprehensive visibility into all Stable SDK operations without requiring per-module custom logic. The key architectural principle is that system transactions remain a protocol-level feature, created only by validators during block proposal. +- [**Guaranteed blockspace**](/en/explanation/guaranteed-blockspace): Understand how the returned weights and matchers control reserved capacity. +- [**Track unbonding completions**](/en/how-to/track-unbonding): Subscribe to `UnbondingCompleted` and query historical events. +- [**System transactions**](/en/explanation/system-transactions): Understand how protocol events become EVM logs. diff --git a/docs/pages/en/reference/testnet-version-history.mdx b/docs/pages/en/reference/testnet-version-history.mdx index 050f565..a341ad1 100755 --- a/docs/pages/en/reference/testnet-version-history.mdx +++ b/docs/pages/en/reference/testnet-version-history.mdx @@ -1,28 +1,29 @@ --- title: Version history -description: "Version history and upgrade schedule for the Stable Testnet network." +description: "Find Stable Testnet releases, upgrade heights, commits, and downloadable node binaries." diataxis: "reference" --- # Version history -Complete version history and related documentation for the Stable Testnet. +Stable Testnet currently runs `v1.8.0-rc1`. Use this history to identify each release, its activation height, and its node binaries. ## Current version information -- **Current Version**: `v1.8.0-rc1` -- **Next Upgrade**: `TBD` -- **Upgrade Height**: `TBD` -- **Expected Time**: `TBD` +- **Current version**: `v1.8.0-rc1` +- **Next upgrade**: `TBD` +- **Upgrade height**: `TBD` +- **Expected time**: `TBD` ## Version history -### Current & previous versions +### Current and previous versions -| Version | Commit | Upgrade Height | Binary | Status | -|---------|--------|----------------|--------|-------------------------------| +| **Version** | **Commit** | **Upgrade height** | **Binary** | **Status** | +| :--- | :--- | :--- | :--- | :--- | | **v1.8.0-rc1** | `a07c551` | 64,956,000 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.8.0-rc1-linux-amd64-testnet.tar.gz) / [ARM64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.8.0-rc1-linux-arm64-testnet.tar.gz) | Current | | **v1.8.0-rc0** | `4cc6813` | 61,689,000 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.8.0-rc0-linux-amd64-testnet.tar.gz) / [ARM64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.8.0-rc0-linux-arm64-testnet.tar.gz) | | +| **v1.4.0-rc2** | `75c2934` | 60,110,000 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.4.0-rc2-linux-amd64-testnet.tar.gz) / [ARM64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.4.0-rc2-linux-arm64-testnet.tar.gz) | | | **v1.4.0-rc1** | `4744d2d` | 58,520,000 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.4.0-rc1-linux-amd64-testnet.tar.gz) / [ARM64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.4.0-rc1-linux-arm64-testnet.tar.gz) | | | **v1.4.0-rc0** | `83b5efb` | 57,806,500 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.4.0-rc0-linux-amd64-testnet.tar.gz) / [ARM64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.4.0-rc0-linux-arm64-testnet.tar.gz) | | | **v1.3.1-rc0** | `75bb546` | - | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.3.1-rc0-linux-amd64-testnet.tar.gz) / [ARM64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.3.1-rc0-linux-arm64-testnet.tar.gz) | | @@ -46,7 +47,7 @@ Complete version history and related documentation for the Stable Testnet. | **v0.2.0** | `8bdd771` | 8,956,584 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.2.0-linux-amd64-testnet.tar.gz) | Feature update | | **v0.1.0** | `10dfg542` | Genesis | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.1.0-linux-amd64-testnet.tar.gz) | Genesis (2025-04-07) | -## Related documentation +## Where to go next -- [Upgrade Guide](/en/how-to/upgrade-node) - Step-by-step upgrade procedures -- [Testnet Information](/en/reference/testnet-information) - Current network details +- [**Upgrade a node**](/en/how-to/upgrade-node): Replace the node binary and configuration files for a coordinated network upgrade. +- [**Testnet information**](/en/reference/testnet-information): Connect to Stable Testnet with its current chain ID, endpoints, and contract addresses. From 34b7210111218547f2c2256f71d43b2e7d1daf6d Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sat, 5 Sep 2026 02:35:50 +0000 Subject: [PATCH 2/2] i18n: auto-translate cn/ko for changed en content --- docs/pages/cn/explanation/core-concepts.mdx | 55 +-- docs/pages/cn/explanation/execution.mdx | 80 ++-- .../cn/explanation/guaranteed-blockspace.mdx | 67 +-- docs/pages/cn/explanation/stable-db.mdx | 70 +-- docs/pages/cn/explanation/staking-module.mdx | 46 +- .../explanation/system-modules-overview.mdx | 32 +- .../cn/explanation/system-transactions.mdx | 60 +-- docs/pages/cn/explanation/tech-overview.mdx | 65 ++- .../cn/explanation/technical-roadmap.mdx | 54 +-- docs/pages/cn/how-to/track-unbonding.mdx | 143 ++++-- docs/pages/cn/how-to/upgrade-node.mdx | 333 ++++++-------- docs/pages/cn/how-to/use-system-modules.mdx | 75 ++-- docs/pages/cn/reference/network-upgrades.mdx | 140 +++--- .../cn/reference/system-transactions-api.mdx | 415 +++++------------ .../cn/reference/testnet-version-history.mdx | 25 +- docs/pages/ko/explanation/core-concepts.mdx | 65 +-- docs/pages/ko/explanation/execution.mdx | 80 ++-- .../ko/explanation/guaranteed-blockspace.mdx | 59 +-- docs/pages/ko/explanation/stable-db.mdx | 64 +-- docs/pages/ko/explanation/staking-module.mdx | 40 +- .../explanation/system-modules-overview.mdx | 36 +- .../ko/explanation/system-transactions.mdx | 60 +-- docs/pages/ko/explanation/tech-overview.mdx | 44 +- .../ko/explanation/technical-roadmap.mdx | 54 +-- docs/pages/ko/how-to/track-unbonding.mdx | 125 ++++-- docs/pages/ko/how-to/upgrade-node.mdx | 331 ++++++-------- docs/pages/ko/how-to/use-system-modules.mdx | 71 ++- docs/pages/ko/reference/network-upgrades.mdx | 142 +++++- .../ko/reference/system-transactions-api.mdx | 419 +++++------------- .../ko/reference/testnet-version-history.mdx | 23 +- 30 files changed, 1566 insertions(+), 1707 deletions(-) diff --git a/docs/pages/cn/explanation/core-concepts.mdx b/docs/pages/cn/explanation/core-concepts.mdx index b733a00..a7ce96a 100755 --- a/docs/pages/cn/explanation/core-concepts.mdx +++ b/docs/pages/cn/explanation/core-concepts.mdx @@ -1,58 +1,59 @@ --- source_path: explanation/core-concepts.mdx -source_sha: 45b22f6b8de51a67dbe1ed9ffb14d57302775f8c +source_sha: 8af8d2892f4a217e2908aacda0f16699f1a4bc63 title: "核心概念" -description: "在构建之前，请先了解 Stable 的四个核心概念：USDT0 作为燃料、有保障的区块空间、转账聚合和 EVM 兼容性。" +description: "在构建之前了解 Stable 的四个核心概念：USDT0 作为燃料、保障区块空间、转账聚合和 EVM 兼容性。" diataxis: "explanation" --- # 核心概念 -掌握四个概念即可开始构建。每个部分都定义了概念，展示了它的作用，并链接到完整的参考资料。 +掌握四个概念即可开始构建。每个部分都定义了概念，展示了其工作原理，并提供了完整参考的链接。 ## USDT0 作为燃料 -您使用 USDT0 支付交易费用，这是您已经持有并正在交易的资产。无需资助或管理第二种代币。 +您使用 USDT0 支付交易费用，USDT0 是您已持有并进行交易的同一资产。无需为第二个代币注资或管理。 -USDT0 既是原生燃料资产（18 位小数，通过 `address(x).balance` 读取），也是 ERC-20 代币（6 位小数，通过 `USDT0.balanceOf(x)` 读取）。这两个接口操作相同的底层余额，协议会自动调和 12 位小数的精度差距。 +USDT0 既是原生燃料资产（18 位小数，通过 `address(x).balance` 读取），也是 ERC-20 代币（6 位小数，通过 `USDT0.balanceOf(x)` 读取）。两个接口操作的是同一个底层余额，协议会自动调和 12 位小数的精度差。 ```solidity -// 两者读取相同的余额： +// SAFE: 两次读取都使用 Stable 的规范余额接口。 +// 两者读取的是相同的余额： uint256 native = address(user).balance; // 18 decimals uint256 erc20 = IERC20(USDT0).balanceOf(user); // 6 decimals ``` :::warning -余额调和会在储备金地址 `0x5113954bbC0eD721F1C68671EBa3d91e9e9bF7b5` 发出额外的 `Transfer` 事件。重放 `Transfer` 事件的索引器必须过滤进出该地址的转账，否则它们将无声地重复计算余额。 +余额调和会在储备地址 `0x5113954bbC0eD721F1C68671EBa3d91e9e9bF7b5` 发出额外的 `Transfer` 事件。重放 `Transfer` 事件的索引器必须过滤进出此地址的转账，否则会悄无声息地重复计算余额。 ::: -阅读更多：[USDT0 作为燃料](/cn/explanation/usdt-as-gas-token) · [USDT0 在 Stable 上的行为](/cn/explanation/usdt0-behavior)。 +了解更多：[USDT0 作为燃料](/cn/explanation/usdt-as-gas-token) · [Stable 上的 USDT0 行为](/cn/explanation/usdt0-behavior)。 -## 有保障的区块空间 +## 保障区块空间 -Stable v1.4.0 可以为符合条件的优先工作负载在每个区块内预留燃气配额。在网络拥堵期间，普通流量无法消耗此 VIP 通道容量。 +Stable v1.8.0 在每个区块内为符合条件的优先级工作负载预留了燃料配额。正常流量在拥堵期间无法占用此企业级通道容量。 -标准 EVM 交易继续使用默认的 nonce 通道，即 `NonceKey = 0`。符合条件的优先流使用 `CustomTx` 类型 `0x3F` 和协议预留的 `NonceKey`，用以识别 VIP 通道。 +标准 EVM 交易继续使用默认的 Nonce 通道，`NonceKey = 0`。符合条件的优先级流使用 `CustomTx` 类型 `0x3F` 和 `NonceKey` 并设置第 63 位。 -治理层配置这些通道和配额。如果没有配置，每个交易都使用一个普通通道。该功能目前处于 v1.4.0 Testnet 发布候选版本中，其主网计划待定。 +治理配置了通道和配额。保障区块空间已在主网和测试网中上线，`StableSystem.blockspaceLanes()` 返回活动配置。 -阅读更多：[有保障的区块空间](/cn/explanation/guaranteed-blockspace)。 +了解更多：[保障区块空间](/cn/explanation/guaranteed-blockspace)。 ## USDT 转账聚合器 -大批量的 USDT0 转账通过 MapReduce 启发的管道并行批处理和验证。每个账户的失败是隔离的，因此一个不良转账不会中止整个批次。 +大容量 USDT0 转账通过 MapReduce 启发式流水线进行批处理和并行验证。每个账户的失败是隔离的，因此一次错误的转账不会中止批处理。 -调用方转账 API 保持不变。您以正常方式提交转账，无需更改代码即可获得吞吐量。 +调用方的转账 API 保持不变。您以常规方式提交转账，无需更改代码即可提高吞吐量。 -阅读更多：[USDT 转账聚合器](/cn/explanation/usdt-transfer-aggregator)。 +了解更多：[USDT 转账聚合器](/cn/explanation/usdt-transfer-aggregator)。 ## EVM 兼容性 -标准 EVM 工具无需修改即可工作。在 EVM 层面，有三种行为与以太坊不同（USDT0 作为燃料，如上所述，是第四种）。 +标准 EVM 工具无需更改即可工作。在 EVM 层面，有三种行为与以太坊不同（上面已经介绍了 USDT0 作为燃料是第四种）。 -**单槽最终性。** 交易一旦包含在区块中即为最终交易。区块大约每 0.7 秒产出一个。 +**单槽最终性。** 交易一旦包含在区块中即为最终交易。区块大约每 0.7 秒生成一次。 -**无优先小费。** `maxPriorityFeePerGas` 始终被忽略。有效的燃气价格是协议设定的基础费用。 +**无优先级小费。** `maxPriorityFeePerGas` 始终被忽略。有效燃料价格是协议设置的基础费用。 ```typescript import { ethers } from "ethers"; @@ -75,23 +76,23 @@ console.log("Included at gas price:", tx.gasPrice?.toString()); Included at gas price: 1000000000 ``` -**USDT0 双重角色，移植风险。** 从以太坊移植的合约不应镜像原生余额，应拒绝 `address(0)` 转账，并且不应依赖 `EXTCODEHASH` 进行地址重用检测。 +**双重作用的 USDT0，移植风险。** 从以太坊移植的合约不应镜像原生余额，应拒绝 `address(0)` 转账，并且不应依赖 `EXTCODEHASH` 进行地址重用检测。 :::warning -在 Stable 上，移植一个在内部变量中镜像原生余额的合约是不安全的。外部的 `USDT0.transferFrom` 调用可以在不调用任何合约代码的情况下耗尽合约的原生余额。在转账时务必通过 `address(this).balance` 进行偿付能力检查。 +移植在内部变量中镜像原生余额的合约在 Stable 上是不安全的。外部 `USDT0.transferFrom` 调用可以耗尽合约的原生余额，而无需调用任何合约代码。在转账时务必使用 `address(this).balance` 进行偿付能力检查。 ::: -阅读更多：[与以太坊的区别](/cn/explanation/ethereum-comparison) · [Stable 上的合约](/cn/explanation/contracts-overview) · [USDT0 迁移清单](/cn/explanation/usdt0-behavior)。 +了解更多：[与以太坊的区别](/cn/explanation/ethereum-comparison) · [Stable 上的合约](/cn/explanation/contracts-overview) · [USDT0 迁移清单](/cn/explanation/usdt0-behavior)。 ## 机密转账（计划中） -Stable 有一个计划中的零知识转账功能，它可以隐藏金额，同时允许授权方进行审计。该功能尚未上线。 +Stable 有一个计划中的零知识转账功能，可以隐藏金额，同时允许授权方进行审计。该功能尚未上线。 -阅读更多：[机密转账](/cn/explanation/confidential-transfer)。 +了解更多：[机密转账](/cn/explanation/confidential-transfer)。 -## 接下来建议 +## 接下来去哪里 - [**快速入门**](/cn/tutorial/quick-start)：连接到测试网并发送第一笔交易。 -- [**USDT0 行为**](/cn/explanation/usdt0-behavior)：将合约移植到 Stable，避免双重角色陷阱。 -- [**燃气定价**](/cn/reference/gas-pricing-api)：在 Stable 的费用模型上正确构建交易。 +- [**USDT0 行为**](/cn/explanation/usdt0-behavior)：将合约移植到 Stable 而不会遇到双重作用的陷阱。 +- [**燃料定价**](/cn/reference/gas-pricing-api)：在 Stable 的费用模型上正确构建交易。 - [**生产就绪**](/cn/how-to/production-readiness)：在发布到主网之前验证集成。 diff --git a/docs/pages/cn/explanation/execution.mdx b/docs/pages/cn/explanation/execution.mdx index d9bebca..2b203a1 100755 --- a/docs/pages/cn/explanation/execution.mdx +++ b/docs/pages/cn/explanation/execution.mdx @@ -1,6 +1,6 @@ --- source_path: explanation/execution.mdx -source_sha: 6fd36fc5aba0418235d67180f61d452cae54c8a7 +source_sha: 4944b75f046b2ae6cae395c17b913b618cf9a3e3 title: "执行" description: "了解 Stable 如何使用 Block-STM 并发执行事务，同时保持确定性状态。" diataxis: "explanation" @@ -8,6 +8,8 @@ diataxis: "explanation" # 执行 +Stable 使用 Block-STM 并发执行 EVM 事务，同时保持确定性的最终状态。预编译将执行层连接到 Stable SDK 模块。 + ## Stable EVM Stable EVM -**Stable EVM** 是 Stable 的以太坊兼容执行层。现有的以太坊工具和钱包，如 MetaMask，可以直接与 Stable 交互而无需修改。Stable EVM 结合了 EVM 的开发者体验和 Stable SDK 的模块化基础设施。 +**Stable EVM** 是 Stable 的以太坊兼容执行层。现有的以太坊工具和钱包（如 MetaMask）与 Stable 的交互方式保持不变。Stable EVM 将 EVM 的开发者体验与 Stable SDK 的模块化基础设施相结合。 -为了弥合 Stable EVM 和 Stable SDK 之间的鸿沟，Stable EVM 引入了一组**预编译（precompiles）**。这些预编译将原生的 Stable SDK 模块功能暴露给 EVM 智能合约，使其能够安全且原子地调用核心链逻辑。智能合约随后可以执行特权操作，例如代币转移、质押或参与治理。 +为了弥合 Stable EVM 和 Stable SDK 之间的鸿沟，Stable EVM 引入了一组**预编译**。这些预编译将原生的 Stable SDK 模块功能暴露给 EVM 智能合约，使它们能够安全、原子地调用核心链逻辑。智能合约随后可以执行特权操作，例如代币转移、质押或参与治理。 -## v1.4.0 中的乐观并行执行 +## v1.8.0 中的乐观并行执行 -历史上，区块链系统一直依赖于顺序执行，即每个事务按顺序处理，以确保所有节点上的确定性状态。虽然这种设计保证了一致性，但它严重限制了吞吐量和可扩展性，尤其是当现代区块链旨在支持每秒数万个事务时。 +历史上，区块链系统一直依赖顺序执行，即每个事务依次处理，以确保所有节点的状态确定性。虽然这种设计保证了一致性，但它严重限制了吞吐量和可扩展性，尤其是在现代区块链旨在支持每秒数万笔事务的情况下。 -Stable v1.4.0 通过 Block-STM 引入了**乐观并行执行（Optimistic Parallel Execution, OPE）**。事务在 CPU 核心之间并发执行，而固定的块内顺序保持最终状态的确定性。 +Stable v1.8.0 通过 Block-STM 运行**乐观并行执行 (OPE)**。事务在 CPU 核心上并发执行，同时固定的块内顺序保持最终状态的确定性。 -### Block-STM 如何工作 +### Block-STM 的工作原理 -Block-STM 使用乐观并发控制机制：事务首先在假设它们不会冲突的情况下并行执行。然后，在验证阶段，通过重新执行来检测和处理任何冲突。该过程依赖于以下五种关键技术： +Block-STM 使用乐观并发控制机制：事务首先在假设它们不会冲突的情况下并行执行。然后，在验证阶段，检测并处理任何冲突，通过重新执行来解决。该过程依赖于以下五种关键技术： **1. 多版本内存结构** Block-STM 存储每个内存键的多个版本： -- 每个事务读取由先前事务提交的最新版本。 +- 每个事务读取先前事务提交的最新版本。 - 在执行期间，读取和写入都进行版本控制。 - 随后，在验证期间，检查这些版本的一致性以检测冲突。 -**2. 基于读写集（Read-Set / Write-Set）的验证** +**2. 基于读集/写集的验证** -- 在执行期间，每个事务将其读取的键和版本记录在读写集中。 -- 在执行结束时，它将其写集记录到多版本内存中。 -- 在验证期间，如果另一个事务修改了读写集中的任何键，则该事务被标记为冲突。然后它被中止并通过增加的迭代次数重新执行。 +- 在执行期间，每个事务都会将它读取的键和版本记录在读集中。 +- 执行结束时，它将其写集记录到多版本内存中。 +- 在验证期间，如果另一个事务修改了读集中的任何键，则该事务被标记为冲突。然后它被中止并以递增的化身号重新执行。 **3. 使用 ESTIMATE 标记快速检测冲突** - 当事务失败时，其写集会用 ESTIMATE 标志标记。 -- 如果另一个事务读取了带有 ESTIMATE 标记的值，它会立即停止并等待重新执行（由 `READ_ERROR` 触发）。 -- 这有助于通过快速识别依赖关系来减少开销，而无需重新执行完整的事务集。 +- 如果另一个事务读取了 ESTIMATE 标记的值，它会立即停止并等待重新执行（由 `READ_ERROR` 触发）。 +- 这有助于通过快速识别依赖关系来减少开销，而无需重新执行整个事务集。 **4. 预设事务顺序** -- 区块内的所有事务都按照预设的确定性顺序执行。 +- 块中的所有事务都按照预设的确定性顺序执行。 - 验证和提交阶段也遵循相同的顺序。 -- 这确保了即使是并行执行，所有节点也都能达到相同的最终状态。 +- 这确保了即使是并行执行，所有节点也能达到相同的最终状态。 **5. 协作调度器** - 协作调度器以线程安全的方式在执行和验证工作程序之间分配任务。 - 它优先处理索引较低的事务，以加速早期提交并最大程度地减少重新执行。 -- 调度器管理事务的迭代，以便在它们成功提交之前重复尝试。 +- 调度器管理事务化身，以进行重复尝试，直到它们成功提交。 ### Block-STM 的主要优势 -- **无锁并行化**：通过利用 MVCC（Multi-Version Concurrency Control），Block-STM 允许多个事务并发读写，无需互斥锁。冲突仅在执行后检查，从而在初始处理阶段实现最大吞吐量。 -- **通过 ESTIMATE 标记实现最小开销**：失败的事务用 ESTIMATE 标记标记其写集，信号通知依赖事务提前暂停，避免浪费执行。这导致更快地收敛到有效的执行路径。 -- **高效调度和优先提交**：使用协作调度器，系统通过首先提交索引较低的事务来最大限度地减少重试。这提高了整体吞吐量并缩短了执行周期。 -- **确定性和共识兼容性**：因为每个事务都遵循固定的顺序，即使重新执行的事务最终也会以相同的顺序提交。这确保了所有节点上的安全和确定性状态一致性，即使在并行化环境中也保持共识完整性。 +- **无锁并行**：通过利用 MVCC（多版本并发控制），Block-STM 允许多个事务并发读写，而无需互斥锁。冲突只在执行后检查，从而在初始处理阶段实现最大吞吐量。 +- **通过 ESTIMATE 标记实现最小开销**：失败的事务会用 ESTIMATE 标记其写集，指示依赖事务提前暂停，避免浪费执行。这会加快有效执行路径的收敛。 +- **高效调度和优先提交**：使用协作调度器，系统通过首先提交索引较低的事务来最大程度地减少重试。这提高了整体吞吐量并缩短了执行周期。 +- **确定性和共识兼容性**：因为每个事务都遵循固定的顺序，即使是重新执行的事务最终也会以相同的顺序提交。这确保了所有节点之间安全且确定性的状态一致性，即使在并行化环境中也能保持共识完整性。 ### Stable 上的 OPE Optimistic Parallel Execution on Stable -Stable 将 OPE 与**乐观区块处理（Optimistic Block Processing, OBP）**相结合。这两种优化处理不同的工作。 +Stable 将 OPE 与**乐观块处理 (OBP)** 结合使用。这两种优化解决了不同的工作。 ### 关于 OBP -- OBP 与并行化无关，而是与执行时机有关。 -- 在 `ProcessProposal` 阶段，Stable 在区块被传播到其他节点时预执行区块。 -- 生成的状态被缓存到内存中，并在 `FinalizeBlock` 期间重用，从而节省时间并减少重复计算。 +- OBP 与并行性无关，而是与执行时间有关。 +- 在 `ProcessProposal` 阶段，Stable 在块被传播到其他节点时预先执行这些块。 +- 生成的状态被缓存在内存中，并在 `FinalizeBlock` 期间重用，从而节省时间并减少重复计算。 -OPE 通过使用多个 CPU 核心来缩短执行时间。OBP 避免了在提案处理和最终确定过程中两次执行同一个区块。 +OPE 通过使用多个 CPU 核心来减少执行时间。OBP 避免在提案处理和最终确定过程中两次执行相同的块。 ### 提交后重新检查 -区块提交后，CometBFT 通常会重新检查内存池中等待的每个事务。这种重复的工作会消耗节点 31-34% 的 CPU。 +块提交后，CometBFT 通常会重新检查内存池中仍在等待的每个事务。这种重复的工作会消耗节点 31–34% 的 CPU。 -Stable v1.4.0 添加了**选择性 RecheckTx**。应用程序返回区块的状态更改增量，节点仅重新检查受影响账户的事务。CometBFT 检测应用程序支持，并在选择性重新检查不可用时回退到完全重新检查。 +Stable v1.8.0 包含**选择性 RecheckTx**。应用程序返回块的状态更改增量，节点仅重新检查受影响账户的事务。CometBFT 检测应用程序支持，并在选择性重新检查不可用时回退到完全重新检查。 -在最佳情况下，对来自唯一发送方的 10,000 个待处理事务的基准测试中，吞吐量从 700 提高到 1,400 TPS。更典型的工作负载预计提高 1.5-1.7 倍。 +在最佳情况基准测试中，有 10,000 个来自唯一发送者的待处理事务，吞吐量从 700 提高到 1,400 TPS。更典型的工作负载预计提高 1.5–1.7 倍。 -这里节省的 CPU 可用于 OPE 工作人员。MemIAVL 消除了可能限制这些执行增益的存储瓶颈。 +此处节省的 CPU 可供 OPE 工作人员使用。MemIAVL 消除了可能限制这些执行增益的存储瓶颈。 ## 未来路线图：StableVM++ -尽管像乐观并行执行（OPE）和乐观区块处理（OBP）这样的工作着重于优化**多个事务并发执行的方式**，但还有另一个重要的性能杠杆：**单个事务的处理效率**。 +虽然乐观并行执行 (OPE) 和乐观块处理 (OBP) 等工作侧重于优化*如何并发执行多个事务*，但还有另一个重要的性能杠杆：*每个事务的处理效率*。 -Stable 目前正在探索替代的 EVM 实现，以提高执行速度。在候选方案中，用 C++ 编写的高性能 EVM **EVMONE** 脱颖而出，有望取代现有的基于 Go 的 EVM。根据理论基准测试，预计这种转换将使 EVM 执行性能**提高多达 6 倍**。 +Stable 目前正在探索替代 EVM 实现以提高执行速度。在候选方案中，**EVMONE**（用 C++ 编写的高性能 EVM）作为替代现有基于 Go 的 EVM 的有力竞争者脱颖而出。根据理论基准测试，预计这种切换将使 **EVM 执行性能提高 6 倍**。 -## 接下来去哪里 +## 下一步 -- [**存储 (StableDB)**](/cn/explanation/stable-db)：了解分离的状态提交如何在不阻塞磁盘 I/O 的情况下进行执行。 -- [**高性能 RPC**](/cn/explanation/high-performance-rpc)：了解将执行结果显示给客户端的分离路径 RPC。 -- [**以太坊兼容性**](/cn/explanation/ethereum-compatibility)：使用标准 EVM 工具针对 Stable 移植现有合约。 -- [**网络升级**](/cn/reference/network-upgrades)：查看完整的 v1.4.0 发布范围和发布说明。 +- [**存储 (StableDB)**](/cn/explanation/stable-db)：了解分离的状态提交如何在不阻塞磁盘 I/O 的情况下支持执行。 +- [**高性能 RPC**](/cn/explanation/high-performance-rpc)：了解将执行结果呈现给客户端的分路径 RPC。 +- [**以太坊兼容性**](/cn/explanation/ethereum-compatibility)：使用标准 EVM 工具将现有合约移植到 Stable。 +- [**网络升级**](/cn/reference/network-upgrades)：查看 v1.8.0 发布范围和激活详情。 diff --git a/docs/pages/cn/explanation/guaranteed-blockspace.mdx b/docs/pages/cn/explanation/guaranteed-blockspace.mdx index 416f18b..545781f 100755 --- a/docs/pages/cn/explanation/guaranteed-blockspace.mdx +++ b/docs/pages/cn/explanation/guaranteed-blockspace.mdx @@ -1,70 +1,71 @@ --- source_path: explanation/guaranteed-blockspace.mdx -source_sha: 5a58c3c6715bd458c1b2a57a9130934021c66e59 -title: "有保证的区块空间" -description: "了解 Stable 如何通过二维随机数保留每个通道的 Gas 容量并识别优先级流量。" +source_sha: 457ac2eee760abfd2926cf176022aa6204a46e7a +title: "有保障的出块空间" +description: "了解 Stable 如何预留每通道的 gas 容量，并通过二维 nonce 识别优先级交易。" diataxis: "explanation" --- -# 有保证的区块空间 +# 有保障的出块空间 -Stable v1.4.0 将每个区块划分成具有独立 Gas 预算的通道。符合条件的优先级交易进入 VIP 通道，因此正常的流量无法占用为其保留的容量。 +Stable v1.8.0 将每个区块划分为具有独立 gas 预算的通道。符合条件的优先级交易进入企业通道，因此普通交易流量无法占用为它们预留的容量。 :::note -有保证的区块空间已在 v1.4.0 Testnet 候选版本中上线。主网升级时间表仍在等待中。如果没有治理配置，每个交易将继续使用一个普通通道。 +有保障的出块空间已在 Stable 主网和测试网上线。治理可以更改活跃的通道配置，因此在链下对交易进行分类之前，请查询 `blockspaceLanes()`。 ::: ## 区块通道 -提案和验证规则识别出三种通道类型： +提案和验证规则识别三种通道类型： -- **VIP 通道**：承载其 `NonceKey` 属于协议保留范围的交易。 +- **企业通道**：承载 `CustomTx` 交易，其 `NonceKey` 的第 63 位已设置，但无序标记 `MaxUint64` 除外。 - **交易类型通道**：为配置的交易类别保留容量。 - **普通通道**：承载不匹配其他已配置通道的标准交易。 -每个通道都有自己的 Gas 配额。提议者在这些限制内填充通道，验证者在验证提议的区块时强制执行相同的限制。 +`maxBlockspaceGasWeight` 设置了所有已配置通道预留的区块 gas 限制的百分比。每个通道的 `weight` 设置了该预留池的百分比。 -这使得保留在协议层面是确定性的。它不依赖于提议者自愿不留下未使用的空间。 +提案者在这些限制内填充通道，并且验证者在验证提议区块时强制执行相同的限制。 -## 二维随机数 +这使得预留方案在协议层面是确定性的。它不依赖于提案者自愿留下未使用的空间。 -以太坊账户通常有一个随机数序列。如果交易 12 缺失或卡住，交易 13 及之后的交易就无法执行。 +## 二维 nonce -**二维随机数**（或 2D 随机数）为账户提供了多个独立的序列。`NonceKey` 选择序列，交易的随机数给出其在该序列中的位置。 +以太坊账户通常只有一个 nonce 序列。如果交易 12 缺失或卡住，交易 13 及后续交易将无法执行。 -例如，一个支付账户可以使用 `NonceKey = 1` 进行工资支付，`NonceKey = 2` 进行供应商结算。延迟的工资支付交易不会阻塞供应商序列。 +**二维 nonce** 为账户提供了多个独立的序列。`NonceKey` 选择序列，交易的 nonce 给出其在该序列中的位置。 -随机数键空间有三个重要的区域： +例如，一个支付账户可以使用 `NonceKey = 1` 进行工资支付，使用 `NonceKey = 2` 进行供应商结算。延迟的工资支付交易不会阻塞供应商序列。 -- `NonceKey = 0` 保持标准的 EVM 兼容随机数行为。 -- `uint64` 范围的上半部分保留给协议使用。VIP 成员资格通过此范围传达。 -- `NonceKey = MaxUint64` 标记一个无序交易。`TimeoutTimestamp` 提供其重放保护截止日期。 +nonce 键空间有三个重要区域： -Stable 在 `CustomTx` (交易类型 `0x3F`) 中携带这些字段。现有的 EVM 交易格式仍然可用，并且默认的随机数通道保留了它们的预期行为。 +- `NonceKey = 0` 保持标准的 EVM 兼容 nonce 行为。 +- `uint64` 范围的上半部分预留给协议使用。设置第 63 位表示企业通道的资格。 +- `NonceKey = MaxUint64` 标记无序交易。`TimeoutTimestamp` 提供其重放保护截止日期。 + +Stable 在 `CustomTx` 中携带这些字段，交易类型为 `0x3F`。现有的 EVM 交易格式仍然可用，默认的 nonce 通道保留了它们的预期行为。 ## 治理和激活 -治理通过一个 `MsgUpdateParams` 提案控制通道定义和 Gas 配额。接受的参数在下一个区块生效。 +治理通过一个 `MsgUpdateParams` 提案控制通道定义和 gas 配额。接受的参数在下一个区块生效。 + +v1.8.0 主网升级设定了 `maxBlockspaceGasWeight = 20` 和一个 `weight = 50` 的企业通道。它没有设定交易类型通道。治理可以在之后更改这些参数。 -默认值不包含保留通道。在治理配置它们之前，链将作为单个普通通道运行。这使得通道配置是对现有交易处理的补充。 +`StableSystem` 预编译上的 `blockspaceLanes()` 查询返回活跃配置。两个通道数组都按 `id` 升序排序，较低的 ID 优先匹配。 ## 保证边界 -当满足所有这些条件时，VIP 交易会获得确定性的下一区块包含： +当所有这些条件都满足时，企业交易将获得确定性的下一区块包含： -- 交易符合 VIP 通道的资格。 -- 通道有足够的为交易保留的 Gas。 +- 交易符合企业通道的条件。 +- 该通道有足够的预留 gas 用于该交易。 - 验证者遵循协议。 -- 网络保持足够的同步性，以便验证者在提案之前接收交易。 - -Stable 的无内存池验证者入口模型将 VIP 交易提供给验证者。保留的提案容量随后阻止了正常流量取代它们。 +- 网络保持足够的同步性，以便验证者在提案之前收到交易。 -:::note -免 Gas 的交易类型通道被推迟了。一个 `gasPrice = 0` 的通道需要受信任的准入控制；否则，攻击者可以用免费交易淹没它。 -::: +Stable 的企业 RPC 网关向验证者提供符合条件的交易。预留的提案容量可以防止普通交易流量将其挤占。 -## 下一步 +## 接下来去哪里 -- [**有保证的结算**](/cn/explanation/upcoming-use-cases)：查看依赖于有保证的区块空间的支付模式：具有确定性包含的定时 DvP 结算周期。 -- [**网络升级**](/cn/reference/network-upgrades)：查看完整的 v1.4.0 版本及其推出状态。 +- [**有保障的结算**](/cn/explanation/upcoming-use-cases)：查看依赖于有保障出块空间的支付模式：具有确定性包含的定时 DvP 结算周期。 +- [**StableSystem 预编译**](/cn/reference/system-transactions-api)：查询活跃的企业通道和交易类型通道定义。 +- [**网络升级**](/cn/reference/network-upgrades)：查看 v1.8.0 发布和激活详情。 - [**执行**](/cn/explanation/execution)：了解 Stable 如何执行为每个区块选择的交易。 diff --git a/docs/pages/cn/explanation/stable-db.mdx b/docs/pages/cn/explanation/stable-db.mdx index c787760..6abf8d4 100755 --- a/docs/pages/cn/explanation/stable-db.mdx +++ b/docs/pages/cn/explanation/stable-db.mdx @@ -1,25 +1,25 @@ --- source_path: explanation/stable-db.mdx -source_sha: ffbcf61705d3dbb4a82da281257a33d12e385b45 +source_sha: 504059cb504eb59f4dab03833fd8498a842c7187 title: "存储 (StableDB)" -description: "了解 MemIAVL 如何使用内存映射快照和顺序写入预警日志来存储当前状态。" +description: "了解 MemIAVL 如何通过内存映射快照和顺序预写日志存储当前状态。" diataxis: "explanation" --- # 存储 (StableDB) -Stable v1.4.0 使用 MemIAVL 替代了基于 LevelDB 的状态存储。MemIAVL 将一个状态快照存储在内存映射文件中，并在顺序写入预警日志中记录每个新区块的更改。 +Stable v1.8.0 使用 MemIAVL 替代了之前基于 LevelDB 的状态存储。MemIAVL 将一个状态快照保存在内存映射文件中，并在顺序预写日志中记录每个新块的更改。 :::note -MemIAVL 已在 v1.4.0 测试网发布候选版本中上线。主网升级时间表仍在等待中。请关注[网络升级](/cn/reference/network-upgrades)以了解推出状态。 +MemIAVL 和 VersionDB 已在主网上线。Stable v1.8.0 还强化了 WAL 恢复、快照发布和回滚、状态同步以及历史查询资源清理。 ::: -## 磁盘 I/O 为何成为瓶颈 +## 为什么磁盘 I/O 是瓶颈 -每个区块都会改变应用程序状态。节点必须完成两个相关任务： +每个区块都会改变应用程序状态。节点必须完成两项相关任务： -1. **状态提交**：计算并提交新状态的根哈希。 -2. **状态持久化**：将更改的数据写入存储，以便节点以后可以恢复。 +1. **状态提交**：计算并提交新状态的根哈希。 +2. **状态持久化**：将更改的数据写入存储，以便节点以后可以恢复。 耦合的状态提交和存储 -以前的 LevelDB 后端存储将这些任务耦合在一起。它还在后台压缩期间重写数据，以重新组织存储的记录，从而提高后续读取效率。 +以前基于 LevelDB 的存储将这些任务耦合在一起。它还在后台压缩期间重写数据，压缩操作会重新组织存储的记录以提高后续读取效率。 -一次逻辑上的状态更新可能导致 10-50 倍的物理磁盘写入。这称为**写入放大**。执行必须等待一个由随机写入和压缩主导的存储路径。 +一个逻辑状态更新可能导致 10-50 倍的物理磁盘写入。这称为**写入放大**。执行必须等待一个以随机写入和压缩为主的存储路径。 ## MemIAVL 如何改变存储 -内存映射文件 (`mmap`) 允许操作系统通过内存地址暴露文件内容。节点可以通过指针读取状态，而操作系统将所需的页面加载到其页面缓存中。 +内存映射文件（或 `mmap`）允许操作系统通过内存地址暴露文件内容。节点可以通过跟踪指针来读取状态，而操作系统会将所需的页面加载到其页面缓存中。 MemIAVL 结合了两种结构： -- **快照**：持久化状态树的内存映射表示。 -- **写入预警日志 (WAL)**：快照后所做原始更改的仅追加记录。 +- **快照**：持久化状态树的一个内存映射表示。 +- **预写日志 (WAL)**：快照后所做原始更改的仅追加记录。 技术概述 + +## StableBFT + +**状态：已上线** + +Stable 区块链利用 **StableBFT**，一种基于 CometBFT 构建的定制 PoS 共识协议，以实现网络的高吞吐量、低延迟和高可靠性。 + +:::note +**计划中：** 基于 DAG 的 **Autobahn** 共识，具有解耦的数据传播。请参阅 [路线图](/cn/explanation/technical-roadmap#phase-3-full-stack-optimized-layer-for-usdt)。 +::: + +## Stable EVM + +**状态：已上线** + +**Stable EVM** 是 Stable 的以太坊兼容执行层。标准的以太坊工具和钱包可以无缝地与链进行交互。一组**预编译合约**将 Stable EVM 连接到 Stable SDK，允许 EVM 智能合约原子地调用核心链逻辑。 + +:::note +**v1.8.0 中已上线：** Block-STM 增加了跨 CPU 核的乐观并行执行。选择性 RecheckTx 减少了提交后的内存池工作。请参阅[执行](/cn/explanation/execution)。 +::: + +StableVM++ 作为当前基于 Go 的 EVM 实现的可能替代方案，仍是后续路线图项目。 + +## StableDB + +**状态：v1.8.0 在主网已上线** + +MemIAVL 用内存映射快照和仅追加的预写日志取代了 LevelDB。一个由 RocksDB 支持的 VersionDB 为早于保留快照的历史查询提供服务。 + +## 高性能 RPC + +**状态：已上线** + +即使在快速链上，缓慢的 RPC 层也会破坏用户体验。Stable 通过**分路径架构**解决了这个问题，该架构按功能分离操作，部署轻量级、专门的 RPC 节点以加快响应时间。 + +:::note +**计划中：** 针对 EVM 视图调用优化的 RPC 节点，以及节点集成的索引器。请参阅[路线图](/cn/explanation/technical-roadmap#phase-3-full-stack-optimized-layer-for-usdt)。 +::: + +## 接下来去哪里 + +- [**执行**](/cn/explanation/execution)：了解 OPE 和选择性 RecheckTx 如何消除 CPU 瓶颈。 +- [**存储 (StableDB)**](/cn/explanation/stable-db)：了解 MemIAVL 如何改变当前和历史状态存储。 +- [**保证的区块空间**](/cn/explanation/guaranteed-blockspace)：了解 2D nonce 和区块通道模型。 +- [**网络升级**](/cn/reference/network-upgrades)：查看 v1.8.0 兼容性和激活详情。 diff --git a/docs/pages/cn/explanation/technical-roadmap.mdx b/docs/pages/cn/explanation/technical-roadmap.mdx index 8f8a1db..90a8dfd 100755 --- a/docs/pages/cn/explanation/technical-roadmap.mdx +++ b/docs/pages/cn/explanation/technical-roadmap.mdx @@ -1,14 +1,14 @@ --- source_path: explanation/technical-roadmap.mdx -source_sha: 12d6268b1d6e265ecdcb13be47d79ee8c3d0e443 +source_sha: ff6d7eb8b66059317f331963487cd09ff3a2f9c1 title: "路线图" -description: "Stable 阶段性优化路线图：当前已上线功能、即将推出功能以及未来规划。" +description: "了解哪些 Stable 协议优化已上线、正在进行或已规划。" diataxis: "explanation" --- # 路线图 -Stable 分三阶段优化交易管道的每一层（共识、执行、存储、RPC 和 USDT 特定流程）。本页面将标记已发布、正在进行和仍在规划中的内容。 +Stable 的三阶段路线图涵盖了共识、执行、存储、RPC 和 USDT 特有的流程。以下每个项目都标明了已上线、正在进行或已规划。 { +stableSystem.on("UnbondingCompleted", (delegator, validator, originBlockHeight, amount, event) => { console.log("Unbonding completed:"); console.log(" Delegator:", delegator); console.log(" Validator:", validator); + console.log(" Origin block:", originBlockHeight.toString()); console.log(" Amount:", ethers.formatEther(amount), "tokens"); console.log(" Block:", event.log.blockNumber); console.log(" Tx Hash:", event.log.transactionHash); }); ``` -### 按用户筛选 +```text +Unbonding completed: + Delegator: 0xabcd... + Validator: 0x1234... + Origin block: 36975999 + Amount: 100.0 tokens + Block: 36976000 + Tx Hash: 0x12ab... +``` + +### 按用户过滤 要仅接收特定委托人地址的事件，请使用索引事件参数创建过滤器。 @@ -83,15 +99,26 @@ import { stableSystem } from "./config"; const userAddress = "0xabcd..."; const filter = stableSystem.filters.UnbondingCompleted(userAddress); -stableSystem.on(filter, (delegator, validator, amount, event) => { - refreshUserBalance(userAddress); - showNotification( - `您的 ${ethers.formatEther(amount)} 代币的解除质押已完成！` - ); +stableSystem.on(filter, (delegator, validator, originBlockHeight, amount) => { + console.log("User unbonding completed:", { + delegator, + validator, + originBlockHeight, + amount: ethers.formatEther(amount), + }); }); ``` -### 按验证者筛选 +```text +User unbonding completed: { + delegator: "0xabcd...", + validator: "0x1234...", + originBlockHeight: 36975999n, + amount: "100.0" +} +``` + +### 按验证者过滤 ```typescript // subscribeByValidator.ts @@ -103,14 +130,28 @@ const validatorFilter = stableSystem.filters.UnbondingCompleted( validatorAddress ); -stableSystem.on(validatorFilter, (delegator, validator, amount) => { - updateValidatorStats(validator, amount); +stableSystem.on(validatorFilter, (delegator, validator, originBlockHeight, amount) => { + console.log("Validator unbonding completed:", { + delegator, + validator, + originBlockHeight, + amount, + }); }); ``` +```text +Validator unbonding completed: { + delegator: "0xabcd...", + validator: "0x1234...", + originBlockHeight: 36975999n, + amount: 100000000000000000000n +} +``` + ### 历史查询 -如果你的 dApp 需要显示过去解除质押完成的历史记录，请使用带有区块范围的事件过滤器查询历史事件。 +如果您的 dApp 需要显示过去解除绑定的历史记录，请使用带有区块范围的事件过滤器查询历史事件。 ```typescript // queryHistory.ts @@ -128,6 +169,7 @@ async function getUnbondingHistory( return events.map((event) => ({ delegator: event.args.delegator, validator: event.args.validator, + originBlockHeight: event.args.originBlockHeight, amount: ethers.formatEther(event.args.amount), blockNumber: event.blockNumber, txHash: event.transactionHash, @@ -140,29 +182,54 @@ const history = await getUnbondingHistory( currentBlock - 1000, currentBlock ); + +console.log(history); +``` + +```text +[ + { + delegator: "0xabcd...", + validator: "0x1234...", + originBlockHeight: 36975999n, + amount: "100.0", + blockNumber: 36976000, + txHash: "0x12ab..." + } +] ``` ## 步骤 3：处理连接问题 -事件订阅依赖于持久的 WebSocket 连接。为生产 dApp 实现重新连接逻辑。 +事件订阅依赖于持久的 WebSocket 连接。请为生产 dApp 实现重新连接逻辑。 ```typescript // subscribeWithReconnection.ts -import { ethers } = "ethers"; +import { ethers } from "ethers"; import { STABLE_SYSTEM_ADDRESS, STABLE_SYSTEM_ABI } from "./config"; let reconnectAttempts = 0; const MAX_RECONNECT_ATTEMPTS = 5; -function handleUnbonding(delegator: string, validator: string, amount: bigint) { - console.log("解除质押完成:", { delegator, validator, amount }); +function handleUnbonding( + delegator: string, + validator: string, + originBlockHeight: bigint, + amount: bigint +) { + console.log("Unbonding completed:", { + delegator, + validator, + originBlockHeight, + amount, + }); } function setupEventListener() { const wsProvider = new ethers.WebSocketProvider("wss://rpc.testnet.stable.xyz"); wsProvider.on("error", (error) => { - console.error("提供者错误:", error); + console.error("Provider error:", error); if (reconnectAttempts < MAX_RECONNECT_ATTEMPTS) { reconnectAttempts++; setTimeout(() => setupEventListener(), 5000); @@ -181,8 +248,12 @@ function setupEventListener() { setupEventListener(); ``` -## 下一步推荐 +```text +No output until an unbonding completes or the provider reports an error. +``` + +## 接下来去哪里 -- [**系统交易概念**](/cn/explanation/system-transactions)：了解协议级别的事件如何到达 EVM。 -- [**质押模块概念**](/cn/explanation/staking-module)：回顾委托和解除质押流程。 +- [**系统事务概念**](/cn/explanation/system-transactions)：了解协议级事件如何到达 EVM。 +- [**质押模块概念**](/cn/explanation/staking-module)：回顾委托和解除绑定流程。 - [**质押预编译参考**](/cn/reference/staking-module-api)：查找触发此处跟踪的事件的方法。 diff --git a/docs/pages/cn/how-to/upgrade-node.mdx b/docs/pages/cn/how-to/upgrade-node.mdx index 6e0850a..1400361 100755 --- a/docs/pages/cn/how-to/upgrade-node.mdx +++ b/docs/pages/cn/how-to/upgrade-node.mdx @@ -1,262 +1,205 @@ --- source_path: how-to/upgrade-node.mdx -source_sha: c05435b6446847bcf6c1ef3c51961b184f712073 -title: 升级指南 -description: "Stable 网络版本变更的节点升级过程、升级类型和回滚策略。" +source_sha: e2f8ef3c819976fcf7a91e8ff2841f1368c80108 +title: "升级节点" +description: "通过备份身份、替换发布文件和验证同步来安全升级 Stable 节点。" diataxis: "how-to" --- -本指南介绍 Stable 节点的升级过程，包括升级步骤和回滚策略。 +# 升级节点 -> 有关完整的版本历史和升级详情，请参阅 [版本历史](/cn/reference/testnet-version-history)。 - -## 升级类型 - -### 软升级（非破坏性） -- 可随时执行 -- 向后兼容 - -### 硬升级（破坏性） -- 需要在特定高度进行升级 -- 不向后兼容 - -### 紧急升级 -- 关键安全修复 -- 需要立即采取行动 -- 可能需要暂停链 - -## v1.4.0 存储迁移 - -v1.4.0 将基于 LevelDB 的状态存储替换为 MemIAVL。除了正常二进制替换外，本次升级还需要数据迁移。 - -除非网络特定的升级说明选择其他方法，否则请使用本地快照导出和恢复。基准测试表明，标准恢复的平均验证器停机时间为 19.4 秒，并行恢复约为 2.6 秒。 - -以轮询方式迁移验证器，以便至少三分之二的投票权保持在线。如果您的节点必须回答早于其最早保留快照的历史查询，请配置基于 RocksDB 的 VersionDB。 +使用此过程升级 Stable 节点，同时保留其节点特定配置和验证器状态。始终从网络历史页面获取版本、二进制文件和激活高度。 :::warning -请勿对 v1.4.0 使用下面通用的纯二进制过程。请等待 [网络升级](/cn/reference/network-upgrades) 中的最终网络特定二进制文件、升级高度、备份路径和恢复命令。 +状态中断升级要求每个节点在协调高度切换。在停止或替换任何内容之前，请确认网络、版本和升级高度。 ::: -## 标准升级流程 +## 开始之前 -### 步骤 1：准备 +你需要： -```bash -# Check current version -stabled version --long +- 节点的 Shell 访问权限以及管理其服务的权限。 +- 足以在活动数据目录之外进行受保护备份的磁盘空间。 +- 部署的节点主目录、服务名称和已安装的二进制文件路径。 +- [主网版本历史](/cn/reference/mainnet-version-history) 或 [测试网版本历史](/cn/reference/testnet-version-history) 中的版本条目。 -# Backup critical data -cp -r ~/.stabled/config ~/stable-backup-$(date +%Y%m%d)/ +以下示例使用这些路径。将它们更改为与你的部署匹配： -# For validators only: Backup validator state -cp ~/.stabled/data/priv_validator_state.json ~/stable-backup-$(date +%Y%m%d)/ +```bash +export STABLED_HOME="/var/lib/stabled" +export STABLED_SERVICE="stabled" +export STABLED_BIN="/usr/local/bin/stabled" +export STABLED_ARCH="amd64" # 在 ARM 主机上使用 arm64。 +``` -# Check disk space (need 2x current data size) -df -h ~/.stabled +```text +无输出。 ``` -### 步骤 2：下载新二进制文件 +## 1. 检查运行中的节点 + +在更改节点之前记录当前构建和同步状态： ```bash -# For v1.2.0-rc1 upgrade (January 22, 2026) -# Choose your architecture: +"$STABLED_BIN" version --long +curl -fsS http://localhost:26657/status \ + | jq '{catching_up: .result.sync_info.catching_up, latest_block_height: .result.sync_info.latest_block_height}' +``` -# Linux AMD64 -BINARY_URL="https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.2.0-rc1-linux-amd64-testnet.tar.gz" +```text +<当前构建信息> +{ + "catching_up": false, + "latest_block_height": "<当前高度>" +} +``` -# OR Linux ARM64 -BINARY_URL="https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.2.0-rc1-linux-arm64-testnet.tar.gz" +在 `catching_up` 为 `false` 之前不要继续。 -# Download new binary -wget $BINARY_URL +## 2. 备份身份和配置 -# Extract to temporary location -tar -xvzf stabled-1.2.0-rc1-linux-*.tar.gz -C /tmp/ +保持验证器密钥和签名状态私密。将此备份存储在加密存储上，权限仅限于节点操作员。 -# Verify new version -/tmp/stabled version --long +```bash +export STABLED_BACKUP="/var/backups/stabled/pre-upgrade" +sudo install -d -m 0700 "$STABLED_BACKUP" +sudo cp -a "$STABLED_HOME/config" "$STABLED_BACKUP/config" +sudo cp -a "$STABLED_HOME/data/priv_validator_state.json" \ + "$STABLED_BACKUP/priv_validator_state.json" +sudo cp -a "$STABLED_BIN" "$STABLED_BACKUP/stabled" +printf '备份存储在 %s\n' "$STABLED_BACKUP" ``` -### 步骤 3：执行升级 - -#### 对于软升级 - -```bash -# Stop node -sudo systemctl stop ${SERVICE_NAME} +```text +备份存储在 /var/backups/stabled/pre-upgrade +``` -# Backup current binary -sudo mv /usr/bin/stabled /usr/bin/stabled.backup +:::danger +切勿使用相同的私有验证器密钥运行两个验证器。重复的密钥可能导致双重签名和惩罚。 +::: -# Install new binary -sudo mv /tmp/stabled /usr/bin/stabled -sudo chmod +x /usr/bin/stabled +## 3. 下载并检查发布版本 -# Verify installation -stabled version --long +Stable 主网在区块 `36,976,000` 激活了 v1.8.0。下载适用于你的主机架构的存档，并在安装前检查报告的构建： -# Start node -sudo systemctl start ${SERVICE_NAME} +```bash +export STABLED_RELEASE="v1.8.0" +export STABLED_ARCHIVE="/tmp/stabled-1.8.0-linux-${STABLED_ARCH}-mainnet.tar.gz" +export STABLED_STAGE="/tmp/stabled-v1.8.0" + +curl -fL \ + "https://stable-data-dist.s3.us-east-1.amazonaws.com/mainnet/binary/stabled-1.8.0-linux-${STABLED_ARCH}-mainnet.tar.gz" \ + -o "$STABLED_ARCHIVE" +mkdir -p "$STABLED_STAGE" +tar -xzf "$STABLED_ARCHIVE" -C "$STABLED_STAGE" +"$STABLED_STAGE/stabled" version --long +``` -# Monitor logs -sudo journalctl -u ${SERVICE_NAME} -f +```text + ``` -#### 对于硬升级 +对于其他版本或测试网，从相应的版本历史表中复制精确的二进制文件 URL。 -```bash -# Monitor for upgrade height -while true; do - HEIGHT=$(curl -s localhost:26657/status | jq -r '.result.sync_info.latest_block_height') - echo "Current height: $HEIGHT" - if [ $HEIGHT -ge $UPGRADE_HEIGHT ]; then - break - fi - sleep 10 -done - -# Node will halt automatically at upgrade height -# Wait for halt message in logs -sudo journalctl -u ${SERVICE_NAME} -f | grep "UPGRADE" - -# Once halted, perform upgrade -sudo systemctl stop ${SERVICE_NAME} -sudo mv /usr/bin/stabled /usr/bin/stabled.backup -sudo mv /tmp/stabled /usr/bin/stabled - -# Start with new binary -sudo systemctl start ${SERVICE_NAME} -``` +## 4. 准备 v1.8.0 配置 -### 步骤 4：升级后验证 +v1.8.0 在 `config.toml` 和 `app.toml` 中添加了所需设置。将主网模板下载到临时目录： ```bash -# Check node status -curl -s localhost:26657/status | jq '.result' - -# Verify version -curl -s localhost:26657/status | jq '.result.node_info.version' +export STABLED_CONFIG_STAGE="/tmp/stable-v1.8.0-config" +mkdir -p "$STABLED_CONFIG_STAGE" +curl -fL \ + "https://stable-data-dist.s3.us-east-1.amazonaws.com/mainnet/configuration/v1.8.0/partners/config.toml" \ + -o "$STABLED_CONFIG_STAGE/config.toml" +curl -fL \ + "https://stable-data-dist.s3.us-east-1.amazonaws.com/mainnet/configuration/v1.8.0/partners/app.toml" \ + -o "$STABLED_CONFIG_STAGE/app.toml" +printf '配置暂存到 %s\n' "$STABLED_CONFIG_STAGE" +``` -# Check peers -curl -s localhost:26657/net_info | jq '.result.n_peers' +```text +配置暂存到 /tmp/stable-v1.8.0-config +``` -# Monitor sync status -watch -n 2 'curl -s localhost:26657/status | jq ".result.sync_info"' +从这些模板开始，然后从备份中恢复每个节点特定的值。至少检查： -# Check for errors -sudo journalctl -u ${SERVICE_NAME} --since "10 minutes ago" | grep -i error -``` +- `moniker` 和 `external_address`。 +- 持久对等点、种子和私有对等点设置。 +- API、JSON-RPC、gRPC 和指标设置。 +- 组织特定的超时和资源限制。 +- 归档节点的修剪设置。 -## Cosmovisor 设置（自动化升级） +分发的 `app.toml` 使用默认修剪。修剪的历史无法从本地节点重建。v1.8.0 还强制关闭 `inter-block-cache`。 -Cosmovisor 自动化协调升级过程。 +## 5. 停止节点并安装文件 -### 安装 +对于协调的未来升级，等待节点在发布的高度停止。v1.8.0 主网高度是历史的，因此较旧的主网节点可以在此安装之前停止。 ```bash -# Install cosmovisor -go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest +sudo systemctl stop "$STABLED_SERVICE" +systemctl is-active "$STABLED_SERVICE" || true +``` -# Or download binary -wget https://github.com/cosmos/cosmos-sdk/releases/download/cosmovisor%2Fv1.7.0/cosmovisor-v1.7.0-linux-amd64.tar.gz -tar -xzf cosmovisor-v1.7.0-linux-amd64.tar.gz -sudo mv cosmovisor /usr/bin/ +```text +非活动 ``` -### 配置 +安装暂存的二进制文件和已完成的配置文件： ```bash -# Set environment variables -cat >> ~/.bashrc < /dev/null < +{ + "catching_up": false, + "latest_block_height": "<当前高度>" +} +``` -```bash -# Stop node -sudo systemctl stop ${SERVICE_NAME} +在将节点恢复正常操作之前，检查服务日志中是否有重复的崩溃、共识失败或配置解析错误。 -# Backup current state (in case needed) -cp -r ~/.stabled/data ~/.stabled/data.failed +## 使用 Cosmovisor 自动执行未来的升级 -# Restore from snapshot before upgrade -cd ~/.stabled -rm -rf data/ -tar -I lz4 -xf ~/snapshots/pre-upgrade-snapshot.tar.lz4 +当链上升级处理程序达到其配置的高度时，Cosmovisor 可以切换二进制文件。遵循 [Cosmovisor 文档](https://docs.cosmos.network/main/build/tooling/cosmovisor) 并使用适用治理提案中的升级名称。 -# Restore previous binary -sudo mv /usr/bin/stabled.backup /usr/bin/stabled +除非你的操作策略明确信任配置的源，否则请禁用自动二进制下载。在激活高度之前暂存并验证发布二进制文件。 -# Start node -sudo systemctl start ${SERVICE_NAME} -``` +## 仅根据特定于版本的说明回滚 -## 紧急程序 +:::danger +除非 Stable 的发布说明要求，否则不要删除活动数据目录或恢复旧快照。使用旧的二进制文件对抗由较新版本写入的状态可能会损坏节点或使其跟随错误的链。 +::: -```bash -# If chain halts unexpectedly -# 1. Check Discord for instructions -# 2. Export state at last known good height -stabled export --height > export.json +如果新进程在执行升级块之前失败，请保持服务停止并检查错误。仅当发布说明表示回滚安全时才恢复以前的二进制文件和配置。 -# 3. Wait for coordinated restart instructions -``` +如果节点已执行升级块，请与网络操作员协调恢复。恢复可能需要特定于版本的二进制文件或在商定高度的受信任快照。 -## 后续步骤 +## 接下来去哪里 -- [版本历史](/cn/reference/testnet-version-history) - 完整的升级历史和发行说明 -- 升级后[监控您的节点](/cn/how-to/monitor-node) -- 查看[故障排除](/cn/how-to/troubleshoot-node)以获取常见问题 +- [**网络升级**](/cn/reference/network-upgrades)：确定每个协议版本的兼容性和操作员影响。 +- [**监控节点**](/cn/how-to/monitor-node)：升级后验证同步、对等点、资源使用和服务运行状况。 +- [**故障排除节点**](/cn/how-to/troubleshoot-node)：诊断启动、网络、共识和存储故障。 diff --git a/docs/pages/cn/how-to/use-system-modules.mdx b/docs/pages/cn/how-to/use-system-modules.mdx index 09382f3..9b57b71 100644 --- a/docs/pages/cn/how-to/use-system-modules.mdx +++ b/docs/pages/cn/how-to/use-system-modules.mdx @@ -1,46 +1,45 @@ --- source_path: how-to/use-system-modules.mdx -source_sha: cfd6ec43ac3c766ae5fdb7d0007a1cb6671ad955 +source_sha: fb55bfe49f1cc321f4a78da45af133aad15ab828 title: "使用系统模块" -description: "通过最少的 ABI 和工作示例，从 Solidity 和 ethers.js 调用 Stable 的银行、分配和质押预编译。" +description: "通过最少的 ABI 和工作示例，从 Solidity 和 ethers.js 调用 Stable 协议的预编译。" diataxis: "how-to" --- # 使用系统模块 -Stable 通过固定地址的**预编译合约**公开协议级结算逻辑。预编译合约允许 EVM 代码调用 Stable SDK 模块（质押、奖励分配、STABLE 代币操作），而无需重新实现它们。由于它们在协议级别运行，因此比同等的 Solidity 实现效率更高，消耗的 Gas 更少。 - -本指南介绍了如何从 Solidity 和 ethers.js 调用预编译合约，以及何时使用预编译合约而不是常规合约。 +Stable 通过固定地址的**预编译合约**公开协议级逻辑。您可以从 Solidity 或 ethers.js 调用这些预编译，而不是在应用程序合约中重新实现 Stable SDK 行为。 :::note -**概念**：有关系统模块的功能和为何它们是预编译合约，请参阅[系统模块概述](/cn/explanation/system-modules-overview)。有关每个模块的方法签名和事件，请参阅[系统模块参考](/cn/reference/system-modules-api-overview)。 +**概念**：有关系统模块的功能以及为何它们是预编译的，请参阅[系统模块](/cn/explanation/system-modules-overview)。有关每个模块的方法签名和事件，请参阅[系统模块参考](/cn/reference/system-modules-api-overview)。 ::: ## 开放的功能 -| **模块** | **预编译合约地址** | **用途** | +| **模块** | **预编译地址** | **用途** | | :--- | :--- | :--- | -| Bank (银行) | `0x0000000000000000000000000000000000001003` | STABLE 代币转账和余额操作 | -| Distribution (分配) | `0x0000000000000000000000000000000000000801` | 领取质押奖励、奖励查询、佣金管理 | -| Staking (质押) | `0x0000000000000000000000000000000000000800` | 委托、解除委托、重新委托、验证者查询 | -| Gov (治理) | `0x0000000000000000000000000000000000000805` | 提案、计票结果和链上投票记录 | -| Slashing (罚没) | `0x0000000000000000000000000000000000000806` | 验证者签名信息和正常运行时间 | -| StableSystem | `0x0000000000000000000000000000000000009999` | 系统交易的 EVM 事件 emission（解除绑定完成） | +| Bank | `0x0000000000000000000000000000000000001003` | STABLE 代币转账和余额操作 | +| Distribution | `0x0000000000000000000000000000000000000801` | 领取质押奖励、奖励查询、佣金管理 | +| Staking | `0x0000000000000000000000000000000000000800` | 委托、取消委托、重新委托、验证者查询 | +| Gov | `0x0000000000000000000000000000000000000805` | 提案、计票结果和链上投票记录 | +| Slashing | `0x0000000000000000000000000000000000000806` | 验证者签名信息和正常运行时间 | +| StableSystem | `0x0000000000000000000000000000000000009999` | 保证区块空间通道查询和系统交易的 EVM 事件发射 | -所有这些都可以从任何 EVM 合约或链下客户端调用。这些地址是稳定的，在主网和测试网上都相同。 +读取方法可以从任何 EVM 合约或链下客户端调用。某些状态更改方法强制执行调用者授权，`notifySystemTxLogs()` 仅接受协议生成的系统交易。这些地址在主网和测试网上是相同的。 -## 何时调用预编译合约与常规合约 +## 何时调用预编译合约与普通合约 -- **在以下情况下使用预编译合约**：当操作映射到 Stable SDK 模块时：质押、奖励分配、STABLE 代币操作。调用预编译合约更便宜，并且是触发协议级行为的唯一方式。 -- **在以下情况下使用常规合约**：当操作是应用程序逻辑时：托管、定价、访问控制。如果您需要自定义授权或验证，请将预编译合约调用包装在您自己的合约中。 +- **在操作映射到 Stable SDK 模块时使用预编译**：质押、奖励分配、STABLE 代币操作。调用预编译既便宜又是触发协议级行为的唯一方法。 +- **在操作是应用程序逻辑时使用普通合约**：托管、定价、访问控制。如果您需要自定义授权或验证，请将预编译调用包装在您自己的合约中。 -预编译合约不能替代应用程序合约。它们是底层协议的稳定接口。 +预编译不能替代应用程序合约。它们是底层协议的稳定接口。 ## 从 Solidity 调用 -为所需方法声明一个接口，然后像调用已部署合约一样调用预编译合约。 +为您需要的方法声明一个接口，然后像调用已部署的合约一样调用预编译。 ```solidity +// SAFE: the precompile address is fixed on Stable. // SPDX-License-Identifier: MIT pragma solidity ^0.8.24; @@ -87,15 +86,11 @@ contract StakingHelper { } ``` -使用 Foundry 或 Hardhat 编译和部署。预编译合约地址在合约中固定不变，因此部署后无需任何额外配置。 - -```solidity -// SAFE: 预编译合约地址在 Stable 上固定且永不改变。 -``` +使用 Foundry 或 Hardhat 编译和部署。预编译地址在常量槽中已写入合约，因此部署后无需进行任何连接。 ## 从 ethers.js 调用 -对于链下客户端，声明相同的接口作为最小 ABI，并实例化指向预编译地址的合约。 +对于链下客户端，将相同的接口声明为最小 ABI，并实例化指向预编译地址的合约。 ```typescript // queryDelegation.ts @@ -133,9 +128,9 @@ Delegation balance: 1000.0 STABLE ## 订阅系统交易事件 -一些 Stable SDK 操作（例如解除绑定完成）不会自然地发出 EVM 事件。Stable 通过**系统交易**弥补了这一空白：验证者生成的交易调用 `StableSystem` 预编译合约，以便在下一个区块期间发出标准 EVM 事件。 +某些 Stable SDK 操作（例如解除绑定完成）不会自然地发出 EVM 事件。Stable 通过**系统交易**弥补了这一空白：验证者生成的交易调用 `StableSystem` 预编译以在下一个区块期间发出标准 EVM 事件。 -要监视 `UnbondingCompleted`，请像监听 ERC-20 `Transfer` 事件一样订阅预编译合约地址。 +要观察 `UnbondingCompleted`，请像任何 ERC-20 `Transfer` 监听器一样在预编译地址订阅。 ```typescript // watchUnbonding.ts @@ -148,13 +143,14 @@ const STABLE_SYSTEM = "0x0000000000000000000000000000000000009999"; const stableSystem = new ethers.Contract( STABLE_SYSTEM, [ - "event UnbondingCompleted(address indexed delegator, address indexed validator, uint256 amount)", + "event UnbondingCompleted(address indexed delegator, address indexed validator, uint64 indexed originBlockHeight, uint256 amount)", ], provider ); -stableSystem.on("UnbondingCompleted", (delegator, validator, amount, event) => { +stableSystem.on("UnbondingCompleted", (delegator, validator, originBlockHeight, amount, event) => { console.log("Unbonding completed for:", delegator); + console.log("Origin block:", originBlockHeight.toString()); console.log("Amount:", ethers.formatEther(amount), "STABLE"); console.log("Tx:", event.log.transactionHash); }); @@ -169,23 +165,24 @@ npx tsx watchUnbonding.ts ```text Listening for UnbondingCompleted events... Unbonding completed for: 0xabcd... +Origin block: 36975999 Amount: 100.0 STABLE Tx: 0x12ab... ``` -有关完整的系统交易机制以及按用户筛选/历史查询模式，请参阅[跟踪解除绑定完成情况](/cn/how-to/track-unbonding)。 +有关完整的系统交易机制以及按用户过滤/历史查询模式，请参阅[跟踪解除绑定完成情况](/cn/how-to/track-unbonding)。 -## 各模块参考 +## 每个模块的参考 -每个预编译合约的完整方法列表、事件和授权规则都可以在其参考页面中找到。 +每个预编译的完整方法列表、事件和授权规则都可以在其参考页面中找到。 -- [银行预编译合约](/cn/reference/bank-module-api)：STABLE 代币转账和供应查询。 -- [分配预编译合约](/cn/reference/distribution-module-api)：奖励领取和佣金。 -- [质押预编译合约](/cn/reference/staking-module-api)：委托、解除委托、重新委托、验证者查询。 +- [Bank 预编译](/cn/reference/bank-module-api)：STABLE 代币转账和供应查询。 +- [Distribution 预编译](/cn/reference/distribution-module-api)：奖励领取和佣金。 +- [Staking 预编译](/cn/reference/staking-module-api)：委托、取消委托、重新委托、验证者查询。 - [系统交易](/cn/reference/system-transactions-api)：StableSystem 事件格式和授权。 -## 下一步建议 +## 下一步 -- [**跟踪解除绑定完成情况**](/cn/how-to/track-unbonding)：订阅通过 StableSystem 预编译合约发出的 `UnbondingCompleted` 事件。 -- [**系统模块参考**](/cn/reference/system-modules-api-overview)：跳转到各模块的 ABI、方法签名和事件模式。 -- [**系统模块概念**](/cn/explanation/system-modules-overview)：了解 Stable 为什么通过预编译合约公开 SDK 模块。 +- [**跟踪解除绑定完成情况**](/cn/how-to/track-unbonding)：订阅通过 StableSystem 预编译发出的 UnbondingCompleted 事件。 +- [**系统模块参考**](/cn/reference/system-modules-api-overview)：跳转到每个模块的 ABI、方法签名和事件 schema。 +- [**系统模块概念**](/cn/explanation/system-modules-overview)：了解 Stable 为何通过预编译公开 SDK 模块。 diff --git a/docs/pages/cn/reference/network-upgrades.mdx b/docs/pages/cn/reference/network-upgrades.mdx index 5bcef45..0290f56 100644 --- a/docs/pages/cn/reference/network-upgrades.mdx +++ b/docs/pages/cn/reference/network-upgrades.mdx @@ -1,24 +1,24 @@ --- source_path: reference/network-upgrades.mdx -source_sha: cdcb426b3580e25ac41f039bd750b4356f3803ce +source_sha: 5f1fc33d12d32aa730cd5949a3cf5645be11733f title: "网络升级" -description: "Stable 网络协议版本的发布说明：每个版本更改了什么以及谁需要采取行动。" +description: "识别每个 Stable 版本中发生的变化，以及您的节点或应用程序是否需要更新。" diataxis: "reference" --- # 网络升级 -下面的每个条目都描述了 StableChain 版本中更改的内容、重要性以及您是否需要采取任何操作。发布按最新排序。有关二进制文件、提交哈希和升级块高度，请参阅[主网版本历史记录](/cn/reference/mainnet-version-history)和[测试网版本历史记录](/cn/reference/testnet-version-history)。 +以下每个条目都描述了 StableChain 版本中发生的变化、重要性以及您是否需要执行任何操作。版本按最新到最旧的顺序列出。有关二进制文件、提交哈希和升级区块高度，请参阅[主网版本历史](/cn/reference/mainnet-version-history)和[测试网版本历史](/cn/reference/testnet-version-history)。 ## 如何阅读这些说明 -以下是一些常用术语的含义： +下面是一些常见术语及其含义： -- **状态破坏性升级**：所有节点必须在相同的块高度运行新的二进制文件，通过治理提案进行协调。这些版本在版本历史记录表中有一个升级高度。如果您运行验证器，则必须按计划升级，否则您的节点将停止跟随链。 -- **向后兼容升级**：新的二进制文件与旧的二进制文件兼容，因此没有协调的切换。这些版本没有升级高度。您可以在方便时通过替换二进制文件进行升级。 -- **Gas 豁免**：StableChain 的一项功能，允许赞助者支付交易费用，这样发送者就可以在不持有 gas 代币的情况下进行交易。 -- **系统交易**：协议本身（而不是普通用户）为运行内部操作而发起的特殊交易。 -- **预编译**：一个内置的固定地址合约，运行原生代码而不是 EVM 字节码，用于需要快速执行的常见操作。 +- **状态破坏性升级**：所有节点必须在同一区块高度运行新的二进制文件，通过治理提案协调。这些版本在版本历史表中具有升级高度。如果您运行验证器，则必须按计划升级，否则您的节点将停止遵循链。 +- **向后兼容升级**：新的二进制文件与旧的二进制文件兼容，因此无需协调切换。这些版本没有升级高度。您可以在方便时通过替换二进制文件进行升级。 +- **燃气豁免**：StableChain 的一项功能，允许赞助商支付交易费用，这样发送方无需持有燃气代币即可进行交易。 +- **系统交易**：协议本身而非普通用户发出的特殊交易，用于运行内部操作。 +- **预编译**：位于固定地址的内置合约，运行本机代码而不是 EVM 字节码，用于需要快速执行的常见操作。 要检查您的节点运行的是哪个版本： @@ -27,118 +27,126 @@ stabled version ``` ```text -v1.3.1 +v1.8.0 ``` -## v1.4.0 (即将发布) :badge[测试网]{warning} +## v1.8.0 :badge[当前]{success} -一个性能和可预测性版本，目前作为发布候选版本在测试网上线，尚未在主网上线。它将四个更改分为两个主题：加快块处理速度，以及使优先流量的交易包含更具可预测性。 +一个状态机破坏性主网升级，于 2026 年 8 月 26 日在区块 `36,976,000` 激活。它将四个更改分为两个主题：更快的区块处理和优先级流量的可预测包含。 -| **举措** | **块阶段** | **更改内容** | **预期结果** | +| **举措** | **区块阶段** | **变化内容** | **预期结果** | | :--- | :--- | :--- | :--- | -| 乐观并行执行 (OPE) | 执行 | Block-STM 替代顺序交易执行。 | 多核执行，目标是大约 10,000 TPS。 | -| 选择性重新检查交易 | 提交后内存池重新检查 | 节点仅重新检查由已提交块更改的账户的交易。 | 在最佳测量情况下，持续吞吐量可提高两倍，节点 CPU 使用率降低 31-34%。 | -| MemIAVL | 状态持久性 | 内存映射快照和预写日志 (WAL) 替代基于 LevelDB 的存储。 | 写入放大从 10-50 倍降至约一次写入。 | -| 2D nonce 和保证块空间 | 提交和块提案 | 独立的 nonce 通道与保留的每通道 gas 容量相结合。 | 符合条件的 VIP 交易的确定性下一块包含。 | +| 乐观并行执行 (OPE) | 执行 | Block-STM 替代了顺序交易执行。 | 多核执行，目标约为 10,000 TPS。 | +| 选择性 RecheckTx | 提交后内存池重新检查 | 节点仅重新检查由已提交区块更改的账户的交易。 | 在测量最佳情况下，持续吞吐量最高可提高一倍，节点 CPU 使用率降低 31-34%。 | +| MemIAVL | 状态持久化 | 内存映射快照和预写日志 (WAL) 替代了 LevelDB 支持的存储。 | 写入放大从 10-50 倍降至约一次写入。 | +| 2D 随机数和企业区块空间 | 提交和区块提议 | 独立的随机数通道与每个通道预留的燃气容量相结合。 | 符合条件的企业交易的确定性下一区块包含。 | -这些更改解决了单个块生命周期的不同阶段： +这些更改解决了区块生命周期的不同阶段： -1. **提交**：2D nonce 允许一个账户通过独立的 nonce 通道提交交易。一个通道上的卡住交易不会阻塞其他通道。 -2. **提案**：保证块空间将块划分为 VIP、交易类型和普通通道。每个通道都有一个在提案和验证期间强制执行的保留 gas 预算。 -3. **执行**：OPE 通过 Block-STM 并发运行交易，然后根据固定的块内顺序对其进行验证。每个节点仍然产生相同的状态。 -4. **提交**：MemIAVL 将更改附加到 WAL 中，与一个内存映射快照对应。这避免了 LevelDB 压缩及其重复的磁盘写入。 -5. **提交后重新检查**：选择性重新检查交易使用块的状态更改增量仅重新检查受影响的发送方，而不是扫描整个内存池。 +1. **提交**：2D 随机数允许账户通过独立的随机数通道提交交易。一个通道上的卡顿交易不会阻塞其他通道。 +2. **提议**：保证的区块空间将区块分为企业、交易类型和普通通道。每个通道都有一个在提议和验证期间强制执行的预留燃气预算。 +3. **执行**：OPE 通过 Block-STM 并发执行交易，然后根据固定的区块内顺序进行验证。每个节点仍然产生相同的状态。 +4. **提交**：MemIAVL 将更改附加到 WAL，并针对一个内存映射快照。这避免了 LevelDB 压缩及其重复的磁盘写入。 +5. **提交后重新检查**：选择性 RecheckTx 使用区块的状态更改增量仅重新检查受影响的发送方，而不是扫描整个内存池。 ### 吞吐量变化 -OPE 将交易执行从一个 CPU 核心移到多个核心。交易乐观执行，冲突触发重新执行，固定的交易顺序保留确定性结果。 +OPE 将交易执行从一个 CPU 核心转移到多个核心。交易乐观执行，冲突触发重新执行，固定的交易顺序保持确定性结果。 -选择性重新检查交易在每次提交后删除工作。在包含来自唯一发送者的 10,000 个待处理交易的最佳测试中，吞吐量从 700 TPS 增加到 1,400 TPS。对于更典型的工作负载，预计改进为 1.5–1.7 倍。CometBFT 检测应用程序是否支持选择性重新检查，如果不支持，则回退到完全重新检查。 +选择性 RecheckTx 在每次提交后减少工作量。在一次最佳情况测试中，有 10,000 个来自唯一发送方的待处理交易，吞吐量从 700 增加到 1,400 TPS。对于更典型的负载，预计改进为 1.5-1.7 倍。CometBFT 检测应用程序是否支持选择性重新检查，并在不支持时回退到完全重新检查。 -MemIAVL 从状态存储路径中移除 LevelDB。写入变为包含原始更改集的顺序 WAL 条目。读取变为对操作系统页面缓存的指针查找。一个单独的 VersionDB（由 RocksDB 支持）服务于早于最早保留快照的历史状态。 +MemIAVL 从状态存储路径中移除 LevelDB。写入变为包含原始更改集的顺序 WAL 条目。读取变为指向操作系统页面缓存的指针查找。单独的 VersionDB（由 RocksDB 支持）提供早于最早保留快照的历史状态。 ### 可预测的包含 -2D nonce 为每个账户提供了多个独立的 nonce 通道。 `NonceKey` 选择通道。 `NonceKey = 0` 保留正常的 EVM 兼容序列，而协议保留 `uint64` 范围的上半部分供自己使用。 `MaxUint64` 标记一个无序交易，它使用 `TimeoutTimestamp` 进行重放保护。 +2D 随机数赋予每个账户多个独立的随机数通道。`NonceKey` 选择通道。`NonceKey = 0` 保留正常的 EVM 兼容序列，而协议将 `uint64` 范围的上限保留供其自身使用。`MaxUint64` 标记无序交易，该交易使用 `TimeoutTimestamp` 进行重放保护。 -该版本添加了 `CustomTx` 交易类型 `0x3F`，以及现有的 EVM 交易格式。协议保留的 `NonceKey` 范围也标识 VIP 通道交易。 +该版本添加了 `CustomTx`（交易类型 `0x3F`），与现有 EVM 交易格式并存。设置了第 63 位的 `NonceKey` 标识企业通道交易，`MaxUint64` 除外。 -保证块空间将每个块划分为 VIP、交易类型和具有单独 gas 配额的普通通道。治理通过一个 `MsgUpdateParams` 提案控制通道参数，接受的更新在下一个块中生效。如果没有通道配置，链将作为一个普通通道运行。 +保证的区块空间将每个区块划分为企业、交易类型和普通通道，并具有单独的燃气配额。治理通过一个 `MsgUpdateParams` 提案控制通道参数，接受的更新在下一个区块中生效。 -当验证器行为诚实且网络保持同步时，符合条件的 VIP 交易将获得确定性的下一块包含。阅读[保证块空间](/cn/explanation/guaranteed-blockspace)以了解通道和 nonce 模型。 +主网激活播种了 `max_blockspace_gas_weight = 20` 和一个权重为 `50` 的企业通道。它没有播种交易类型通道。当验证者行为诚实且网络保持同步时，符合条件的企业交易将获得确定性的下一区块包含。 -### 节点部署 +`StableSystem` 预编译现在暴露 `blockspaceLanes()`。任何客户端都可以通过 `eth_call` 查询活动通道注册表并重现协议的分类规则。 -MemIAVL 改变了状态存储，因此节点操作员必须迁移其现有数据。推荐的方法是本地快照导出和恢复。基准测试显示每个验证器平均停机时间为 19.4 秒。并行恢复变体将平均停机时间缩短到大约 2.6 秒。 +阅读[保证的区块空间](/cn/explanation/guaranteed-blockspace)了解通道模型，或阅读[StableSystem 参考](/cn/reference/system-transactions-api)了解查询 ABI。 -验证器可以按轮循顺序迁移，以保留至少三分之二的投票权。请遵循网络特定的升级说明，而不是将基准测试过程视为固定的运行手册。 +### 激活和节点配置 -### 延迟工作 +v1.8.0 处理程序运行模块迁移，启用 NonceKey 预编译，安装 EIP-2935 历史存储，并将 `max_gas_per_tx` 设置为 `40,000,000`。 -- **Gas 豁免交易类型通道**：零 gas 通道需要受信任的内存池准入控制。如果没有它，攻击者可能会提交无限的免费交易。 -- **发送者匹配优化**：后续版本可能会让全节点发送预先计算的发送者地址，从而避免在块提案期间重复签名恢复。 +该版本向 `config.toml` 和 `app.toml` 都添加了配置键。操作员必须在激活前安装 v1.8.0 模板，然后恢复其节点特定设置。对于记录的主网升级，不需要状态导出、导入或快照重置。 -:::note -v1.4.0 仍在审计和测试中。在主网升级之前，范围和时间可能会发生变化。跟踪[测试网版本历史记录](/cn/reference/testnet-version-history)以获取最新发布候选版本。 -::: +二进制文件强制关闭 `inter-block-cache`。归档节点操作员在安装默认 `app.toml` 模板后必须恢复其原始修剪设置。 -## v1.3.1 :badge[当前]{success} +### 可靠性和安全性变更 -一个向后兼容的补丁和当前的主网版本。它没有协调的升级高度，因此节点操作员可以随时通过替换二进制文件来采用它。 +- Nonce 与最终状态进行检查，关闭跨区块交易重放。 +- 提议处理在准入和共识阶段强制执行通道预算和每笔交易的燃气上限。 +- 顺序执行和 Block-STM 执行现在产生相同的累积 EVM 日志索引和 `LastResultsHash`。 +- JSON-RPC 对昂贵的请求、WebSocket 订阅、证据存储键和跟踪输出应用限制。 +- 流式区块结果和 `BlockResultsForLogs` 在大型日志查询期间限制内存使用。 +- MemIAVL 和 VersionDB 在版本间隙上关闭失败，并从中断的 WAL 或快照写入中安全恢复。 + +**谁需要采取行动**：在激活后加入或升级的节点必须使用 v1.8.0 二进制文件和配置模板。按照[升级节点](/cn/how-to/upgrade-node)并确认[主网版本历史](/cn/reference/mainnet-version-history)中的当前二进制文件。 + +## v1.3.1 + +一个向后兼容的补丁。它没有协调的升级高度，因此节点操作员可以通过随时替换二进制文件来采用它。 ## v1.3.0 -一个以安全为重点的状态破坏性升级，也使 gas 豁免功能更加灵活。gas 豁免的更改允许通过治理提案在以后引入新的合作伙伴（例如钱包和交易所），而无需每次都进行另一次状态破坏性升级。 +一个侧重于安全的状态破坏性升级，也使燃气豁免功能更加灵活。燃气豁免的更改允许新的合作伙伴（例如钱包和交易所）通过治理提案在以后加入，而不是每次都需要另一个状态破坏性升级。 -**谁需要采取行动**：所有节点操作员都在预定高度升级。请参阅[主网版本历史记录](/cn/reference/mainnet-version-history)以了解确切高度。 +**谁需要采取行动**：所有节点操作员都在计划高度升级。请参阅[主网版本历史](/cn/reference/mainnet-version-history)以获取确切的高度。 -**安全改进**： +**安全改进：** -- 不再注册非公共 JSON-RPC 命名空间，并且只有当 `AllowInsecureUnlock=true` 时才启用签名 API。 -- Gas 豁免输入得到加强：地址必须使用 EIP-55 规范格式，查询输入受到长度和格式限制，并且加强了包装类型、链 ID 和 EIP-7702 内部交易验证。 +- 不再注册非公共 JSON-RPC 命名空间，并且仅当 `AllowInsecureUnlock=true` 时才启用签名 API。 +- 燃气豁免输入得到强化：地址必须使用 EIP-55 规范格式，查询输入受长度和格式限制，并且加强了包装器类型、链 ID 和 EIP-7702 内部交易验证。 - 系统交易现在针对 `to` 地址和方法选择器进行验证，而不仅仅是 `from` 地址。这关闭了可能触发免手续费执行的路径。 -- Prague 预编译地址范围已添加到阻塞地址列表，未知预编译方法现在需要查询 gas。 +- Prague 预编译地址范围已添加到被阻止地址列表，并且未知预编译方法现在需要查询燃气。 -**错误修复和稳定性**： +**错误修复和稳定性：** -- 更正了失败的有状态预编译调用的 gas 核算。 +- 纠正了失败的有状态预编译调用的燃气核算。 - 解决了 ERC-20 内部调用失败后的退款禁用状态泄漏。 - 修复了预编译热集跟踪和 `COINBASE` 操作码行为。 -- 使 EIP-7702 授权回滚与规范保持一致。 +- 将 EIP-7702 授权回滚与规范对齐。 - 修复了报告 `from=0x0` 的系统交易响应、`feeHistory` 错误日志记录以及历史完整交易响应中的链 ID 一致性。 ## v1.2.2 -一个向后兼容的可选升级，使 StableChain 与官方上游共识版本保持一致，并清理了两种查询行为。 +一个向后兼容的可选升级，使 StableChain 与官方上游共识版本对齐，并清理了两个查询行为。 -**谁需要采取行动**：没有人需要。此升级无需治理提案。节点操作员可以在方便时通过替换二进制文件来采用它。 +**谁需要采取行动**：没有人需要。此升级不需要治理提案。节点操作员可以通过随时替换二进制文件来采用它。 -**更改**： +**变化：** -- 将 CometBFT 升级到官方 `v0.38.21`。这遵循了 v1.1.4 中早些时候发布的安全性补丁，并允许外部合作伙伴验证网络运行的确切共识版本。 -- 移除了 gas 豁免交易查询中的重复日志索引。 -- 为系统交易查询的 RPC 响应添加了安全措施。 +- 将 CometBFT 升级到官方 `v0.38.21`。这遵循 v1.1.4 中早些时候发布的安全性补丁，并允许外部合作伙伴验证网络运行的确切共识版本。 +- 删除了燃气豁免交易查询中的重复日志索引。 +- 为系统交易查询的 RPC 响应添加了保护措施。 ## v1.2.1 -一个向后兼容的热修复，弥补了两个如果被利用可能会导致链停机的漏洞。 +一个向后兼容的热修复，它弥补了两个问题，如果被利用，可能会导致链停止。 -**谁需要采取行动**：验证器必须升级。对于其他节点操作员，包括 RPC 提供者，升级是可选的。它不需要治理提案。 +**谁需要采取行动**：验证者必须升级。对于包括 RPC 提供商在内的其他节点操作员，升级是可选的。它不需要治理提案。 -**修复**： +**修复：** -- 修复了系统交易欺骗路径，用户可以将 `MsgEthereumTx.From == 0x1` 设置为绕过身份验证并调用 только系统预编译，然后使用欺骗交易反复强制 `ProcessProposal` 拒绝块并停止共识。 -- 修复了内存池中毒链停机，其中 `ExtensionOptionsWaiver` 交易可以绕过 `CheckTx` 但导致 `ProcessProposal` 拒绝整个块。 +- 关闭了系统交易欺骗路径，用户可以通过设置 `MsgEthereumTx.From == 0x1` 来绕过身份验证并调用仅限系统的预编译，然后使用欺骗性交易反复强制 `ProcessProposal` 拒绝区块并使共识停滞。 +- 修复了内存池中毒导致的链停止问题，其中 `ExtensionOptionsWaiver` 交易可以通过 `CheckTx` 但导致 `ProcessProposal` 拒绝整个区块。 -## 更早的版本 +## 早期版本 -详细的发布说明从 v1.2.1 开始。对于 v1.2.0 和更早的版本，包括创世版本，请参阅版本历史记录表中的二进制文件、提交哈希和升级高度： +详细的发布说明从 v1.2.1 开始。对于 v1.2.0 及更早版本，包括创世版本，请参阅版本历史表以获取二进制文件、提交哈希和升级高度： -- [主网版本历史记录](/cn/reference/mainnet-version-history)：每个主网版本及其二进制文件和升级高度。 -- [测试网版本历史记录](/cn/reference/testnet-version-history)：每个测试网版本，包括发布候选版本。 +- [主网版本历史](/cn/reference/mainnet-version-history)：每个主网版本及其二进制文件和升级高度。 +- [测试网版本历史](/cn/reference/testnet-version-history)：每个测试网版本，包括候选发布版本。 ## 接下来去哪里 - [**升级节点**](/cn/how-to/upgrade-node)：按照分步过程将您的节点升级到新版本。 -- [**主网版本历史记录**](/cn/reference/mainnet-version-history)：查找每个主网版本的提交哈希、二进制文件和升级高度。 +- [**主网版本历史**](/cn/reference/mainnet-version-history)：查找每个主网版本的提交哈希、二进制文件和升级高度。 - [**主网信息**](/cn/reference/mainnet-information)：获取链 ID、RPC 端点和当前网络参数。 diff --git a/docs/pages/cn/reference/system-transactions-api.mdx b/docs/pages/cn/reference/system-transactions-api.mdx index dcb44d0..a98cc51 100644 --- a/docs/pages/cn/reference/system-transactions-api.mdx +++ b/docs/pages/cn/reference/system-transactions-api.mdx @@ -1,360 +1,179 @@ --- source_path: reference/system-transactions-api.mdx -source_sha: 14ee7e0538b5323f809b63454db35d954d8db488 +source_sha: a8f5d4cbdfe52da5101751e74b8efb7a8390d16d title: "系统交易参考" -description: "StableSystem 预编译参考：接口、发送者授权、批处理限制和 gas 计费。" +description: "通过 StableSystem 预编译查询有保证的块空间通道并消费协议事件。" diataxis: "reference" --- # 系统交易参考 +`StableSystem` 预编译通过固定的 EVM 合约接口暴露 Stable 协议数据和事件。在 v1.8.0 中，任何客户端都可以查询有保证的块空间注册表，而只有协议生成的交易才能发出系统日志。 + :::note -**概念：** 关于系统交易如何将 SDK 事件桥接到 EVM 以及为什么这很重要，请参阅[系统交易](/cn/explanation/system-transactions)。 +有关系统交易流程及其安全模型，请参阅[系统交易](/cn/explanation/system-transactions)。 ::: -## 摘要 - -系统交易为 Stable 协议提供了一种为 Stable SDK 操作发出 EVM 事件的方式。当诸如解绑完成之类的质押事件在 SDK 层发生时，协议会自动生成发出相应事件的 EVM 交易。这使得这些操作对 EVM 工具和应用程序完全可见。 - -## 动机 - -你和你在 Stable 上的应用程序期望通过标准的 EVM 接口（如 `eth_getLogs`）来监控区块链事件。但关键操作发生在 Stable SDK 模块中，而这些模块本身不会自然地发出 EVM 事件。这造成了可见性缺口：EVM dApp 无法轻松追踪用户的代币何时完成解绑。 - -系统交易弥补了这一缺口。当质押模块完成一个解绑操作时，Stable 的 x/stable 模块会检测到该事件并生成一个调用 StableSystem 预编译（`0x0000000000000000000000000000000000009999`）的系统交易。然后，预编译会发出任何 dApp 都可以订阅的正确 EVM 事件。系统交易以一个特殊的发送者地址（`0x8888888888888888888888888888888888888888`）运行，只有协议才能使用该地址。这可以防止任何人伪造协议事件，同时保持事件发出过程无需信任且可在链上验证。 - -## 规范 +## 合约 -系统交易通过三个主要组件运作：x/stable 模块的 EndBlocker、PrepareProposal 处理器以及 StableSystem 预编译。 +预编译在主网和测试网上使用相同的地址： -### 架构概览 +`0x0000000000000000000000000000000000009999` -system-transaction-architecture +| **方法** | **选择器** | **访问** | **Gas 限制** | **目的** | +| :--- | :--- | :--- | :--- | :--- | +| `blockspaceLanes()` | `0x2c0ac3be` | 任何人，只读 | `10,000` | 返回活跃的企业和交易类型通道注册表。 | +| `notifySystemTxLogs()` | `0xe8e983b7` | 仅限系统交易发送方 | `50,000` | 处理最多 100 个排队的系统日志条目。 | -### StableSystem 预编译 - -StableSystem 预编译位于 `0x0000000000000000000000000000000000009999`，处理需要发出 EVM 事件的协议级操作。目前它支持解绑完成通知。 +使用此 Solidity 接口获取 v1.8.0 ABI： ```solidity -interface IStableSystem { - /// @notice Processes queued unbonding completions and emits EVM events - /// @param blockHeight The block height at which to process completions - /// @dev Only callable by system transactions (from = 0x8888888888888888888888888888888888888888) - /// @dev Processes up to 100 completions per call - /// @dev Automatically deletes processed completions from the queue - function notifyUnbondingCompletions(int64 blockHeight) external; - - /// @notice Emitted when an unbonding operation completes - /// @param delegator The address that delegated the tokens - /// @param validator The validator address the tokens were delegated to - /// @param amount The amount of tokens that finished unbonding (in uusdc) - event UnbondingCompleted( - address indexed delegator, - address indexed validator, - uint256 amount - ); - - /// @notice The caller is not authorized (not system transaction sender) - error Unauthorized(); +// SAFE: This interface matches the Stable v1.8.0 StableSystem ABI. +struct EnterpriseLane { + uint64 id; + string name; + uint32 weight; } -``` - -### 系统交易发送者 - -系统交易使用 `0x8888888888888888888888888888888888888888` 作为发送者地址。该地址： - -- 不需要签名验证 -- 只能由在 PrepareProposal 中创建的交易使用 -- 无法被用户或合约伪造 -- 通过 SystemTxDecorator ante 处理器跳过手续费扣除 - -EVM 通过检查 `msg.sender == 0x8888888888888888888888888888888888888888` 来识别系统交易。预编译可以利用这一点来限制仅协议可执行的操作。 - -### 事件驱动流程 - -当用户的解绑期完成时，会发生以下情况： - -1. **Stable SDK 层：** 质押模块的 EndBlocker 完成解绑，并发出 EventTypeCompleteUnbonding，其中包含委托人地址、验证者地址和金额。 -2. **检测：** x/stable 模块的 EndBlocker 在质押之后运行，并扫描区块事件日志中的解绑事件。对于每个完成的解绑，它都会在状态中排入一个条目，包含委托人地址、验证者地址、金额和区块高度。 -3. **系统交易生成**：在下一个区块的 PrepareProposal 中，应用查询所有排队的完成项。如果存在任何完成项，它会创建一个调用 StableSystem.notifyUnbondingCompletions(blockHeight) 的系统交易，并传入当前区块高度。该交易位于区块的最前面，在任何用户交易之前。 -4. **执行：** 在区块执行期间，系统交易最先运行。预编译查询该区块高度下排队的完成项的状态，为每一项（最多 100 项）发出一个 UnbondingCompleted 事件，并将它们从队列中删除。 -5. **EVM 可见性：** 这些事件出现在交易收据和日志中，可被 eth\_getLogs 查询、区块浏览器以及任何监控 StableSystem 预编译的应用程序看到。 - -### 批处理 -为了防止区块变得过大，系统每个区块最多处理 100 个解绑完成项。如果有 150 个完成项排队： - -- 区块 N：创建处理完成项 0-99 的系统交易 -- 区块 N+1：创建处理完成项 100-149 的系统交易 - -预编译直接查询状态，而不是在 calldata 中接收完成数据。这使得交易大小可预测，并将数据从昂贵的 calldata 转移到更便宜的状态读取。 - -## 使用示例 - -最常见的用例是一个质押仪表盘，需要在用户的解绑期完成时通知用户。以下是如何为解绑完成设置监听器。 - -```javascript -import { ethers } from 'ethers'; - -// StableSystem precompile address -const STABLE_SYSTEM_ADDRESS = '0x0000000000000000000000000000000000009999'; - -// ABI for the UnbondingCompleted event -const STABLE_SYSTEM_ABI = [ - 'event UnbondingCompleted(address indexed delegator, address indexed validator, uint256 amount)' -]; - -// Connect to the Stable network -const provider = new ethers.JsonRpcProvider('https://rpc.testnet.stable.xyz'); -const stableSystem = new ethers.Contract( - STABLE_SYSTEM_ADDRESS, - STABLE_SYSTEM_ABI, - provider -); - -// Subscribe to all unbonding completions -stableSystem.on('UnbondingCompleted', (delegator, validator, amount, event) => { - console.log('Unbonding completed!'); - console.log('Delegator:', delegator); - console.log('Validator:', validator); - console.log('Amount:', ethers.formatEther(amount), 'tokens'); - console.log('Block:', event.log.blockNumber); - console.log('Tx Hash:', event.log.transactionHash); -}); - -``` - -每当任何用户的解绑完成时，此监听器都会触发。对于生产环境的 dApp，请按如下所示为特定用户过滤事件。 - -### 为特定用户过滤事件 - -要仅接收特定委托人地址的事件，请使用索引事件参数来创建过滤器： - -```javascript -// Only watch unbondings for a specific user -const userAddress = '0xabcd...'; - -const filter = stableSystem.filters.UnbondingCompleted(userAddress); - -stableSystem.on(filter, (delegator, validator, amount, event) => { - // This only fires for the specified user's unbondings - showNotification(`Your unbonding of ${ethers.formatEther(amount)} tokens completed!`); - refreshUserBalance(userAddress); -}); -``` - -如果你正在构建一个特定于验证者的仪表盘，也可以按验证者过滤： - -```javascript -// Watch all unbondings from a specific validator -const validatorAddress = '0x1234...'; - -const validatorFilter = stableSystem.filters.UnbondingCompleted(null, validatorAddress); - -stableSystem.on(validatorFilter, (delegator, validator, amount) => { - updateValidatorStats(validator, amount); -}); -``` - -### 查询历史事件 - -如果你的 dApp 需要显示过去解绑完成的历史记录，你可以使用带有区块范围的事件过滤器来查询历史事件： - -```javascript -// Get all unbondings for a user in the last 1000 blocks -const currentBlock = await provider.getBlockNumber(); -const filter = stableSystem.filters.UnbondingCompleted(userAddress); - -const events = await stableSystem.queryFilter( - filter, - currentBlock - 1000, - currentBlock -); - -const unbondingHistory = events.map(event => ({ - delegator: event.args.delegator, - validator: event.args.validator, - amount: ethers.formatEther(event.args.amount), - blockNumber: event.blockNumber, - txHash: event.transactionHash -})); - -console.log('Recent unbondings:', unbondingHistory); - -``` - -## 集成指南 - -### 步骤 1：添加 Stable System 合约接口 +struct TxTypeLane { + uint64 id; + string name; + address[] toAddrs; + bytes4[] methods; + uint8[] txTypes; + uint64[] nonceKeys; + address[] senders; + uint32 weight; + bool noOverflow; +} -首先，将 StableSystem 预编译接口添加到你的项目中。如果你使用的是 Foundry 或 Hardhat，请创建一个新的接口文件： +struct BlockspaceLanes { + uint32 maxBlockspaceGasWeight; + EnterpriseLane[] enterpriseLanes; + TxTypeLane[] txTypeLanes; +} -```solidity interface IStableSystem { event UnbondingCompleted( address indexed delegator, address indexed validator, + uint64 indexed originBlockHeight, uint256 amount ); -} -``` - -如果你正在构建一个没有 Solidity 合约的纯前端 dApp，你只需要事件的 ABI 片段： - -```javascript -const STABLE_SYSTEM_ABI = [ - 'event UnbondingCompleted(address indexed delegator, address indexed validator, uint256 amount)' -]; -``` - -### 步骤 2：设置事件监听器 - -初始化你的 ethers.js provider，并创建一个指向 StableSystem 预编译地址的合约实例。该预编译在 Stable 测试网和 Stable 主网上始终部署于 `0x00000000000....0000009999`。 - -*注意：该预编译尚未部署在 Stable 主网上，将在 v1.2.0 升级后提供。* - -```javascript -const provider = new ethers.JsonRpcProvider(RPC_URL); -const stableSystem = new ethers.Contract( - '0x0000000000000000000000000000000000009999', - STABLE_SYSTEM_ABI, - provider -); -``` -### 步骤 3：在应用程序逻辑中处理事件 + function notifySystemTxLogs() external; -订阅事件并相应地更新你的应用程序状态。常见的模式包括： - -- **余额更新**：当解绑完成时，刷新用户的代币余额 -- **通知系统**：当用户的解绑完成时显示弹窗通知 -- **仪表盘统计**：实时更新质押指标和图表 -- **交易历史**：将已完成的解绑添加到用户的活动动态中 - -### 步骤 4：处理连接问题 - -由于事件订阅依赖于持久的 websocket 连接，请为生产环境的 dApp 实现重连逻辑： - -```javascript -let reconnectAttempts = 0; -const MAX_RECONNECT_ATTEMPTS = 5; - -function setupEventListener() { - const provider = new ethers.WebSocketProvider('wss://rpc.testnet.stable.xyz'); - - provider.on('error', (error) => { - console.error('Provider error:', error); - if (reconnectAttempts < MAX_RECONNECT_ATTEMPTS) { - reconnectAttempts++; - setTimeout(() => setupEventListener(), 5000); - } - }); - - const stableSystem = new ethers.Contract( - '0x0000000000000000000000000000000000009999', - STABLE_SYSTEM_ABI, - provider - ); - - stableSystem.on('UnbondingCompleted', handleUnbonding); + function blockspaceLanes() + external + view + returns (BlockspaceLanes memory lanes); } ``` -## 为什么采用这种方法？ - -### 与自定义索引器相比 - -以前，Stable SDK 要求你运行自定义索引器来监视 SDK 事件并将它们存储在数据库中。这增加了运维开销并引入了潜在的故障点。 - -有了系统交易，就不再需要单独的索引器基础设施。事件通过 EVM 的日志系统原生可用，而每个 RPC 节点都已经对其进行了索引和服务。任何标准的 web3 库都可以订阅这些事件，而无需额外的工具。 +## `blockspaceLanes()` -### 与轮询 SDK 端点相比 +`blockspaceLanes()` 返回在块提案和验证期间使用的由治理控制的通道注册表。它是一个普通的 `eth_call`，而不是自定义的 JSON-RPC 方法，并且不需要企业网关。 -如果没有系统交易，EVM dApp 将需要定期调用 Stable SDK REST 端点来检查解绑期是否已完成。这会带来几个问题： +两个通道数组都按 `id` 升序排序。较低的 ID 具有较高的匹配优先级。 -- **延迟增加**：5-10 秒的轮询间隔意味着用户可能要等待那么长时间才能看到更新 -- **负载更高**：每个 dApp 实例轮询端点都会增加 RPC 基础设施的负载 -- **复杂性**：dApp 需要同时处理 web3 provider（用于 EVM 交互）和 Stable SDK REST 客户端（用于 SDK 查询） -- **没有实时更新**：轮询本质上无法提供即时通知 +### 返回值 -系统交易通过 dApp 已经用于 EVM 交互的相同 websocket 连接提供实时事件通知。这简化了开发者体验并降低了基础设施成本。 +| **字段** | **类型** | **描述** | +| :--- | :--- | :--- | +| `maxBlockspaceGasWeight` | `uint32` | 所有配置通道中保留的块 gas 限制的百分比，从 0 到 100。 | +| `enterpriseLanes` | `EnterpriseLane[]` | 企业通道定义。治理最多允许一个企业通道。 | +| `txTypeLanes` | `TxTypeLane[]` | 匹配规则检查交易字段的通道。 | -## 安全保证 +### 企业通道 -### 无需信任的事件发出 +任何 `CustomTx`，其 `NonceKey` 的第 63 位设置，都路由到配置的企业通道，除了 `MaxUint64`。较低的 63 位选择一个独立的 nonce 通道，而不是一个通道。 -系统交易在 `PrepareProposal` ABCI 阶段创建，只有验证者才能执行该阶段。用户提交的交易无法伪造系统发送者地址（`0x8888888888888888888888888888888888888888`）。EVM 的状态转换逻辑强制规定只有发往 StableSystem 预编译地址的交易才能跳过签名验证。 +| **字段** | **类型** | **描述** | +| :--- | :--- | :--- | +| `id` | `uint64` | 耗尽顺序优先级和标识符。 | +| `name` | `string` | 人类可读的通道名称。 | +| `weight` | `uint32` | 分配给通道的保留块空间池的百分比，从 0 到 100。 | -这意味着： +### 交易类型通道 -- 用户无法伪造解绑完成事件 -- 用户无法从自己的交易中调用 `notifyUnbondingCompletions` -- 发出 `UnbondingCompleted` 事件的唯一方式是 Stable SDK 质押模块中实际完成一次解绑 +交易必须匹配所有已填充的匹配器字段。一个字段内的条目是替代项，空匹配器是通配符。 -### 没有额外的信任假设 +| **字段** | **类型** | **描述** | +| :--- | :--- | :--- | +| `id` | `uint64` | 通道优先级和标识符。较低的 ID 优先匹配。 | +| `name` | `string` | 人类可读的通道名称。 | +| `toAddrs` | `address[]` | 允许的目标地址。空值匹配任何目标。 | +| `methods` | `bytes4[]` | 允许的四字节函数选择器。空值匹配任何选择器。 | +| `txTypes` | `uint8[]` | 允许的交易格式。空值或 `0` 条目匹配任何格式。 | +| `nonceKeys` | `uint64[]` | 允许的 nonce 键。空值或 `0` 条目匹配任何键。 | +| `senders` | `address[]` | 允许的发送方地址。空值匹配任何发送方。 | +| `weight` | `uint32` | 分配给通道的保留块空间池的百分比，从 0 到 100。 | +| `noOverflow` | `bool` | 当为 `true` 时，未使用的容量不会级联到后续通道。 | -系统交易不会在区块链共识所需的基础上引入新的安全假设。如果你信任验证者正确地执行区块，你就可以信任系统交易事件准确地反映了 Stable SDK 的状态变化。 +`txTypes` 使用这些 `TxFormat` 值： -事件发出过程是确定性的：给定 `EndBlock` 中相同的 SDK 事件，所有诚实的验证者都会在 `PrepareProposal` 期间生成相同的系统交易。共识机制确保验证者就要包含哪些系统交易达成一致。 +| **值** | **交易格式** | **EVM 类型** | +| :--- | :--- | :--- | +| `0` | 通配符 | 任何 | +| `1` | 传统 | `0x00` | +| `2` | 访问列表 | `0x01` | +| `3` | 动态费用 | `0x02` | +| `4` | 设置代码 | `0x04` | +| `5` | 二维 nonce | `0x3F` | -### 区块最终性 +### 查询注册表 -Stable 区块链通过 StableBFT 的共识机制实现快速最终性。一旦区块被提交，它立即成为最终状态且无法重组。这意味着一旦你收到 `UnbondingCompleted` 事件，你就可以信任它是永久性的。 +使用 Foundry 的 `cast` 命令调用预编译： -无需像在概率最终性链上那样等待多次确认。dApp 可以在收到事件后立即更新用户余额并显示通知。 - -## 性能与限制 - -### 批处理大小约束 - -每个区块通过系统交易最多处理 100 个解绑完成项。这一限制的存在是为了防止在解绑活动高峰期间区块大小无限制增长。 - -实际上，假设平均出块时间为 0.7 秒，每个区块 100 个完成项可提供每分钟约 9000 个完成项的吞吐量。正常的质押活动很少达到这一限制。在特殊情况下，完成项可能会排队数个区块才能完全处理。 - -### Gas 消耗 - -系统交易在执行期间消耗 gas，这会计入区块的 gas 限制中。gas 成本与处理的完成项数量呈线性关系： - -- 基础函数调用：约 21,000 gas -- 每个事件发出：约 3,000 gas -- 读取状态：每个完成项约 2,000 gas - -一个完整的 100 个完成项批次消耗约 521,000 gas。由于 Stable 的区块 gas 限制为 100,000,000，这还不到可用区块空间的 0.6%。 - -### 通知延迟 +```bash +cast call \ + 0x0000000000000000000000000000000000009999 \ + "blockspaceLanes()((uint32,(uint64,string,uint32)[],(uint64,string,address[],bytes4[],uint8[],uint64[],address[],uint32,bool)[]))" \ + --rpc-url https://rpc.stable.xyz +``` -当解绑期在区块 N 期间完成时： +v1.8.0 主网激活时，播种了一个 20% 的保留池和一个企业通道，该通道占用池的 50%。治理可以更改此输出。 -1. Stable 模块的 `EndBlock` 在区块 N 的状态中将完成项排队 -2. 区块 N+1 的 `PrepareProposal` 创建一个系统交易 -3. 系统交易在区块 N+1 期间执行，发出事件 +```text +(20, [(1, "enterprise", 50)], []) +``` -这意味着在解绑完成和 EVM 事件被发出之间存在一个区块的延迟（约 0.7 秒）。对于大多数用例来说，这一延迟是可以接受的，因为解绑期本身就是 7 天。 +## `notifySystemTxLogs()` -### 高负载场景 +`notifySystemTxLogs()` 从状态中读取排队的协议日志条目，每次调用最多处理 100 个。它不接受任何参数，也不返回任何值。 -如果解绑完成项的到达速度快于每个区块 100 个，它们会在队列中累积。队列按 FIFO 顺序处理，因此最旧的完成项总是最先被通知。 +只有发送方为 `0x0000000000000000000000000000000000000001` 的系统交易才能调用此方法。来自用户或合约的调用将回滚。 -在持续的高负载期间，队列可能会暂时增长。然而，一旦峰值消退，后续完成项较少的区块将逐渐排空队列。该系统旨在处理突发情况而不丢失事件。 +当解除绑定完成时，流程如下： -## 未来扩展 +1. 质押模块完成操作并记录其 SDK 事件。 +2. `x/stable` 模块将事件数据及其原始块高排入队列。 +3. 下一个块提议者创建一个调用 `notifySystemTxLogs()` 的系统交易。 +4. 预编译为最多 100 个排队条目发出 EVM 日志。 +5. 客户端通过 `eth_getLogs`、WebSocket 订阅或区块浏览器读取日志。 -系统交易机制为将任何 Stable SDK 操作桥接到 EVM 事件空间提供了一种通用模式。虽然目前仅用于解绑完成，但该架构可以扩展以涵盖更多用例： +超出批处理限制的条目将继续排队等待后续区块。 -### 质押操作 +## `UnbondingCompleted` 事件 -除了解绑之外，其他质押事件也可以发出 EVM 通知： +| **参数** | **类型** | **索引** | **描述** | +| :--- | :--- | :--- | :--- | +| `delegator` | `address` | 是 | 其委托代币完成解除绑定的地址。 | +| `validator` | `address` | 是 | 从其验证者操作员地址派生的验证者地址。 | +| `originBlockHeight` | `uint64` | 是 | SDK 层解除绑定最初完成时的块高。 | +| `amount` | `uint256` | 否 | 完成解除绑定的数量。 | -- 验证者更改佣金率 -- 验证者监禁和解除监禁 +EVM 日志出现在包含系统交易的区块中。当您需要原始 SDK 事件的高度时，请使用 `originBlockHeight`。 -### 治理执行 +## 安全模型 -当治理提案通过并执行时，系统交易可以发出带有提案 ID 和执行结果的事件。这将允许 dApp 对参数更改或升级做出反应，而无需轮询治理模块。 +- 协议在区块提案期间创建系统交易。 +- EVM 状态转换规则为系统交易保留发送方 `0x0000000000000000000000000000000000000001`。 +- 用户交易无法伪造发送方或成功调用 `notifySystemTxLogs()`。 +- `blockspaceLanes()` 有意公开，不能更改状态。 -### 通用事件桥 +## 下一步 -该模式可以泛化为一个可配置的事件桥，其中每个模块注册哪些 SDK 事件应被镜像到 EVM。这将提供对所有 Stable SDK 操作的全面可见性，而无需为每个模块定制逻辑。关键的架构原则是系统交易始终是协议级功能，仅由验证者在区块提议期间创建。 +- [**有保证的块空间**](/cn/explanation/guaranteed-blockspace)：了解返回的权重和匹配器如何控制保留容量。 +- [**跟踪解除绑定完成**](/cn/how-to/track-unbonding)：订阅 `UnbondingCompleted` 并查询历史事件。 +- [**系统交易**](/cn/explanation/system-transactions)：了解协议事件如何成为 EVM 日志。 diff --git a/docs/pages/cn/reference/testnet-version-history.mdx b/docs/pages/cn/reference/testnet-version-history.mdx index fc7d26a..85feee8 100755 --- a/docs/pages/cn/reference/testnet-version-history.mdx +++ b/docs/pages/cn/reference/testnet-version-history.mdx @@ -1,30 +1,31 @@ --- source_path: reference/testnet-version-history.mdx -source_sha: 050f5652f63ca9f7d67ab44ad1b5798f243fc236 +source_sha: a341ad196aefb3dbe2c44e3df89474344c069155 title: 版本历史 -description: "Stable 测试网的版本历史和升级计划。" +description: "查找 Stable 测试网发布、升级高度、提交和可下载的节点二进制文件。" diataxis: "reference" --- # 版本历史 -Stable 测试网的完整版本历史和相关文档。 +Stable 测试网目前运行 `v1.8.0-rc1` 版本。使用此历史记录可以识别每个版本、其激活高度及其节点二进制文件。 ## 当前版本信息 - **当前版本**：`v1.8.0-rc1` -- **下次升级**：`TBD` +- **下一次升级**：`TBD` - **升级高度**：`TBD` - **预计时间**：`TBD` ## 版本历史 -### 当前及以前的版本 +### 当前和以前的版本 -| 版本 | 提交 | 升级高度 | 二进制文件 | 状态 | -|---------|--------|----------------|--------|-------------------------------| +| **版本** | **提交** | **升级高度** | **二进制文件** | **状态** | +| :--- | :--- | :--- | :--- | :--- | | **v1.8.0-rc1** | `a07c551` | 64,956,000 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.8.0-rc1-linux-amd64-testnet.tar.gz) / [ARM64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.8.0-rc1-linux-arm64-testnet.tar.gz) | 当前 | | **v1.8.0-rc0** | `4cc6813` | 61,689,000 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.8.0-rc0-linux-amd64-testnet.tar.gz) / [ARM64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.8.0-rc0-linux-arm64-testnet.tar.gz) | | +| **v1.4.0-rc2** | `75c2934` | 60,110,000 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.4.0-rc2-linux-amd64-testnet.tar.gz) / [ARM64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.4.0-rc2-linux-arm64-testnet.tar.gz) | | | **v1.4.0-rc1** | `4744d2d` | 58,520,000 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.4.0-rc1-linux-amd64-testnet.tar.gz) / [ARM64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.4.0-rc1-linux-arm64-testnet.tar.gz) | | | **v1.4.0-rc0** | `83b5efb` | 57,806,500 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.4.0-rc0-linux-amd64-testnet.tar.gz) / [ARM64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.4.0-rc0-linux-arm64-testnet.tar.gz) | | | **v1.3.1-rc0** | `75bb546` | - | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.3.1-rc0-linux-amd64-testnet.tar.gz) / [ARM64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.3.1-rc0-linux-arm64-testnet.tar.gz) | | @@ -40,15 +41,15 @@ Stable 测试网的完整版本历史和相关文档。 | **v0.8.1** | `1eb65d5` | 30,770,000 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.8.1-linux-amd64-testnet.tar.gz) / [ARM64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.8.1-linux-arm64-testnet.tar.gz) | | | **v0.8.0** | `e55efb6` | 29,410,999 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.8.0-linux-amd64-testnet.tar.gz) / [ARM64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.8.0-linux-arm64-testnet.tar.gz) | 银行预编译增强 | | **v0.7.2** | `3c53e14` | 27,258,000 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.7.2-linux-amd64-testnet.tar.gz) / [ARM64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.7.2-linux-arm64-testnet.tar.gz) | StableBFT 集成 | -| **v0.6.0** | `5cc1ad6` | 19,587,000 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.6.0-linux-amd64-testnet.tar.gz) | 小错误修复 | -| **v0.5.0** | `919281d` | 18,719,000 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.5.0-linux-amd64-testnet.tar.gz) | 小错误修复 | +| **v0.6.0** | `5cc1ad6` | 19,587,000 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.6.0-linux-amd64-testnet.tar.gz) | 小幅修复 | +| **v0.5.0** | `919281d` | 18,719,000 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.5.0-linux-amd64-testnet.tar.gz) | 小幅修复 | | **v0.4.0** | `c6240c0` | 18,666,150 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.4.0-linux-amd64-testnet.tar.gz) | Stable SDK v0.53.4 | | **v0.3.0** | `a4f5ac5` | 9,166,131 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.3.0-linux-amd64-testnet.tar.gz) | EVM 值传输允许列表 | | **v0.2.1** | `53e6e073` | - | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.2.1-linux-amd64-testnet.tar.gz) | 非破坏性更新 | | **v0.2.0** | `8bdd771` | 8,956,584 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.2.0-linux-amd64-testnet.tar.gz) | 功能更新 | | **v0.1.0** | `10dfg542` | 创世 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.1.0-linux-amd64-testnet.tar.gz) | 创世 (2025-04-07) | -## 相关文档 +## 下一步 -- [升级指南](/cn/how-to/upgrade-node) - 分步升级程序 -- [测试网信息](/cn/reference/testnet-information) - 当前网络详情 +- [**升级节点**](/cn/how-to/upgrade-node)：替换协调网络升级的节点二进制文件和配置文件。 +- [**测试网信息**](/cn/reference/testnet-information)：使用当前链 ID、端点和合约地址连接到 Stable 测试网。 diff --git a/docs/pages/ko/explanation/core-concepts.mdx b/docs/pages/ko/explanation/core-concepts.mdx index 1e3afa0..1b0e2ca 100755 --- a/docs/pages/ko/explanation/core-concepts.mdx +++ b/docs/pages/ko/explanation/core-concepts.mdx @@ -1,58 +1,59 @@ --- source_path: explanation/core-concepts.mdx -source_sha: 45b22f6b8de51a67dbe1ed9ffb14d57302775f8c +source_sha: 8af8d2892f4a217e2908aacda0f16699f1a4bc63 title: "핵심 개념" -description: "Stable을 구축하기 전에 USDT0를 Gas로 사용, 보장된 블록 공간, 전송 집계 및 EVM 호환성이라는 4가지 핵심 개념을 이해하세요." +description: "구축하기 전에 Stable의 네 가지 핵심 개념을 이해하세요: 가스로서의 USDT0, 보장된 블록 공간, 전송 집계 및 EVM 호환성." diataxis: "explanation" --- # 핵심 개념 -4가지 개념만 알아도 구축을 시작할 수 있습니다. 각 섹션에서는 개념을 정의하고, 보여주고, 전체 참조에 연결합니다. +네 가지 개념만 알면 빌드를 시작할 수 있습니다. 각 섹션에서는 개념을 정의하고, 이를 보여주며, 전체 참조에 연결합니다. -## Gas로 USDT0 사용 +## 가스로서의 USDT0 -거래 수수료는 이미 보유하고 거래하고 있는 자산과 동일한 USDT0로 지불합니다. 자금을 조달하거나 관리할 두 번째 토큰은 없습니다. +거래 수수료는 이미 보유하고 거래하는 자산과 동일한 USDT0으로 지불합니다. 자금을 조달하거나 관리해야 하는 두 번째 토큰은 없습니다. -USDT0는 네이티브 Gas 자산(18진수, `address(x).balance`를 통해 읽음)이자 ERC-20 토큰(6진수, `USDT0.balanceOf(x)`를 통해 읽음)입니다. 두 인터페이스는 동일한 기본 잔액에서 작동하며, 프로토콜은 12자리 정밀도 차이를 자동으로 조정합니다. +USDT0은 기본 가스 자산(18진수, `address(x).balance`를 통해 읽음)이자 ERC-20 토큰(6진수, `USDT0.balanceOf(x)`를 통해 읽음)입니다. 두 인터페이스는 동일한 기본 잔액에서 작동하며, 프로토콜은 12자리 정밀도 차이를 자동으로 조정합니다. ```solidity -// 둘 다 동일한 잔액을 읽습니다: +// SAFE: 두 읽기 모두 Stable의 정식 잔액 인터페이스를 사용합니다. +// 둘 다 동일한 잔액을 읽습니다. uint256 native = address(user).balance; // 18 decimals uint256 erc20 = IERC20(USDT0).balanceOf(user); // 6 decimals ``` :::warning -잔액 조정은 예비 주소 `0x5113954bbC0eD721F1C68671EBa3d91e9e9bF7b5`에서 추가 `Transfer` 이벤트를 발생시킵니다. `Transfer` 이벤트를 재생하는 인덱서 (Indexer)는 이 주소로의 전송 및 이 주소로부터의 전송을 필터링해야 합니다. 그렇지 않으면 잔액이 자동으로 이중으로 계산됩니다. +잔액 조정은 예약 주소 `0x5113954bbC0eD721F1C68671EBa3d91e9e9bF7b5`에서 추가 `Transfer` 이벤트를 발생시킵니다. `Transfer` 이벤트를 재생하는 인덱서는 이 주소로의 전송 및 이 주소로부터의 전송을 필터링해야 합니다. 그렇지 않으면 잔액을 자동으로 이중으로 계산합니다. ::: -더 읽어보기: [Gas 토큰으로서의 USDT0](/ko/explanation/usdt-as-gas-token) · [Stable에서의 USDT0 동작](/ko/explanation/usdt0-behavior). +자세히 보기: [가스로서의 USDT0](/ko/explanation/usdt-as-gas-token) · [Stable의 USDT0 동작](/ko/explanation/usdt0-behavior). ## 보장된 블록 공간 -Stable v1.4.0은 각 블록 내에서 적격 우선 작업 부하에 대한 Gas 할당량을 예약할 수 있습니다. 일반 트래픽은 혼잡 시 이 VIP-레인 용량을 사용할 수 없습니다. +Stable v1.8.0은 적격 우선 워크로드를 위해 각 블록 내에 가스 할당량을 예약합니다. 일반 트래픽은 혼잡 시 이 엔터프라이즈 레인 용량을 사용할 수 없습니다. -표준 EVM 트랜잭션은 기본 논스 채널 `NonceKey = 0`을 계속 사용합니다. 적격 우선 흐름은 `CustomTx` 유형 `0x3F` 및 VIP 레인을 식별하는 프로토콜 예약 `NonceKey`를 사용합니다. +표준 EVM 트랜잭션은 기본 논스 채널인 `NonceKey = 0`을 계속 사용합니다. 적격 우선 흐름은 `CustomTx` 유형 `0x3F`와 63비트가 설정된 `NonceKey`를 사용합니다. -거버넌스는 레인과 할당량을 구성합니다. 구성 없이는 모든 트랜잭션이 하나의 일반 레인을 사용합니다. 이 기능은 현재 v1.4.0 테스트넷 릴리스 후보에 있으며, 메인넷 일정은 보류 중입니다. +거버넌스는 레인과 할당량을 구성합니다. 보장된 블록 공간은 메인넷과 테스트넷에서 활성화되어 있으며, `StableSystem.blockspaceLanes()`는 활성 구성을 반환합니다. -더 읽어보기: [보장된 블록 공간](/ko/explanation/guaranteed-blockspace). +자세히 보기: [보장된 블록 공간](/ko/explanation/guaranteed-blockspace). -## USDT 전송 집계기 +## USDT 전송 애그리게이터 -대용량 USDT0 전송은 MapReduce에서 영감을 받은 파이프라인을 사용하여 일괄 처리되고 병렬로 검증됩니다. 계정별 실패가 격리되므로 하나의 잘못된 전송이 배치를 중단시키지 않습니다. +대용량 USDT0 전송은 MapReduce에서 영감을 받은 파이프라인을 사용하여 병렬로 일괄 처리되고 검증됩니다. 계정별 오류는 격리되므로 하나의 잘못된 전송이 일괄 처리를 중단시키지 않습니다. -호출자 측 전송 API는 변경되지 않습니다. 코드를 변경하지 않고도 일반적인 방식으로 전송을 제출하고 처리량을 얻습니다. +호출자 측 전송 API는 변경되지 않습니다. 코드를 변경하지 않고도 일반적인 방식으로 전송을 제출하고 처리량을 확보할 수 있습니다. -더 읽어보기: [USDT 전송 집계기](/ko/explanation/usdt-transfer-aggregator). +자세히 보기: [USDT 전송 애그리게이터](/ko/explanation/usdt-transfer-aggregator). ## EVM 호환성 -표준 EVM 툴링은 변경 없이 작동합니다. EVM 레벨에서 세 가지 동작이 이더리움과 다릅니다(위에서 다룬 Gas로서의 USDT0는 네 번째입니다). +표준 EVM 툴링은 변경 없이 작동합니다. EVM 수준에서는 Ethereum과 세 가지 동작이 다릅니다(위에서 다룬 가스로서의 USDT0이 네 번째입니다). -**단일 슬롯 완결성.** 트랜잭션은 블록에 포함되면 최종적입니다. 블록은 약 0.7초마다 생성됩니다. +**단일 슬롯 최종성.** 트랜잭션은 블록에 포함되면 최종적입니다. 블록은 대략 0.7초마다 생성됩니다. -**우선순위 팁 없음.** `maxPriorityFeePerGas`는 항상 무시됩니다. 유효 Gas 가격은 프로토콜에 의해 설정된 기본 수수료입니다. +**우선순위 팁 없음.** `maxPriorityFeePerGas`는 항상 무시됩니다. 실제 가스 가격은 프로토콜에 의해 설정된 기본 수수료입니다. ```typescript import { ethers } from "ethers"; @@ -63,8 +64,8 @@ const baseFee = block.baseFeePerGas; const tx = await wallet.sendTransaction({ to: "0xRecipientAddress", value: ethers.parseEther("0.1"), - maxFeePerGas: baseFee * 2n, // 안전 마진으로 기본 수수료의 2배 - maxPriorityFeePerGas: 0n, // Stable에서는 항상 0 + maxFeePerGas: baseFee * 2n, // 2x base fee as safety margin + maxPriorityFeePerGas: 0n, // always 0 on Stable }); await tx.wait(); @@ -72,26 +73,26 @@ console.log("Included at gas price:", tx.gasPrice?.toString()); ``` ```text -Include at gas price: 1000000000 +Included at gas price: 1000000000 ``` -**이중 역할 USDT0, 포팅 위험.** 이더리움에서 포팅된 계약은 네이티브 잔액을 미러링하지 않고, `address(0)` 전송을 거부해야 하며, 주소 재사용 감지를 위해 `EXTCODEHASH`에 의존해서는 안 됩니다. +**이중 역할 USDT0, 포팅 위험.** Ethereum에서 포팅된 계약은 기본 잔액을 미러링해서는 안 되며, `address(0)` 전송을 거부해야 하며, 주소 재사용 감지를 위해 `EXTCODEHASH`에 의존해서는 안 됩니다. :::warning -내부 변수에 네이티브 잔액을 미러링하는 계약을 포팅하는 것은 Stable에서 안전하지 않습니다. 외부 `USDT0.transferFrom` 호출은 계약 코드를 호출하지 않고 계약의 네이티브 잔액을 소진할 수 있습니다. 전송 시 항상 `address(this).balance`로 지급 능력(solvency)을 확인하십시오. +내부 변수에 기본 잔액을 미러링하는 계약을 Stable에 포팅하는 것은 안전하지 않습니다. 외부 `USDT0.transferFrom` 호출은 계약 코드를 호출하지 않고도 계약의 기본 잔액을 고갈시킬 수 있습니다. 전송 시점에 `address(this).balance`로 항상 지급 능력을 확인하십시오. ::: -더 읽어보기: [이더리움과의 차이점](/ko/explanation/ethereum-comparison) · [Stable의 계약](/ko/explanation/contracts-overview) · [USDT0 마이그레이션 체크리스트](/ko/explanation/usdt0-behavior). +자세히 보기: [Ethereum과의 차이점](/ko/explanation/ethereum-comparison) · [Stable의 계약](/ko/explanation/contracts-overview) · [USDT0 마이그레이션 체크리스트](/ko/explanation/usdt0-behavior). ## 기밀 전송 (계획 중) -Stable은 승인된 당사자가 감사할 수 있으면서도 금액을 숨기는 영지식 전송을 위한 기능을 계획하고 있습니다. 아직 출시되지 않았습니다. +Stable은 승인된 당사자가 감사할 수 있도록 금액을 숨기는 영지식 전송을 위한 계획된 기능을 가지고 있습니다. 아직 출시되지 않았습니다. -더 읽어보기: [기밀 전송](/ko/explanation/confidential-transfer). +자세히 보기: [기밀 전송](/ko/explanation/confidential-transfer). -## 다음 추천 항목 +## 다음 단계 - [**빠른 시작**](/ko/tutorial/quick-start): 테스트넷에 연결하고 첫 번째 트랜잭션을 보냅니다. -- [**USDT0 동작**](/ko/explanation/usdt0-behavior): 이중 역할 문제점 없이 Stable로 계약을 포팅합니다. -- [**Gas 가격 책정**](/ko/reference/gas-pricing-api): Stable의 수수료 모델에서 트랜잭션을 올바르게 구성합니다. -- [**프로덕션 준비 상태**](/ko/how-to/production-readiness): 메인넷에 출시하기 전에 통합을 검증합니다. +- [**USDT0 동작**](/ko/explanation/usdt0-behavior): 이중 역할의 함정에 빠지지 않고 계약을 Stable로 포팅합니다. +- [**가스 가격 책정**](/ko/reference/gas-pricing-api): Stable의 수수료 모델에서 트랜잭션을 올바르게 구성합니다. +- [**생산 준비 완료**](/ko/how-to/production-readiness): 메인넷에 출시하기 전에 통합을 검증합니다. diff --git a/docs/pages/ko/explanation/execution.mdx b/docs/pages/ko/explanation/execution.mdx index 9a65826..32da7cc 100755 --- a/docs/pages/ko/explanation/execution.mdx +++ b/docs/pages/ko/explanation/execution.mdx @@ -1,13 +1,15 @@ --- source_path: explanation/execution.mdx -source_sha: 6fd36fc5aba0418235d67180f61d452cae54c8a7 +source_sha: 4944b75f046b2ae6cae395c17b913b618cf9a3e3 title: "실행" -description: "Stable이 결정론적 상태를 유지하면서 Block-STM으로 트랜잭션을 동시적으로 실행하는 방법을 이해해 보세요." +description: "Stable이 결정론적 상태를 유지하면서 Block-STM으로 트랜잭션을 동시 실행하는 방법을 이해합니다." diataxis: "explanation" --- # 실행 +Stable은 결정론적 최종 상태를 유지하면서 Block-STM으로 EVM 트랜잭션을 동시 실행합니다. 프리컴파일은 해당 실행 계층을 Stable SDK 모듈에 연결합니다. + ## Stable EVM Stable의 낙관적 병렬 실행 -Stable은 OPE를 **낙관적 블록 처리(OBP)**와 결합합니다. 두 최적화는 서로 다른 작업을 처리합니다. +Stable은 OPE를 **낙관적 블록 처리(OBP)**와 결합합니다. 두 최적화는 다른 작업을 처리합니다. ### OBP 정보 - OBP는 병렬 처리가 아니라 실행 타이밍에 관한 것입니다. -- `ProcessProposal` 단계에서 Stable은 블록이 다른 노드에 전파되는 동안 블록을 미리 실행합니다. +- `ProcessProposal` 단계에서 Stable은 블록이 다른 노드로 전파되는 동안 블록을 사전 실행합니다. - 결과 상태는 메모리에 캐시되고 `FinalizeBlock` 중에 재사용되어 시간을 절약하고 중복 계산을 줄입니다. OPE는 여러 CPU 코어를 사용하여 실행 시간을 줄입니다. OBP는 제안 처리와 최종화에서 동일한 블록을 두 번 실행하는 것을 방지합니다. ### 커밋 후 재확인 -블록이 커밋된 후 CometBFT는 일반적으로 멤풀에서 대기 중인 모든 트랜잭션을 재확인합니다. 이 반복적인 작업은 노드 CPU의 31~34%를 소비할 수 있습니다. +블록이 커밋되면 CometBFT는 일반적으로 멤풀에서 대기 중인 모든 트랜잭션을 다시 확인합니다. 이 반복되는 작업은 노드 CPU의 31-34%를 소비할 수 있습니다. -Stable v1.4.0은 **선택적 RecheckTx**를 추가합니다. 애플리케이션은 블록의 상태 변경 델타를 반환하고, 노드는 영향을 받는 계정의 트랜잭션만 재확인합니다. CometBFT는 애플리케이션 지원을 감지하고 선택적 재확인이 불가능할 경우 전체 재확인으로 폴백합니다. +Stable v1.8.0에는 **선택적 RecheckTx**가 포함되어 있습니다. 애플리케이션은 블록의 상태 변경 델타를 반환하고 노드는 영향을 받는 계정의 트랜잭션만 다시 확인합니다. CometBFT는 애플리케이션 지원을 감지하고 선택적 재확인을 사용할 수 없는 경우 전체 재확인으로 폴백합니다. -고유한 송신자로부터 10,000개의 보류 중인 트랜잭션에 대한 최상의 벤치마크에서 처리량은 700에서 1,400 TPS로 증가했습니다. 더 일반적인 워크로드에서는 1.5–1.7배 개선이 예상됩니다. +고유한 보낸 사람으로부터 10,000개의 보류 중인 트랜잭션이 있는 최적의 벤치마크에서 처리량은 700에서 1,400 TPS로 증가했습니다. 더 일반적인 워크로드에서는 1.5-1.7배 개선을 예상합니다. -여기에 절약된 CPU는 OPE 작업자에게 제공됩니다. MemIAVL은 이러한 실행 이득을 제한할 수 있는 스토리지 병목 현상을 제거합니다. +여기서 절약된 CPU는 OPE 작업자에게 제공됩니다. MemIAVL은 그렇지 않으면 이러한 실행 이득을 제한할 수 있는 스토리지 병목 현상을 제거합니다. ## 향후 로드맵: StableVM++ -낙관적 병렬 실행(OPE) 및 낙관적 블록 처리(OBP)와 같은 노력은 *여러 트랜잭션이 동시에 실행되는 방식*을 최적화하는 데 중점을 두지만, 또 다른 중요한 성능 요소는 **개별 트랜잭션이 얼마나 효율적으로 처리되는지**입니다. +낙관적 병렬 실행(OPE) 및 낙관적 블록 처리(OBP)와 같은 노력은 *여러 트랜잭션이 동시에 실행되는 방식*을 최적화하는 데 중점을 두지만, 또 다른 중요한 성능 레버는 **각 개별 트랜잭션이 얼마나 효율적으로 처리되는지**입니다. -Stable은 현재 실행 속도를 높이기 위해 대체 EVM 구현을 모색 중입니다. 후보 중 C++로 작성된 고성능 EVM인 **EVMONE**은 기존 Go 기반 EVM을 대체할 강력한 경쟁자로 두드러집니다. 이 전환은 이론적 벤치마크를 기반으로 **EVM 실행 성능에서 최대 6배 증가**를 가져올 것으로 예상됩니다. +Stable은 현재 실행 속도를 높이기 위해 대체 EVM 구현을 모색하고 있습니다. 후보 중 C++로 작성된 고성능 EVM인 **EVMONE**은 기존 Go 기반 EVM을 대체할 강력한 후보로 돋보입니다. 이 전환은 이론적 벤치마크를 기반으로 **EVM 실행 성능에서 최대 6배 증가**를 제공할 것으로 예상됩니다. ## 다음으로 이동할 곳 -- [**스토리지 (StableDB)**](/ko/explanation/stable-db): 디스크 I/O에 블로킹되지 않고 분리된 상태 커밋이 실행에 어떻게 공급되는지 확인하세요. -- [**고성능 RPC**](/ko/explanation/high-performance-rpc): 실행 결과를 클라이언트에 표시하는 분할 경로 RPC를 이해하세요. -- [**이더리움 호환성**](/ko/explanation/ethereum-compatibility): 표준 EVM 도구를 사용하여 기존 계약을 Stable에 포팅하세요. -- [**네트워크 업그레이드**](/ko/reference/network-upgrades): 전체 v1.4.0 릴리스 범위 및 롤아웃 노트를 검토하세요. +- [**스토리지 (StableDB)**](/ko/explanation/stable-db): 디스크 I/O에서 블로킹하지 않고 분리된 상태 커밋이 실행에 어떻게 공급되는지 확인하세요. +- [**고성능 RPC**](/ko/explanation/high-performance-rpc): 클라이언트에 실행 결과를 제공하는 분할 경로 RPC를 이해하세요. +- [**이더리움 호환성**](/ko/explanation/ethereum-compatibility): 표준 EVM 툴링을 사용하여 기존 컨트랙트를 Stable로 포팅하세요. +- [**네트워크 업그레이드**](/ko/reference/network-upgrades): v1.8.0 릴리스 범위 및 활성화 세부 정보를 검토하세요. diff --git a/docs/pages/ko/explanation/guaranteed-blockspace.mdx b/docs/pages/ko/explanation/guaranteed-blockspace.mdx index 139f887..043ea3e 100755 --- a/docs/pages/ko/explanation/guaranteed-blockspace.mdx +++ b/docs/pages/ko/explanation/guaranteed-blockspace.mdx @@ -1,70 +1,71 @@ --- source_path: explanation/guaranteed-blockspace.mdx -source_sha: 5a58c3c6715bd458c1b2a57a9130934021c66e59 +source_sha: 457ac2eee760abfd2926cf176022aa6204a46e7a title: "보장된 블록 공간" -description: "Stable이 레인별 가스 용량을 예약하고 두 차원 논스를 통해 우선 순위 트래픽을 식별하는 방법을 이해합니다." +description: "Stable이 레인별 가스 용량을 예약하고 2차원 논스를 통해 우선 순위 트래픽을 식별하는 방법을 이해합니다." diataxis: "explanation" --- # 보장된 블록 공간 -Stable v1.4.0은 각 블록을 별도의 가스 예산이 있는 레인으로 나눕니다. 자격이 있는 우선순위 트랜잭션은 VIP 레인으로 들어가므로 일반 트래픽은 이들을 위해 예약된 용량을 소비할 수 없습니다. +Stable v1.8.0은 각 블록을 별도의 가스 예산을 가진 레인으로 나눕니다. 적격 우선순위 트랜잭션은 엔터프라이즈 레인으로 들어가므로 일반 트래픽이 예약된 용량을 소비할 수 없습니다. :::note -보장된 블록 공간은 v1.4.0 테스트넷 릴리스 후보에 적용됩니다. 메인넷 업그레이드 일정은 아직 보류 중입니다. 거버넌스 구성 없이는 모든 트랜잭션이 하나의 일반 레인을 계속 사용합니다. +보장된 블록 공간은 Stable 메인넷과 테스트넷에서 활성화되어 있습니다. 거버넌스는 활성 레인 구성을 변경할 수 있으므로, 오프체인에서 트랜잭션을 분류하기 전에 `blockspaceLanes()`를 쿼리하십시오. ::: ## 블록 레인 -제안 및 유효성 검사 규칙은 세 가지 레인 유형을 인식합니다. +제안 및 검증 규칙은 세 가지 레인 유형을 인식합니다. -- **VIP 레인**: `NonceKey`가 프로토콜 예약 범위에 있는 트랜잭션을 처리합니다. +- **엔터프라이즈 레인**: `NonceKey`의 63번째 비트가 설정된 `CustomTx` 트랜잭션을 전달합니다. 단, 순서가 없는 마커인 `MaxUint64`는 제외합니다. - **트랜잭션 유형 레인**: 구성된 트랜잭션 범주에 대한 용량을 예약합니다. -- **일반 레인**: 다른 구성된 레인과 일치하지 않는 표준 트랜잭션을 처리합니다. +- **일반 레인**: 다른 구성된 레인과 일치하지 않는 표준 트랜잭션을 전달합니다. -각 레인에는 자체 가스 할당량이 있습니다. 제안자는 이 제한 내에서 레인을 채우고, 검증자는 제안된 블록을 검증할 때 동일한 제한을 적용합니다. +`maxBlockspaceGasWeight`는 구성된 모든 레인에 걸쳐 예약된 블록 가스 한도의 백분율을 설정합니다. 각 레인의 `weight`는 해당 예약된 풀의 백분율을 설정합니다. -이는 프로토콜 수준에서 예약을 결정론적으로 만듭니다. 제안자가 자발적으로 공간을 사용하지 않고 남겨두는 것에 의존하지 않습니다. +제안자는 해당 한도 내에서 레인을 채우고, 검증자는 제안된 블록을 검증할 때 동일한 한도를 적용합니다. + +이를 통해 프로토콜 수준에서 예약이 결정론적이 됩니다. 이는 제안자가 자발적으로 공간을 사용하지 않고 남겨두는 것에 의존하지 않습니다. ## 2차원 논스 -이더리움 계정은 일반적으로 하나의 논스 시퀀스를 가집니다. 트랜잭션 12가 누락되거나 멈춘 경우, 트랜잭션 13 및 이후 트랜잭션은 실행될 수 없습니다. +이더리움 계정은 일반적으로 하나의 논스 시퀀스를 가집니다. 트랜잭션 12가 누락되거나 멈춘 경우, 트랜잭션 13 이후는 실행될 수 없습니다. -**2차원 논스** 또는 2D 논스는 계정에 여러 독립적인 시퀀스를 제공합니다. `NonceKey`는 시퀀스를 선택하고, 트랜잭션의 논스는 해당 시퀀스 내에서의 위치를 제공합니다. +**2차원 논스** 또는 2D 논스는 계정에 여러 독립적인 시퀀스를 제공합니다. `NonceKey`가 시퀀스를 선택하고, 트랜잭션의 논스는 해당 시퀀스 내에서의 위치를 제공합니다. 예를 들어, 결제 계정은 급여를 위해 `NonceKey = 1`을 사용하고 공급업체 결제를 위해 `NonceKey = 2`를 사용할 수 있습니다. 지연된 급여 트랜잭션은 공급업체 시퀀스를 차단하지 않습니다. 논스 키 공간에는 세 가지 중요한 영역이 있습니다. - `NonceKey = 0`은 표준 EVM 호환 논스 동작을 유지합니다. -- `uint64` 범위의 상위 절반은 프로토콜 사용을 위해 예약되어 있습니다. VIP 멤버십은 이 범위를 통해 신호를 보냅니다. -- `NonceKey = MaxUint64`는 순서가 없는 트랜잭션을 표시합니다. `TimeoutTimestamp`는 재생 방지 마감일을 제공합니다. +- `uint64` 범위의 상위 절반은 프로토콜 사용을 위해 예약되어 있습니다. 63번째 비트를 설정하면 엔터프라이즈 레인 적격성을 나타냅니다. +- `NonceKey = MaxUint64`는 순서 없는 트랜잭션을 표시합니다. `TimeoutTimestamp`는 재실행 방지 기한을 제공합니다. -Stable은 이 필드들을 트랜잭션 유형 `0x3F`인 `CustomTx`에 포함합니다. 기존 EVM 트랜잭션 형식은 계속 사용할 수 있으며, 기본 논스 채널은 예상되는 동작을 보존합니다. +Stable은 이 필드들을 트랜잭션 유형 `0x3F`인 `CustomTx`에 담습니다. 기존 EVM 트랜잭션 형식은 계속 사용할 수 있으며, 기본 논스 채널은 예상되는 동작을 유지합니다. ## 거버넌스 및 활성화 -거버넌스는 하나의 `MsgUpdateParams` 제안을 통해 레인 정의 및 가스 할당량을 제어합니다. 승인된 매개변수는 다음 블록에서 적용됩니다. +거버넌스는 하나의 `MsgUpdateParams` 제안을 통해 레인 정의 및 가스 할당량을 제어합니다. 승인된 매개변수는 다음 블록부터 적용됩니다. + +v1.8.0 메인넷 업그레이드는 `maxBlockspaceGasWeight = 20`과 `weight = 50`을 가진 하나의 엔터프라이즈 레인을 시드했습니다. 트랜잭션 유형 레인은 시드하지 않았습니다. 거버넌스는 나중에 이 매개변수들을 변경할 수 있습니다. -기본값에는 예약된 레인이 포함되어 있지 않습니다. 거버넌스가 이를 구성할 때까지 체인은 하나의 일반 레인으로 작동합니다. 이는 레인 구성을 기존 트랜잭션 처리에 추가합니다. +`StableSystem` 프리컴파일의 `blockspaceLanes()` 쿼리는 활성 구성을 반환합니다. 두 레인 배열은 `id`를 기준으로 오름차순으로 정렬되며, 낮은 ID가 먼저 일치합니다. ## 보장 경계 -VIP 트랜잭션은 다음 모든 조건이 충족될 때 결정론적인 다음 블록 포함을 받습니다. +엔터프라이즈 트랜잭션은 다음 모든 조건이 충족될 때 결정론적인 다음 블록 포함을 받습니다. -- 트랜잭션이 VIP 레인에 적합합니다. -- 레인에 트랜잭션을 위한 충분한 예약 가스가 있습니다. +- 트랜잭션이 엔터프라이즈 레인에 적합합니다. +- 레인에 트랜잭션에 필요한 충분한 예약된 가스가 있습니다. - 검증자가 프로토콜을 따릅니다. -- 네트워크가 제안 전에 검증자가 트랜잭션을 수신할 수 있을 만큼 충분히 동기화되어 있습니다. - -Stable의 멤풀 없는 검증자 인그레스 모델은 VIP 트랜잭션을 검증자에게 제공합니다. 예약된 제안 용량은 일반 트래픽이 이를 방해하는 것을 방지합니다. +- 네트워크가 검증자가 제안 전에 트랜잭션을 수신할 만큼 충분히 동기화되어 있습니다. -:::note -가스 면제 트랜잭션 유형 레인은 연기됩니다. `gasPrice = 0`인 레인에는 신뢰할 수 있는 입장 제어가 필요합니다. 그렇지 않으면 공격자가 무료 트랜잭션으로 플러딩할 수 있습니다. -::: +Stable의 엔터프라이즈 RPC 게이트웨이는 적격 트랜잭션을 검증자에게 공급합니다. 예약된 제안 용량은 일반 트래픽이 이를 대체하는 것을 방지합니다. -## 다음으로 이동할 곳 +## 다음 단계 -- [**보장된 정산**](/ko/explanation/upcoming-use-cases): 보장된 블록 공간에 의존하는 결제 패턴을 확인하세요: 결정론적 포함을 갖는 DVp(Delivery versus Payment) 정산 주기. -- [**네트워크 업그레이드**](/ko/reference/network-upgrades): v1.4.0 릴리스 전체와 출시 상태를 검토하세요. -- [**실행**](/ko/explanation/execution): Stable이 각 블록에 선택된 트랜잭션을 어떻게 실행하는지 이해하세요. +- [**보장된 정산**](/ko/explanation/upcoming-use-cases): 보장된 블록 공간에 의존하는 결제 패턴, 즉 결정론적 포함과 함께 시간제 DvP 정산 주기를 확인하세요. +- [**StableSystem 프리컴파일**](/ko/reference/system-transactions-api): 활성 엔터프라이즈 및 트랜잭션 유형 레인 정의를 쿼리하세요. +- [**네트워크 업그레이드**](/ko/reference/network-upgrades): v1.8.0 릴리스 및 활성화 세부 정보를 검토하세요. +- [**실행**](/ko/explanation/execution): Stable이 각 블록에 선택된 트랜잭션을 실행하는 방법을 이해하세요. diff --git a/docs/pages/ko/explanation/stable-db.mdx b/docs/pages/ko/explanation/stable-db.mdx index bc7bee9..cf6de4b 100755 --- a/docs/pages/ko/explanation/stable-db.mdx +++ b/docs/pages/ko/explanation/stable-db.mdx @@ -1,96 +1,96 @@ --- source_path: explanation/stable-db.mdx -source_sha: ffbcf61705d3dbb4a82da281257a33d12e385b45 -title: "저장소 (StableDB)" -description: "MemIAVL이 메모리 매핑된 스냅샷과 순차적 쓰기 우선 로그로 현재 상태를 저장하는 방법을 이해합니다." +source_sha: 504059cb504eb59f4dab03833fd8498a842c7187 +title: "스토리지 (StableDB)" +description: "MemIAVL이 메모리 맵 스냅샷과 순차적 쓰기 우선 로그로 현재 상태를 저장하는 방법을 이해합니다." diataxis: "explanation" --- -# 저장소 (StableDB) +# 스토리지 (StableDB) -Stable v1.4.0은 LevelDB 기반 상태 저장소를 MemIAVL로 대체합니다. MemIAVL은 하나의 상태 스냅샷을 메모리 매핑 파일에 유지하고 각 새 블록의 변경 사항을 순차적 쓰기 우선 로그에 기록합니다. +Stable v1.8.0은 이전 LevelDB 기반 상태 저장소 대신 MemIAVL을 사용합니다. MemIAVL은 하나의 상태 스냅샷을 메모리 맵 파일에 유지하고 각 새 블록의 변경 사항을 순차적 쓰기 우선 로그에 기록합니다. :::note -MemIAVL은 v1.4.0 Testnet 릴리스 후보에서 라이브 상태입니다. 메인넷 업그레이드 일정은 아직 보류 중입니다. 출시 상태는 [네트워크 업그레이드](/ko/reference/network-upgrades)를 확인하세요. +MemIAVL과 VersionDB는 메인넷에서 활성화되어 있습니다. Stable v1.8.0은 또한 WAL 복구, 스냅샷 게시 및 롤백, 상태 동기화, 기록 쿼리 리소스 정리를 강화합니다. ::: ## 디스크 I/O가 병목 현상인 이유 모든 블록은 애플리케이션 상태를 변경합니다. 노드는 두 가지 관련 작업을 완료해야 합니다. -1. **상태 커밋**: 새 상태의 루트 해시를 계산하고 커밋합니다. -2. **상태 지속성**: 변경된 데이터를 저장소에 기록하여 나중에 노드가 복구할 수 있도록 합니다. +1. **상태 커밋**: 새 상태에 대한 루트 해시를 계산하고 커밋합니다. +2. **상태 지속성**: 변경된 데이터를 스토리지에 기록하여 노드가 나중에 복구할 수 있도록 합니다. 결합된 상태 커밋 및 저장소 -이전 LevelDB 기반 저장소는 이러한 작업을 결합했습니다. 또한 나중에 읽기를 효율적으로 만들기 위해 저장된 레코드를 재구성하는 백그라운드 압축 중에 데이터를 다시 썼습니다. +이전 LevelDB 기반 저장소는 이러한 작업을 결합했습니다. 또한 배경 압축 중에 데이터를 다시 작성하여 나중에 효율적으로 읽을 수 있도록 저장된 레코드를 재구성했습니다. -하나의 논리적 상태 업데이트가 10-50배 많은 물리적 디스크 쓰기를 유발할 수 있습니다. 이를 **쓰기 증폭(write amplification)**이라고 합니다. 그런 다음 실행은 무작위 쓰기 및 압축이 지배하는 저장소 경로를 기다려야 했습니다. +하나의 논리적 상태 업데이트는 10-50배의 물리적 디스크 쓰기를 유발할 수 있습니다. 이를 **쓰기 증폭(write amplification)**이라고 합니다. 그런 다음 실행은 무작위 쓰기 및 압축이 지배하는 스토리지 경로를 기다려야 했습니다. ## MemIAVL이 저장소를 변경하는 방법 -메모리 매핑 파일 또는 `mmap`를 사용하면 운영 체제가 메모리 주소를 통해 파일 내용을 노출할 수 있습니다. 노드는 포인터를 따라 상태를 읽을 수 있으며, 운영 체제는 필요한 페이지를 페이지 캐시에 로드합니다. +메모리 맵 파일, 즉 `mmap`을 사용하면 운영 체제가 메모리 주소를 통해 파일 내용을 노출할 수 있습니다. 노드는 포인터를 따라 상태를 읽을 수 있으며, 운영 체제는 필요한 페이지를 페이지 캐시에 로드합니다. MemIAVL은 두 가지 구조를 결합합니다. -- **스냅샷**: 지속된 상태 트리의 단일 메모리 매핑 표현. -- **쓰기 우선 로그 (WAL)**: 해당 스냅샷 이후에 발생한 원시 변경 사항에 대한 추가 전용 기록. +- **스냅샷**: 지속된 상태 트리의 단일 메모리 맵 표현. +- **쓰기 우선 로그 (WAL)**: 스냅샷 이후에 변경된 원시 변경 사항의 추가 전용 기록. 분리된 상태 커밋 및 저장소 ### 쓰기 경로 -각 블록은 변경 세트를 WAL에 순서대로 추가합니다. MemIAVL은 업데이트를 LevelDB를 통해 라우팅하거나 압축을 트리거하지 않습니다. 따라서 쓰기 증폭은 10-50배에서 약 1회 쓰기로 감소합니다. +각 블록은 변경 세트를 WAL에 순서대로 추가합니다. MemIAVL은 LevelDB를 통해 업데이트를 라우팅하거나 압축을 트리거하지 않습니다. 따라서 쓰기 증폭은 10-50배에서 약 1회 쓰기로 감소합니다. MemIAVL은 또한 트리 노드를 두 가지 범주로 나눕니다. - `PersistedNode`는 스냅샷에 이미 저장된 변경되지 않은 서브트리를 나타냅니다. - `MemNode`는 현재 업데이트에 의해 메모리에서 변경된 서브트리를 나타냅니다. -MemIAVL이 다음 루트 해시를 계산할 때, 변경되지 않은 `PersistedNode` 서브트리에서 멈춥니다. 새 `MemNode` 데이터를 포함하는 경로만 해시합니다. +MemIAVL이 다음 루트 해시를 계산할 때 변경되지 않은 `PersistedNode` 서브트리에서 중지됩니다. 새 `MemNode` 데이터를 포함하는 경로만 해싱합니다. ### 읽기 경로 -현재 상태 읽기는 메모리 매핑된 스냅샷의 포인터를 따릅니다. 자주 액세스되는 페이지는 운영 체제의 페이지 캐시에 남아 있으므로 노드는 각 트리 노드에 대해 별도의 데이터베이스 조회를 피합니다. +현재 상태 읽기는 메모리 맵 스냅샷의 포인터를 따릅니다. 자주 액세스되는 페이지는 운영 체제의 페이지 캐시에 남아 있으므로 노드는 각 트리 노드에 대한 별도의 데이터베이스 조회를 피할 수 있습니다. ## 기록 상태 및 VersionDB -MemIAVL은 현재 상태와 노드가 유지하는 스냅샷을 제공합니다. 보조 VersionDB는 RocksDB 사이드카에 기록 버전을 저장합니다. +MemIAVL은 현재 상태와 노드가 유지하는 스냅샷을 제공합니다. 동반 VersionDB는 RocksDB 사이드카에 기록 버전을 저장합니다. -노드가 가장 이른 MemIAVL 스냅샷보다 오래된 기록 상태 쿼리에 응답해야 하는 경우 VersionDB가 필요합니다. 이는 아카이브 노드 및 장거리 쿼리를 노출하는 RPC 서비스에 특히 중요합니다. +노드가 가장 이른 MemIAVL 스냅샷보다 오래된 기록 상태 쿼리에 응답해야 할 때 VersionDB가 필요합니다. 이는 아카이브 노드 및 장기 쿼리를 노출하는 RPC 서비스에 특히 중요합니다. -## 마이그레이션 고려 사항 +## 업그레이드 고려 사항 -기존 노드는 v1.4.0을 채택할 때 LevelDB 상태를 마이그레이션해야 합니다. 권장 경로는 로컬 스냅샷 내보내기 및 복원입니다. +Stable 메인넷은 블록 `36,976,000`에서 v1.8.0을 활성화했습니다. 문서화된 업그레이드는 상태 내보내기 또는 스냅샷 재설정 없이 바이너리와 두 구성 파일을 교체했습니다. -벤치마크는 표준 복원에 대해 검증자당 평균 19.4초의 다운타임을 측정했습니다. 병렬 복원 변형은 평균을 약 2.6초로 줄였습니다. +v1.8.0 구성 파일은 새 스토리지 및 제안 경로에서 사용되는 설정을 추가합니다. `config.toml`과 `app.toml`을 백업하고, v1.8.0 템플릿을 설치한 다음, 모든 노드별 설정을 복원하세요. -검증자는 라운드 로빈 순서로 하나씩 마이그레이션할 수 있습니다. 투표권의 최소 3분의 2를 온라인 상태로 유지하면 네트워크는 마이그레이션 중에 블록을 계속 생성할 수 있습니다. +아카이브 노드 운영자는 이전 가지치기 설정을 복원해야 합니다. 배포된 `app.toml` 템플릿은 기본 가지치기를 사용하며, 가지치기된 기록은 로컬 노드에서 복구할 수 없습니다. :::warning -이 시간은 벤치마크 결과일 뿐 다운타임을 보장하지 않습니다. 최종 바이너리, 업그레이드 높이, 백업 및 복원 명령에 대한 네트워크별 업그레이드 지침을 따르세요. +v1.8.0 이전 구성 파일을 변경하지 않고 재사용하지 마십시오. [노드 업그레이드 가이드](/ko/how-to/upgrade-node)를 따라 두 템플릿을 교체하고 운영 설정을 복원하십시오. ::: -## 추가 읽을거리 +## 추가 자료 -더 자세한 기술적 심층 분석 및 구현 세부 정보는 다음을 참조하세요. +더 자세한 기술 심층 분석 및 구현 세부 정보는 다음을 참조하십시오. - [ADR-065: Cosmos Store V2 아키텍처](https://docs.cosmos.network/main/build/architecture/adr-065-store-v2) - [MemIAVL: 실용 가이드](https://hackmd.io/@yihuang/rkeCvy5xh) - [Cronos MemIAVL 노드 구성](https://docs.cronos.org/for-node-hosts/running-nodes/memiavl) - [Sei의 DB 설계 접근 방식](https://4pillars.io/ko/articles/sei-db) -## 다음으로 이동할 곳 +## 다음 단계 -- [**고성능 RPC**](/ko/explanation/high-performance-rpc): RPC 계층이 쓰기와 경쟁하지 않고 상태 읽기를 노출하는 방법을 확인하세요. -- [**실행**](/ko/explanation/execution): 실행이 여기에 설명된 저장소 계층에 어떻게 쓰는지 이해합니다. -- [**노드 업그레이드**](/ko/how-to/upgrade-node): 조정된 업그레이드 후에 백업을 준비하고 노드를 확인합니다. -- [**네트워크 업그레이드**](/ko/reference/network-upgrades): 전체 v1.4.0 범위 및 출시 상태를 검토합니다. +- [**고성능 RPC**](/ko/explanation/high-performance-rpc): RPC 계층이 쓰기와 충돌하지 않고 상태 읽기를 노출하는 방법을 확인하십시오. +- [**실행**](/ko/explanation/execution): 실행이 여기에서 다루는 스토리지 계층에 기록하는 방법을 이해하십시오. +- [**노드 업그레이드**](/ko/how-to/upgrade-node): 백업을 준비하고 조정된 업그레이드 후 노드를 확인하십시오. +- [**네트워크 업그레이드**](/ko/reference/network-upgrades): v1.8.0 범위 및 활성화 세부 정보를 검토하십시오. diff --git a/docs/pages/ko/explanation/staking-module.mdx b/docs/pages/ko/explanation/staking-module.mdx index 03714ba..e84636a 100755 --- a/docs/pages/ko/explanation/staking-module.mdx +++ b/docs/pages/ko/explanation/staking-module.mdx @@ -1,48 +1,48 @@ --- source_path: explanation/staking-module.mdx -source_sha: 32af1af02985137c678f7ed6d46376607121b6bf +source_sha: 668fab7ce8eadc9f4afe3f31ec4e23e2397c2df3 title: "스테이킹 모듈" -description: "스테이킹 사전 컴파일은 위임, 위임 해제 및 유효성 검사기 관리를 EVM 계약에 노출하며, 발신자 신원을 적용하는 권한 부여 확인을 제공합니다." +description: "EVM 컨트랙트가 Stable의 스테이킹 사전 컴파일을 통해 검증자를 위임, 위임 해제 및 관리하는 방법을 이해합니다." diataxis: "explanation" --- # 스테이킹 모듈 -`x/staking` 모듈은 Stable에서 유효성 검사기 참여 및 위임을 제어합니다. 이 사전 컴파일은 이러한 작업을 Solidity에서 호출할 수 있도록 하여, 계약이 STABLE을 위임하고, 언본딩 기간 후에 위임을 해제하며, 유효성 검사기 간에 재위임하거나, EVM을 벗어나지 않고 유효성 검사기 상태를 쿼리할 수 있도록 합니다. +`x/staking` 모듈은 Stable에서 검증자 참여 및 위임을 제어합니다. 사전 컴파일을 통해 이러한 작업을 Solidity에서 호출할 수 있으므로, 컨트랙트는 STABLE을 위임하거나, 언본딩 기간 이후 위임을 해제하거나, 검증자 간에 재위임하거나, EVM을 벗어나지 않고 검증자 상태를 쿼리할 수 있습니다. -## 제공하는 기능 +## 노출하는 것 -- **유효성 검사기 생성**: 설명, 수수료율 및 초기 자체 위임을 사용하여 새 유효성 검사기를 등록합니다. -- **유효성 검사기 편집**: 유효성 검사기 메타데이터 및 수수료 매개변수를 업데이트합니다. -- **위임**: 유효성 검사기에게 STABLE을 스테이킹합니다. -- **위임 해제**: 유효성 검사기에서 언본딩을 시작합니다 (토큰은 언본딩 기간 후에 사용 가능해집니다). -- **재위임**: 언본딩 없이 유효성 검사기 간에 스테이크를 이동합니다. +- **검증자 생성**: 설명, 수수료율 및 초기 자체 위임으로 새 검증자를 등록합니다. +- **검증자 편집**: 검증자 메타데이터 및 수수료 매개변수를 업데이트합니다. +- **위임**: 검증자에게 STABLE을 스테이킹합니다. +- **위임 해제**: 검증자로부터 언본딩을 시작합니다(토큰은 언본딩 기간 후에 사용 가능해집니다). +- **재위임**: 언본딩 없이 검증자 간에 스테이킹을 이동합니다. - **언본딩 위임 취소**: 기간이 완료되기 전에 진행 중인 언본딩을 되돌립니다. -- **쿼리 메서드**: 유효성 검사기 세트, 위임 기록, 언본딩 기록 및 매개변수를 읽습니다. +- **쿼리 메서드**: 검증자 세트, 위임 기록, 언본딩 기록 및 매개변수를 읽습니다. -## 권한 부여 의미론 +## 인증 의미론 -사전 컴파일은 두 가지 검사를 수행합니다. +사전 컴파일은 두 가지 검사를 수행합니다: -1. 본드 데놈 (스테이킹 토큰)은 체인 초기화 시 등록되어야 합니다. Stable에서는 STABLE 토큰입니다. -2. 발신자는 수정되는 유효성 검사기 또는 위임자와 일치해야 합니다. 사전 컴파일을 직접 호출하여 다른 사람을 대신하여 위임할 수 없습니다. +1. 본드 데놈(스테이킹 토큰)은 체인 초기화 시 등록되어야 합니다. Stable에서는 STABLE 토큰입니다. +2. 호출자는 상태가 수정되는 검증자 또는 위임자와 일치해야 합니다. 사전 컴파일을 직접 호출하여 다른 사람을 대신하여 위임할 수 없습니다. ## 언본딩 완료 -언본딩 기간이 끝나면 토큰은 유동성이 되지만, SDK는 이를 조용히 처리하며 EVM은 직접적인 이벤트를 볼 수 없습니다. Stable의 [시스템 트랜잭션](/ko/explanation/system-transactions) 메커니즘은 이 간극을 메웁니다. 프로토콜은 언본딩이 해제되면 `StableSystem` 사전 컴파일을 통해 `UnbondingCompleted` 이벤트를 발생시키므로 dApp은 표준 EVM 로그를 통해 구독할 수 있습니다. +언본딩 기간이 끝나면 토큰이 유동화되지만, SDK가 이를 조용히 처리하고 EVM은 직접적인 이벤트를 보지 못합니다. Stable의 [시스템 트랜잭션](/ko/explanation/system-transactions) 메커니즘이 이를 연결합니다. 프로토콜은 언본딩이 해제되면 `StableSystem` 사전 컴파일을 통해 `UnbondingCompleted` 이벤트를 발생시키므로, dApp은 표준 EVM 로그를 통해 구독할 수 있습니다. ## 언제 사용해야 하는가 -- 스테이킹 프로토콜이 볼트 계약에서 위임을 관리하는 경우: 사용자가 예치하고 인출할 때 `delegate` 및 `undelegate`를 호출합니다. -- 거버넌스 대시보드에 실시간 유효성 검사기 세트가 필요한 경우: 쿼리 메서드를 사용합니다. -- 리스테이킹 또는 유동성 스테이킹 제품이 언본딩 완료를 추적하는 경우: `UnbondingCompleted` 이벤트를 구독합니다 (가이드가 출시되면 [언본딩 추적](/ko/how-to/track-unbonding)을 참조하세요). +- 스테이킹 프로토콜이 볼트 컨트랙트에서 위임을 관리하는 경우: 사용자가 입금하고 출금할 때 `delegate` 및 `undelegate`를 호출합니다. +- 거버넌스 대시보드에 실시간 검증자 세트가 필요한 경우: 쿼리 메서드를 사용합니다. +- 재스테이킹 또는 유동 스테이킹 제품이 언본딩 완료를 추적하는 경우: [언본딩 완료 추적](/ko/how-to/track-unbonding)으로 `UnbondingCompleted` 이벤트를 구독합니다. ## ABI를 찾는 곳 전체 메서드 시그니처, 구조체 정의 및 발생된 이벤트는 [스테이킹 사전 컴파일 참조](/ko/reference/staking-module-api)에 있습니다. -## 다음 권장 사항 +## 다음 단계 -- [**스테이킹 사전 컴파일 참조**](/ko/reference/staking-module-api): `delegate`, `undelegate`, `redelegate`를 호출하고 유효성 검사기 상태를 읽습니다. +- [**스테이킹 사전 컴파일 참조**](/ko/reference/staking-module-api): `delegate`, `undelegate`, `redelegate`를 호출하고 검증자 상태를 읽습니다. - [**시스템 트랜잭션**](/ko/explanation/system-transactions): 언본딩 완료가 이벤트로 EVM에 도달하는 방법을 알아봅니다. - [**분배 모듈**](/ko/explanation/distribution-module): 여기서 관리되는 위임으로 얻은 보상을 인출합니다. diff --git a/docs/pages/ko/explanation/system-modules-overview.mdx b/docs/pages/ko/explanation/system-modules-overview.mdx index eab125d..2002c89 100755 --- a/docs/pages/ko/explanation/system-modules-overview.mdx +++ b/docs/pages/ko/explanation/system-modules-overview.mdx @@ -1,39 +1,39 @@ --- source_path: explanation/system-modules-overview.mdx -source_sha: e9d156bb03d4413c1981f308ba7c076759d9baa8 +source_sha: 844ae01965c8d027ec16cf10164b75b94fdb3078 title: "시스템 모듈" -description: "EVM에서 스테이킹, 분배, 뱅크 작업을 호출합니다. Stable은 Cosmos-SDK 프로토콜 모듈을 재작성 없이 사전 컴파일된 컨트랙트로 노출합니다." +description: "EVM 컨트랙트가 고정 주소 사전 컴파일을 통해 Stable SDK 모듈을 호출하는 방법을 이해합니다." diataxis: "explanation" --- # 시스템 모듈 -Stable의 핵심 프로토콜 동작은 `x/bank`, `x/distribution`, `x/staking`과 같은 SDK 모듈에 있습니다. 이 동작을 EVM에서 접근 가능하도록 Stable은 각 모듈을 고정 주소의 **사전 컴파일된 컨트랙트**로 노출합니다. Solidity로 작성된 컨트랙트는 사전 컴파일을 직접 호출하며, EVM은 이 호출을 네이티브 SDK 핸들러로 라우팅합니다. 사전 컴파일은 프로토콜 수준에서 구현되므로, 동등한 Solidity 재구현보다 훨씬 더 가스 효율적입니다. +Stable의 핵심 프로토콜 동작은 `x/bank`, `x/distribution`, `x/staking`과 같은 SDK 모듈에 있습니다. 고정 주소 사전 컴파일은 애플리케이션 컨트랙트에서 프로토콜 로직을 복제하지 않고 솔리디티 호출을 기본 SDK 핸들러로 라우팅합니다. ## 세 가지 모듈 -| 모듈 | 사전 컴파일 주소 | 목적 | +| **모듈** | **사전 컴파일 주소** | **목적** | | :--- | :--- | :--- | -| [뱅크](/ko/explanation/bank-module) | `0x0000…1003` (STABLE) | 토큰 전송, 잔액 회계, 허용치 관리, 승인된 컨트랙트에 대한 mint/burn. | -| [분배](/ko/explanation/distribution-module) | `0x0000…0801` | 스테이킹 보상 청구, 보상 쿼리, 인출 주소 관리. | -| [스테이킹](/ko/explanation/staking-module) | `0x0000…0800` | 위임, 위임 해제, 재위임, 검증인 쿼리. | -| [시스템 트랜잭션](/ko/explanation/system-transactions) | `0x0000…9999` | SDK 계층 작업(예: 언본딩 완료)에 대해 프로토콜에서 발행하는 EVM 이벤트. | +| [뱅크](/ko/explanation/bank-module) | `0x0000…1003` (STABLE) | 토큰 전송, 잔액 회계, 허용 관리, 승인된 컨트랙트에 대한 발행/소각. | +| [분배](/ko/explanation/distribution-module) | `0x0000…0801` | 스테이킹 보상 청구, 보상 조회, 인출 주소 관리. | +| [스테이킹](/ko/explanation/staking-module) | `0x0000…0800` | 위임, 위임 해제, 재위임, 검증자 조회. | +| [시스템 트랜잭션](/ko/explanation/system-transactions) | `0x0000…9999` | 보장된 블록 공간 레인 쿼리 및 프로토콜에서 발행된 EVM 이벤트. | -위 각 페이지는 모듈이 무엇을 하는지, 언제 사용해야 하는지, 그리고 해당 ABI를 어디서 찾을 수 있는지 설명합니다. +위의 각 페이지에서는 모듈의 기능, 사용 시기, ABI를 찾는 방법에 대해 설명합니다. -## Solidity가 아닌 사전 컴파일인 이유 +## 솔리디티 대신 사전 컴파일을 사용하는 이유 -두 가지 이유가 있습니다: +두 가지 이유: -- **가스 효율성.** 사전 컴파일은 프로토콜의 네이티브 실행 경로에서 실행됩니다. 동등한 Solidity 컨트랙트는 훨씬 더 높은 가스 비용으로 동일한 로직을 재구현할 것입니다. -- **단일 정보원.** 스테이킹, 분배, 토큰 공급은 프로토콜 수준의 상태입니다. 사전 컴파일을 통해 이를 노출함으로써 SDK에서 벗어날 수 있는 중복된 Solidity 구현을 유지할 필요가 없습니다. +- **가스 효율성.** 사전 컴파일은 프로토콜의 기본 실행 경로에서 실행됩니다. 동등한 솔리디티 컨트랙트는 훨씬 더 높은 가스 비용으로 동일한 로직을 재구현합니다. +- **단일 정보원.** 스테이킹, 분배 및 토큰 공급은 프로토콜 수준 상태입니다. 사전 컴파일을 통해 이를 노출하면 SDK와 다를 수 있는 중복 솔리디티 구현을 유지 관리할 필요가 없습니다. ## 권한 부여 -일부 사전 컴파일 메서드(`mint`, `burn`, 프로토콜 수준 스테이킹 작업)는 호출자 권한 부여를 요구합니다. `x/precompile` 모듈은 온체인 화이트리스트를 유지하며, 등록되지 않은 컨트랙트의 호출은 되돌려집니다. 이는 읽기/전송 메서드의 일반적인 EVM 사용을 차단하지 않으면서 특권 작업을 거버넌스 제어가 가능하게 합니다. +일부 사전 컴파일 메서드(`mint`, `burn`, 프로토콜 수준 스테이킹 작업)에는 호출자 권한 부여가 필요합니다. `x/precompile` 모듈은 온체인 화이트리스트를 유지하며, 등록되지 않은 컨트랙트의 호출은 되돌려집니다. 이렇게 하면 읽기/전송 메서드의 일반적인 EVM 사용을 차단하지 않고 권한 있는 작업을 거버넌스 게이트 방식으로 유지할 수 있습니다. -## 다음 권장 사항 +## 다음 단계 -- [**뱅크 모듈**](/ko/explanation/bank-module): 토큰 전송, 허용치, mint/burn 승인 모델을 이해합니다. -- [**스테이킹 모듈**](/ko/explanation/staking-module): 위임 및 검증인 관리가 EVM에 어떻게 도달하는지 확인합니다. -- [**시스템 트랜잭션**](/ko/explanation/system-transactions): 언본딩 완료와 같은 프로토콜 수준 이벤트가 EVM 로그로 어떻게 나타나는지 알아봅니다. +- [**뱅크 모듈**](/ko/explanation/bank-module): 토큰 전송, 허용 및 발행/소각 승인 모델을 이해합니다. +- [**스테이킹 모듈**](/ko/explanation/staking-module): 위임 및 검증자 관리가 EVM에 도달하는 방식을 확인합니다. +- [**시스템 트랜잭션**](/ko/explanation/system-transactions): 언본딩 완료와 같은 프로토콜 수준 이벤트가 EVM 로그로 표시되는 방법을 알아봅니다. diff --git a/docs/pages/ko/explanation/system-transactions.mdx b/docs/pages/ko/explanation/system-transactions.mdx index e115904..8918cec 100755 --- a/docs/pages/ko/explanation/system-transactions.mdx +++ b/docs/pages/ko/explanation/system-transactions.mdx @@ -1,60 +1,64 @@ --- source_path: explanation/system-transactions.mdx -source_sha: 0ca908e75feea70023fe71db75e2068f4c824b90 +source_sha: a90224796f521ad61f8bd2033292c16883630e31 title: "시스템 트랜잭션" -description: "시스템 트랜잭션은 Cosmos-SDK 이벤트를 EVM 로그에 연결하므로, 언본딩 완료와 같은 작업은 dApp이 구독할 수 있는 표준 이벤트로 나타납니다." +description: "Stable이 SDK 모듈 이벤트를 애플리케이션이 구독할 수 있는 EVM 로그로 변환하는 방법을 이해합니다." diataxis: "explanation" --- # 시스템 트랜잭션 -EVM 애플리케이션은 `eth_getLogs`와 같은 표준 인터페이스를 통해 온체인 활동을 구독합니다. 그러나 Stable에서 가장 중요한 작업 중 일부(예: 스테이킹 언본딩 완료)는 EVM 이벤트를 자연스럽게 방출하지 않는 SDK 모듈 내에서 발생합니다. **시스템 트랜잭션**은 이러한 가시성 격차를 해소합니다. 프로토콜 자체는 SDK 계층 작업에 대한 이벤트를 방출하는 EVM 트랜잭션을 제출하여 dApp이 이미 사용하는 동일한 로그 스트림을 통해 인덱싱할 수 있게 합니다. +Stable은 **시스템 트랜잭션**을 사용하여 SDK 모듈 이벤트를 표준 EVM 로그로 변환합니다. 애플리케이션은 `eth_getLogs` 또는 기존 WebSocket 구독을 통해 해당 로그를 사용할 수 있습니다. -## 이것이 중요한 이유 +예를 들어, 시스템 트랜잭션은 스테이킹 모듈이 언본딩 작업을 완료한 후 `UnbondingCompleted`를 내보냅니다. 이 이벤트에는 위임자, 검증자, 원래 완료 높이 및 금액이 포함됩니다. -사용자의 토큰이 언제 언본딩을 완료하는지 추적하는 것을 생각해 봅시다. 시스템 트랜잭션이 없다면, dApp은 다음 중 하나를 해야 합니다. +## 애플리케이션이 수신하는 내용 -- SDK 이벤트를 감시하고 자체 데이터베이스에 저장하는 별도의 인덱서를 실행합니다. 운영 오버헤드와 새로운 실패 지점이 발생합니다. -- REST 엔드포인트를 주기적으로 폴링합니다. 5–10초 지연, 더 높은 RPC 부하, 유지보수해야 할 두 가지 클라이언트 스택(web3 + REST)이 발생합니다. +사용자의 토큰 언본딩이 완료되는 시점을 추적하는 것을 고려해 보세요. 시스템 트랜잭션이 없으면 dApp은 다음 중 하나를 수행해야 합니다. -시스템 트랜잭션은 dApp에 EVM 로그에 이미 사용하는 동일한 WebSocket 연결을 통해 실시간 이벤트 알림을 제공합니다. 별도의 인덱서가 필요 없고, REST 폴링도 필요 없습니다. +- SDK 이벤트를 감시하고 자체 데이터베이스에 저장하는 별도의 인덱서를 실행합니다. 운영 오버헤드와 새로운 실패 지점이 추가됩니다. +- REST 엔드포인트를 주기적으로 폴링합니다. 5~10초의 지연 시간, 더 높은 RPC 로드, 유지 관리해야 할 두 개의 클라이언트 스택(web3 + REST)이 발생합니다. -## 작동 방식 +시스템 트랜잭션은 dApp에 EVM 로그에 이미 사용하고 있는 동일한 WebSocket 연결을 통해 실시간 이벤트 알림을 제공합니다. 별도의 인덱서도, REST 폴링도 필요 없습니다. + +## 흐름 작동 방식 ```text -1. 프로토콜 이벤트: SDK 계층 작업이 완료됩니다(예: 스테이킹 언본딩). -2. 감지: x/stable EndBlocker는 이벤트를 감지하고 상태에 대기시킵니다. -3. 시스템 TX: 다음 블록의 PrepareProposal에서 프로토콜은 StableSystem 사전 컴파일러를 - 호출하는 시스템 트랜잭션을 생성합니다. -4. EVM 방출: 사전 컴파일러는 대기 중인 항목을 처리하고 표준 - EVM 이벤트를 방출합니다. dApp은 eth_getLogs 및 구독을 통해 이를 확인합니다. +1. Protocol event: SDK 계층 작업 완료 (예: 스테이킹 언본딩). +2. Detection: x/stable EndBlocker가 이벤트를 감지하고 상태에 대기시킵니다. +3. System TX: 다음 블록의 PrepareProposal에서 프로토콜은 + StableSystem.notifySystemTxLogs()를 호출하는 시스템 트랜잭션을 생성합니다. +4. EVM emission: 프리컴파일이 대기열에 있는 항목을 처리하고 표준 + EVM 이벤트를 내보냅니다. dApp은 eth_getLogs 및 구독을 통해 이를 확인합니다. ``` -시스템 트랜잭션은 사용자가 아닌 블록 제안 중에 검증자가 생성합니다. 사용자 트랜잭션보다 먼저 블록의 맨 앞에 착륙합니다. +시스템 트랜잭션은 사용자가 아닌 블록 제안 중에 검증자에 의해 생성됩니다. 사용자 트랜잭션보다 먼저 블록의 맨 앞에 위치합니다. + +## StableSystem 프리컴파일 -## StableSystem 사전 컴파일러 +이벤트는 `0x0000000000000000000000000000000000009999`의 `StableSystem` 프리컴파일을 통해 흐릅니다. 현재 위임자, 검증자, 원래 완료 높이 및 금액과 함께 `UnbondingCompleted`를 내보냅니다. -이벤트는 `0x0000000000000000000000000000000000009999`의 `StableSystem` 사전 컴파일러를 통해 흐릅니다. 현재 스테이킹 언본딩에 대해 하나의 이벤트(`UnbondingCompleted`)를 방출합니다. 프로토콜은 동일한 패턴으로 다른 SDK 작업(검증자 수수료 변경, 거버넌스 실행)으로 확장하도록 설계되었습니다. +동일한 프리컴파일은 공개 `blockspaceLanes()` 뷰 메서드를 노출합니다. 오프체인 트랜잭션 분류를 위해 활성 Enterprise 및 트랜잭션 유형 레인 레지스트리를 반환합니다. ## 보안 모델 -두 가지 속성은 이벤트 스트림의 신뢰성을 유지합니다. +두 가지 속성이 이벤트 스트림을 신뢰할 수 있게 유지합니다. -- **프로토콜 전용 발신자.** 시스템 트랜잭션은 `0x8888888888888888888888888888888888888888`를 발신자로 사용합니다. EVM 상태 전환 규칙은 이 주소에서 `StableSystem` 사전 컴파일러로의 트랜잭션만 서명 검증을 건너뛸 수 있도록 허용합니다. 사용자는 자신의 트랜잭션에서 이벤트를 위조하거나 제한된 사전 컴파일러 함수를 호출할 수 없습니다. -- **결정론적 방출.** 모든 정직한 검증자는 동일한 프로토콜 이벤트에 대해 동일한 시스템 트랜잭션을 생성합니다. 표준 합의 외에 추가적인 신뢰 가정은 없습니다. +- **프로토콜 전용 발신자.** 시스템 트랜잭션은 `0x0000000000000000000000000000000000000001`을 발신자로 사용합니다. EVM 상태 전환 규칙은 이 주소를 프로토콜 생성 트랜잭션용으로 예약합니다. 사용자는 이벤트를 위조하거나 자체 트랜잭션에서 `notifySystemTxLogs()`를 호출할 수 없습니다. +- **확정적 방출.** 모든 정직한 검증자는 동일한 프로토콜 이벤트에 대해 동일한 시스템 트랜잭션을 생성합니다. 표준 합의 외에 추가적인 신뢰 가정은 없습니다. ## 배치 처리 -블록 크기를 제한하기 위해 각 블록은 최대 100개의 언본딩 완료를 처리합니다. Stable의 ~700ms 블록 시간에서 이는 분당 약 9,000개의 완료를 의미하며, 이는 일반적인 스테이킹 활동보다 훨씬 높습니다. 버스트가 블록당 제한을 초과하면 완료는 FIFO 순서로 대기열에 추가되고 후속 블록에 걸쳐 처리됩니다. +블록 크기를 제한하기 위해 각 호출은 최대 100개의 대기열에 있는 시스템 로그 항목을 처리합니다. 버스트가 제한을 초과하면 나머지 항목은 나중 블록을 위해 대기열에 유지됩니다. -SDK 이벤트와 EVM 방출 사이에는 한 블록(~700ms)의 지연이 있는데, 이는 7일 언본딩 기간 자체에 비해 무시할 수 있는 수준입니다. +SDK 이벤트와 EVM 방출 사이에는 1블록(~700ms) 지연이 있으며, 이는 7일 언본딩 기간 자체에 비해 미미합니다. ## ABI를 찾는 곳 -`StableSystem` 인터페이스, 이벤트 서명 및 발신자 권한 부여 규칙은 [시스템 트랜잭션 참조](/ko/reference/system-transactions-api)에 있습니다. +`StableSystem` 인터페이스, 블록 공간 반환 유형, 이벤트 서명 및 승인 규칙은 [시스템 트랜잭션 참조](/ko/reference/system-transactions-api)에 있습니다. -## 다음 권장 사항 +## 다음으로 이동할 곳 -- [**시스템 트랜잭션 참조**](/ko/reference/system-transactions-api): `IStableSystem` 인터페이스, 가스 계산 및 권한 부여 규칙을 검토하세요. -- [**스테이킹 모듈**](/ko/explanation/staking-module): 시스템 트랜잭션 이벤트로 나타나는 SDK 작업을 확인하세요. -- [**시스템 모듈 개요**](/ko/explanation/system-modules-overview): 사전 컴파일러가 노출하는 모듈 목록으로 돌아갑니다. +- [**시스템 트랜잭션 참조**](/ko/reference/system-transactions-api): `IStableSystem` 인터페이스, 가스 계정 및 승인 규칙을 검토합니다. +- [**스테이킹 모듈**](/ko/explanation/staking-module): 시스템 트랜잭션 이벤트로 나타나는 SDK 작업을 확인합니다. +- [**시스템 모듈 개요**](/ko/explanation/system-modules-overview): 프리컴파일 노출 모듈 목록으로 돌아갑니다. diff --git a/docs/pages/ko/explanation/tech-overview.mdx b/docs/pages/ko/explanation/tech-overview.mdx index a133c71..ace56a4 100755 --- a/docs/pages/ko/explanation/tech-overview.mdx +++ b/docs/pages/ko/explanation/tech-overview.mdx @@ -1,19 +1,19 @@ --- source_path: explanation/tech-overview.mdx -source_sha: 66c5144a0a00b4fc60545e70df03a2260238b7b8 +source_sha: 6e72e9e8a97620c7a9cc7e0ecb4db16891e6020a title: "기술 개요" -description: "스테이블의 4계층 스택(합의, 실행, 저장, RPC)이 스테이블코인 결제 처리량에 최적화된 방식입니다." +description: "스테이블코인 결제를 위해 Stable이 합의, 실행, 스토리지 및 RPC를 조정하는 방법을 이해합니다." diataxis: "explanation" --- # 기술 개요 +Stable의 트랜잭션 파이프라인은 합의, 실행, 스토리지 및 RPC의 네 가지 계층으로 구성됩니다. 표준 EVM 도구를 사용할 수 있으며, Stable 고유의 서브시스템은 최종성, USDT0 가스, 상태 액세스 및 트랜잭션 처리량을 처리합니다. + :::note -**릴리스 상태:** StableBFT, 순차적 Stable EVM, 분할 경로 RPC 계층이 메인넷에 출시되었습니다. OPE, 선택적 RecheckTx, MemIAVL, 2D nonce 및 보장된 블록 공간은 v1.4.0 테스트넷 릴리스 후보에 있습니다. 메인넷 업그레이드 일정은 보류 중입니다. +**릴리스 상태:** Stable v1.8.0이 메인넷에 출시되었습니다. 여기에는 Block-STM 실행, Selective RecheckTx, MemIAVL, 2D 논스 및 보장된 블록 공간이 포함됩니다. ::: -Hardhat, Foundry 또는 모든 표준 EVM 툴링을 사용하여 현재 Stable에 Solidity 또는 Vyper 컨트랙트를 배포할 수 있으며, 컨트랙트는 수정 없이 작동합니다. 변경되는 점: 가스는 USDT0으로 지불되고, 트랜잭션은 단일 슬롯 완결성에 도달하며, 스택의 모든 계층은 스테이블코인 처리량에 최적화되어 있습니다. - 기술 로드맵 -## 1단계: USDT를 위한 기본 계층 +## 1단계: USDT를 위한 기반 레이어 -상태: **메인넷에 라이브.** +상태: **메인넷에 활성.** -### StableBFT: 라이브 +### StableBFT: 활성 -CometBFT를 기반으로 구축된 맞춤형 PoS 합의 프로토콜입니다. 검증자의 1/3까지 결정론적 완결성과 비잔틴 장애 허용을 제공합니다. 현재 구현은 [합의](/ko/explanation/consensus)를 참조하십시오. +CometBFT를 기반으로 구축된 맞춤형 PoS 합의 프로토콜입니다. 검증자의 1/3까지 결정론적 완결성과 비잔틴 장애 허용을 제공합니다. 현재 구현에 대해서는 [합의](/ko/explanation/consensus)를 참조하십시오. -### USDT0을 기본 가스로: 라이브 +### USDT0을 네이티브 가스로 사용: 활성 -USDT0은 가스 지불 및 가치 이전을 위한 기본 자산이며, 동시에 ERC-20 표면(`approve`, `transfer`, `transferFrom`, `permit`)을 지원합니다. [가스 토큰으로서의 USDT0](/ko/explanation/usdt-as-gas-token)을 참조하십시오. +USDT0은 가스 지불 및 가치 전송을 위한 네이티브 자산이며, 동시에 ERC-20 인터페이스(`approve`, `transfer`, `transferFrom`, `permit`)를 지원합니다. [가스 토큰으로서의 USDT0](/ko/explanation/usdt-as-gas-token)을 참조하십시오. ### Stable Pay & Stable Name: 진행 중 -Stable Pay는 기존 Web3 지갑과의 호환성을 유지하면서 신규 사용자의 온보딩을 단순화하도록 설계된 Web2.5 UX 지갑 경험입니다. Stable Name은 원시 EVM 주소를 사람이 읽을 수 있는 식별자로 대체하여 토큰을 주고받을 수 있는 사용자 친화적인 별칭 시스템입니다. +Stable Pay는 기존 Web3 지갑과 호환성을 유지하면서 신규 사용자를 위한 온보딩을 단순화하도록 설계된 Web2.5 UX 지갑 경험입니다. Stable Name은 토큰을 보내고 받을 때 원시 EVM 주소를 사람이 읽을 수 있는 식별자로 대체하는 사용자 친화적인 별칭 시스템입니다. -

2단계: USDT를 위한 경험 계층

+## 2단계: USDT를 위한 경험 레이어 -상태: **테스트넷의 v1.4.0 릴리스 후보.** 메인넷 업그레이드 일정은 미정입니다. USDT 전송 애그리게이터는 개발 중입니다. +상태: **v1.8.0에서 메인넷에 활성.** USDT 전송 애그리게이터는 개발 중입니다. -### MemIAVL 상태 저장소: v1.4.0에 포함 +### MemIAVL 상태 저장소: v1.8.0에서 활성 -MemIAVL은 LevelDB를 단일 메모리 매핑 스냅샷과 추가 전용 쓰기 선행 로그로 대체합니다. RocksDB 기반 VersionDB는 보존된 스냅샷보다 오래된 기록 쿼리를 처리합니다. [저장소 (StableDB)](/ko/explanation/stable-db)를 참조하십시오. +MemIAVL은 LevelDB를 하나의 메모리 매핑 스냅샷과 추가 전용 쓰기 전 로그로 대체합니다. RocksDB 기반 VersionDB는 보존된 스냅샷보다 오래된 과거 쿼리를 처리합니다. [스토리지(StableDB)](/ko/explanation/stable-db)를 참조하십시오. -### 낙관적 병렬 실행: v1.4.0에 포함 +### 낙관적 병렬 실행: v1.8.0에서 활성 -Block-STM은 CPU 코어에서 트랜잭션을 동시에 실행하고, 충돌을 감지하고, 영향을 받는 작업을 재실행합니다. 고정된 블록 내 순서는 검증자 간에 결정론적 상태를 유지합니다. [실행](/ko/explanation/execution)을 참조하십시오. +Block-STM은 CPU 코어에서 트랜잭션을 동시에 실행하고, 충돌을 감지하며, 영향을 받는 작업을 재실행합니다. 고정된 블록 내 순서는 검증자 간에 결정론적 상태를 보존합니다. [실행](/ko/explanation/execution)을 참조하십시오. -### 선택적 RecheckTx: v1.4.0에 포함 +### 선택적 RecheckTx: v1.8.0에서 활성 -블록이 커밋된 후 노드는 영향을 받는 계정의 보류 중인 트랜잭션만 재확인합니다. 애플리케이션 지원이 제공되지 않는 경우 CometBFT는 전체 멤풀 재확인으로 폴백합니다. +블록이 커밋되면 노드는 영향을 받는 계정의 보류 중인 트랜잭션만 다시 확인합니다. 애플리케이션 지원을 사용할 수 없을 때 CometBFT는 전체 멤풀 재확인으로 폴백합니다. -### 2D 논스 및 보장된 블록 공간: v1.4.0에 포함 +### 2D 논스와 보장된 블록 공간: v1.8.0에서 활성 -독립적인 논스 채널은 하나의 막힌 트랜잭션이 동일한 계정의 모든 이후 트랜잭션을 차단하는 것을 방지합니다. 프로토콜 예약 논스 키는 VIP 트래픽을 식별하며, 레인별 가스 할당량은 블록 용량을 예약합니다. [보장된 블록 공간](/ko/explanation/guaranteed-blockspace)을 참조하십시오. +독립적인 논스 채널은 하나의 막힌 트랜잭션이 동일한 계정의 모든 후속 트랜잭션을 차단하는 것을 방지합니다. 프로토콜 예약 논스 키는 엔터프라이즈 트래픽을 식별하며, 레인별 가스 할당량은 블록 용량을 예약합니다. [보장된 블록 공간](/ko/explanation/guaranteed-blockspace)을 참조하십시오. ### USDT 전송 애그리게이터: 계획됨 -USDT0 전송을 그룹화하고 집합적으로 처리하여 트랜잭션당 오버헤드를 줄이고 전체 처리량을 개선하는 집계 메커니즘입니다. [USDT 전송 애그리게이터](/ko/explanation/usdt-transfer-aggregator)를 참조하십시오. +USDT0 전송을 그룹화하고 집단적으로 처리하여 트랜잭션당 오버헤드를 줄이고 전체 처리량을 개선하는 집계 메커니즘입니다. [USDT 전송 애그리게이터](/ko/explanation/usdt-transfer-aggregator)를 참조하십시오. -## 3단계: USDT를 위한 풀스택 최적화 계층 +## 3단계: USDT를 위한 풀 스택 최적화 레이어 상태: **계획됨.** ### Autobahn의 StableBFT -Stable의 CometBFT 기반 합의 계층과 자연스럽게 통합되는 DAG 기반 BFT 합의입니다. 현재 프로토콜은 [StableBFT](/ko/explanation/consensus)를 참조하고, 목표 아키텍처는 [Autobahn](/ko/explanation/autobahn)을 참조하십시오. 내부 개념 증명은 통제된 환경에서 200,000 TPS 이상(합의만)을 시연했습니다. +Stable의 CometBFT 기반 합의 레이어와 자연스럽게 통합되는 DAG 기반 BFT 합의입니다. 현재 프로토콜에 대해서는 [StableBFT](/ko/explanation/consensus)를, 목표 아키텍처에 대해서는 [Autobahn](/ko/explanation/autobahn)을 참조하십시오. 내부 개념 증명은 제어된 환경에서 200,000 TPS(합의 전용) 이상을 시연했습니다. ### StableVM++ -Go 기반 EVM을 C++ 구현으로 대체하는 고성능 실행 엔진입니다. EVM 실행 속도가 최대 6배 향상될 것으로 예상됩니다. +Go 기반 EVM을 C++ 구현으로 대체하는 고성능 실행 엔진입니다. EVM 실행 속도에서 최대 6배 향상을 제공할 것으로 예상됩니다. ### 고성능 RPC -노드 수준 개선(실시간 체인 상태 처리), 노드 통합 인덱싱(저지연 애플리케이션 API), WebSocket을 통한 확장 가능한 pub/sub, 작업 유형에 따라 라우팅하는 하이브리드 로드 밸런서를 포함하는 완전한 RPC 스택입니다. 현재 분할 경로 아키텍처는 [고성능 RPC](/ko/explanation/high-performance-rpc)를 참조하십시오. +노드 수준 개선(실시간 체인 상태 처리), 노드 통합 인덱싱(낮은 지연 시간 애플리케이션 API), WebSocket을 통한 확장 가능한 pub/sub, 및 작업 유형별로 라우팅하는 하이브리드 로드 밸런서를 포함하는 전체 RPC 스택입니다. 현재 분할 경로 아키텍처에 대해서는 [고성능 RPC](/ko/explanation/high-performance-rpc)를 참조하십시오. -## 다음 권장 사항 +## 다음 단계 -- [**아키텍처 개요**](/ko/explanation/core-optimization-overview): 로드맵에 따라 진화하는 스택의 현재 상태를 살펴봅니다. +- [**아키텍처 개요**](/ko/explanation/core-optimization-overview): 로드맵이 발전하는 스택의 현재 상태를 살펴봅니다. - [**토크노믹스**](/ko/reference/tokenomics): 로드맵 전반에 걸쳐 검증자 인센티브에 자금을 지원하는 경제 모델을 검토합니다. - [**기술 개요**](/ko/explanation/tech-overview): 아키텍처 요약으로 돌아갑니다. diff --git a/docs/pages/ko/how-to/track-unbonding.mdx b/docs/pages/ko/how-to/track-unbonding.mdx index a6bb57d..9e3915f 100644 --- a/docs/pages/ko/how-to/track-unbonding.mdx +++ b/docs/pages/ko/how-to/track-unbonding.mdx @@ -1,34 +1,34 @@ --- source_path: how-to/track-unbonding.mdx -source_sha: 5c4d430a5edb73996ba773710b260c58025a04d8 +source_sha: 5918da4d054d3399391dee083017aa5d5317dbfd title: "언본딩 완료 추적" -description: "시스템 트랜잭션을 통해 StableSystem 사전 컴파일러가 내보내는 UnbondingCompleted 이벤트를 구독하세요. 사용자 또는 검증인별로 필터링하고 과거 이벤트를 쿼리하세요." +description: "사용자 또는 검증자에 의한 UnbondingCompleted를 구독하고, StableSystem을 통해 과거 이벤트를 쿼리합니다." diataxis: "how-to" --- # 언본딩 완료 추적 -언본딩 기간이 완료되면 프로토콜은 시스템 트랜잭션을 통해 `StableSystem` 사전 컴파일러 (`0x0000000000000000000000000000000000009999`)를 통해 `UnbondingCompleted` 이벤트를 내보냅니다. 이를 통해 dApp은 사용자 지정 인덱서를 실행하거나 REST 엔드포인트를 폴링하지 않고도 사용자에게 알리고 실시간으로 잔액을 업데이트할 수 있습니다. +언본딩 기간이 완료되면 프로토콜은 시스템 트랜잭션을 통해 `StableSystem` 프리컴파일(`0x0000000000000000000000000000000000009999`)을 통해 `UnbondingCompleted` 이벤트를 발생시킵니다. 이를 통해 dApp은 사용자에게 알림을 보내고, 사용자 정의 인덱서를 실행하거나 REST 엔드포인트를 폴링하지 않고도 실시간으로 잔액을 업데이트할 수 있습니다. :::note -**개념:** 시스템 트랜잭션이 SDK 계층 이벤트를 EVM에 연결하는 방법과 그것이 중요한 이유에 대해서는 [시스템 트랜잭션](/ko/explanation/system-transactions)을 참조하세요. +**개념:** 시스템 트랜잭션이 SDK-계층 이벤트를 EVM에 어떻게 연결하는지, 그리고 왜 중요한지에 대한 내용은 [시스템 트랜잭션](/ko/explanation/system-transactions)을 참조하세요. ::: ## 전제 조건 - [시스템 트랜잭션](/ko/explanation/system-transactions)에 대한 이해. - [스테이킹](/ko/explanation/staking-module), 특히 `undelegate` 및 언본딩 프로세스에 대한 숙지. -- 표준 web3 라이브러리 (예: [ethers.js](https://docs.ethers.org/) v6)를 사용한 컨트랙트 이벤트 구독 및 필터링 경험. +- 표준 web3 라이브러리(예: [ethers.js](https://docs.ethers.org/) v6)를 사용한 컨트랙트 이벤트 구독 및 필터링 경험. ## 개요 -- **컨트랙트 인스턴스 설정**: StableSystem 사전 컴파일러에 대한 컨트랙트 인스턴스를 생성합니다. +- **컨트랙트 인스턴스 설정**: StableSystem 프리컴파일을 위한 컨트랙트 인스턴스를 생성합니다. - **애플리케이션에서 이벤트 처리**: 애플리케이션 로직에 따라 실시간 이벤트를 구독하거나 과거 데이터를 쿼리합니다. - **연결 문제 처리**: 지속적인 WebSocket 구독을 위한 재연결 로직을 구현합니다. ## 1단계: 컨트랙트 인스턴스 설정 -`UnbondingCompleted` 이벤트 ABI를 사용하여 `StableSystem` 사전 컴파일러에 대한 컨트랙트 인스턴스를 생성합니다. +`UnbondingCompleted` 이벤트 ABI를 사용하여 `StableSystem` 프리컴파일을 위한 컨트랙트 인스턴스를 생성합니다. ```typescript // config.ts @@ -38,7 +38,7 @@ export const STABLE_SYSTEM_ADDRESS = "0x0000000000000000000000000000000000009999"; export const STABLE_SYSTEM_ABI = [ - "event UnbondingCompleted(address indexed delegator, address indexed validator, uint256 amount)", + "event UnbondingCompleted(address indexed delegator, address indexed validator, uint64 indexed originBlockHeight, uint256 amount)", ]; export const provider = new ethers.JsonRpcProvider("https://rpc.testnet.stable.xyz"); @@ -49,31 +49,47 @@ export const stableSystem = new ethers.Contract( ); ``` +```text +출력 없음. StableSystem 컨트랙트 인스턴스는 쿼리 또는 구독할 준비가 되었습니다. +``` + ## 2단계: 애플리케이션에서 이벤트 처리 -애플리케이션 로직에 따라 실시간 이벤트를 구독하거나 과거 데이터를 쿼리하거나 둘 다 수행합니다. +애플리케이션 로직에 따라 실시간 이벤트를 구독하거나, 과거 데이터를 쿼리하거나, 둘 다 수행합니다. ### 실시간 구독 -언본딩이 완료될 때 실시간 알림을 위해 `UnbondingCompleted` 이벤트를 구독합니다. 잔액 업데이트 트리거, 알림 전송 또는 대시보드 통계 새로고침에 유용합니다. +언본딩이 완료될 때 실시간 알림을 위해 `UnbondingCompleted` 이벤트를 구독합니다. 잔액 업데이트 트리거, 알림 전송 또는 대시보드 통계 새로 고침에 유용합니다. ```typescript // subscribeBasic.ts +import { ethers } from "ethers"; import { stableSystem } from "./config"; -stableSystem.on("UnbondingCompleted", (delegator, validator, amount, event) => { +stableSystem.on("UnbondingCompleted", (delegator, validator, originBlockHeight, amount, event) => { console.log("Unbonding completed:"); console.log(" Delegator:", delegator); console.log(" Validator:", validator); + console.log(" Origin block:", originBlockHeight.toString()); console.log(" Amount:", ethers.formatEther(amount), "tokens"); console.log(" Block:", event.log.blockNumber); console.log(" Tx Hash:", event.log.transactionHash); }); ``` +```text +Unbonding completed: + Delegator: 0xabcd... + Validator: 0x1234... + Origin block: 36975999 + Amount: 100.0 tokens + Block: 36976000 + Tx Hash: 0x12ab... +``` + ### 사용자별 필터링 -특정 위임자 주소에 대한 이벤트만 수신하려면 인덱싱된 이벤트 매개변수를 사용하여 필터를 생성합니다. +특정 위임자 주소에 대한 이벤트만 수신하려면, 인덱싱된 이벤트 매개변수를 사용하여 필터를 생성합니다. ```typescript // subscribeByUser.ts @@ -83,15 +99,26 @@ import { stableSystem } from "./config"; const userAddress = "0xabcd..."; const filter = stableSystem.filters.UnbondingCompleted(userAddress); -stableSystem.on(filter, (delegator, validator, amount, event) => { - refreshUserBalance(userAddress); - showNotification( - `Your unbonding of ${ethers.formatEther(amount)} tokens completed!` - ); +stableSystem.on(filter, (delegator, validator, originBlockHeight, amount) => { + console.log("User unbonding completed:", { + delegator, + validator, + originBlockHeight, + amount: ethers.formatEther(amount), + }); }); ``` -### 검증인별 필터링 +```text +User unbonding completed: { + delegator: "0xabcd...", + validator: "0x1234...", + originBlockHeight: 36975999n, + amount: "100.0" +} +``` + +### 검증자별 필터링 ```typescript // subscribeByValidator.ts @@ -103,14 +130,28 @@ const validatorFilter = stableSystem.filters.UnbondingCompleted( validatorAddress ); -stableSystem.on(validatorFilter, (delegator, validator, amount) => { - updateValidatorStats(validator, amount); +stableSystem.on(validatorFilter, (delegator, validator, originBlockHeight, amount) => { + console.log("Validator unbonding completed:", { + delegator, + validator, + originBlockHeight, + amount, + }); }); ``` +```text +Validator unbonding completed: { + delegator: "0xabcd...", + validator: "0x1234...", + originBlockHeight: 36975999n, + amount: 100000000000000000000n +} +``` + ### 과거 쿼리 -dApp에서 과거 언본딩 완료 기록을 표시해야 하는 경우 블록 범위가 있는 이벤트 필터를 사용하여 과거 이벤트를 쿼리합니다. +dApp이 과거 언본딩 완료 기록을 표시해야 하는 경우, 블록 범위와 함께 이벤트 필터를 사용하여 과거 이벤트를 쿼리합니다. ```typescript // queryHistory.ts @@ -128,6 +169,7 @@ async function getUnbondingHistory( return events.map((event) => ({ delegator: event.args.delegator, validator: event.args.validator, + originBlockHeight: event.args.originBlockHeight, amount: ethers.formatEther(event.args.amount), blockNumber: event.blockNumber, txHash: event.transactionHash, @@ -140,11 +182,26 @@ const history = await getUnbondingHistory( currentBlock - 1000, currentBlock ); + +console.log(history); +``` + +```text +[ + { + delegator: "0xabcd...", + validator: "0x1234...", + originBlockHeight: 36975999n, + amount: "100.0", + blockNumber: 36976000, + txHash: "0x12ab..." + } +] ``` ## 3단계: 연결 문제 처리 -이벤트 구독은 지속적인 WebSocket 연결에 의존합니다. 프로덕션 dApp을 위한 재연결 로직을 구현합니다. +이벤트 구독은 지속적인 WebSocket 연결에 의존합니다. 프로덕션 dApp을 위해 재연결 로직을 구현합니다. ```typescript // subscribeWithReconnection.ts @@ -154,8 +211,18 @@ import { STABLE_SYSTEM_ADDRESS, STABLE_SYSTEM_ABI } from "./config"; let reconnectAttempts = 0; const MAX_RECONNECT_ATTEMPTS = 5; -function handleUnbonding(delegator: string, validator: string, amount: bigint) { - console.log("Unbonding completed:", { delegator, validator, amount }); +function handleUnbonding( + delegator: string, + validator: string, + originBlockHeight: bigint, + amount: bigint +) { + console.log("Unbonding completed:", { + delegator, + validator, + originBlockHeight, + amount, + }); } function setupEventListener() { @@ -181,8 +248,12 @@ function setupEventListener() { setupEventListener(); ``` -## 다음 권장 사항 +```text +언본딩이 완료되거나 공급자에서 오류가 보고될 때까지 출력 없음. +``` + +## 다음 단계 -- [**시스템 트랜잭션 개념**](/ko/explanation/system-transactions): 프로토콜 수준 이벤트가 EVM에 도달하는 방식을 이해합니다. +- [**시스템 트랜잭션 개념**](/ko/explanation/system-transactions): 프로토콜 수준 이벤트가 EVM에 도달하는 방법을 이해합니다. - [**스테이킹 모듈 개념**](/ko/explanation/staking-module): 위임 및 언본딩 흐름을 검토합니다. -- [**스테이킹 사전 컴파일러 참조**](/ko/reference/staking-module-api): 여기서 추적된 이벤트를 트리거하는 메서드를 찾아봅니다. +- [**스테이킹 프리컴파일 참조**](/ko/reference/staking-module-api): 여기서 추적되는 이벤트를 트리거하는 메서드를 찾아봅니다. diff --git a/docs/pages/ko/how-to/upgrade-node.mdx b/docs/pages/ko/how-to/upgrade-node.mdx index 7e09311..29d4b8e 100755 --- a/docs/pages/ko/how-to/upgrade-node.mdx +++ b/docs/pages/ko/how-to/upgrade-node.mdx @@ -1,262 +1,205 @@ --- source_path: how-to/upgrade-node.mdx -source_sha: c05435b6446847bcf6c1ef3c51961b184f712073 -title: 업그레이드 가이드 -description: "Stable 네트워크 버전 변경을 위한 노드 업그레이드 절차, 업그레이드 유형, 롤백 전략." +source_sha: e2f8ef3c819976fcf7a91e8ff2841f1368c80108 +title: "노드 업그레이드" +description: "노드 ID를 백업하고, 릴리스 파일을 교체하고, 동기화를 확인하여 Stable 노드를 안전하게 업그레이드합니다." diataxis: "how-to" --- -이 가이드는 업그레이드 절차 및 롤백 전략을 포함하여, Stable 노드의 업그레이드 프로세스를 다룹니다. +# 노드 업그레이드 -> 전체 버전 기록 및 업그레이드 세부 정보는 [버전 기록](/ko/reference/testnet-version-history)을 참조하십시오. - -## 업그레이드 유형 - -### 소프트 업그레이드 (구조적 변경 없음) -- 언제든지 수행 가능 -- 하위 호환성 유지 - -### 하드 업그레이드 (구조적 변경) -- 특정 높이에서 업그레이드 필요 -- 하위 호환성 없음 - -### 긴급 업그레이드 -- 주요 보안 수정 사항 -- 즉각적인 조치 필요 -- 체인 일시 중지 필요할 수 있음 - -## v1.4.0 스토리지 마이그레이션 - -v1.4.0은 LevelDB 기반 상태 스토리지를 MemIAVL로 대체합니다. 이 업그레이드에는 일반적인 바이너리 교체 외에 데이터 마이그레이션이 필요합니다. - -네트워크별 업그레이드 지침에 다른 방법이 명시되지 않는 한 로컬 스냅샷 내보내기 및 복원 기능을 사용하십시오. 벤치마킹 결과 표준 복원의 경우 평균 19.4초, 병렬 복원의 경우 약 2.6초의 유효성 검사기 다운타임이 측정되었습니다. - -투표 권한의 최소 2/3가 온라인 상태를 유지하도록 라운드 로빈 순서로 유효성 검사기를 마이그레이션하십시오. 노드가 가장 오래 보관된 스냅샷보다 오래된 기록 쿼리에 응답해야 하는 경우 RocksDB 기반 VersionDB를 구성하십시오. +이 절차를 사용하여 노드별 구성 및 검증자 상태를 보존하면서 Stable 노드를 업그레이드합니다. 항상 네트워크 기록 페이지에서 버전, 바이너리 및 활성화 높이를 가져옵니다. :::warning -아래의 일반 바이너리 전용 절차를 v1.4.0에 사용하지 마십시오. [네트워크 업그레이드](/ko/reference/network-upgrades)에서 최종 네트워크별 바이너리, 업그레이드 높이, 백업 경로 및 복원 명령을 확인하십시오. +상태를 변경하는 업그레이드는 모든 노드가 조정된 높이에서 전환해야 합니다. 중지하거나 교체하기 전에 네트워크, 릴리스 및 업그레이드 높이를 확인하세요. ::: -## 표준 업그레이드 절차 +## 시작하기 전에 -### 1단계: 준비 +필요한 것: -```bash -# 현재 버전 확인 -stabled version --long +- 노드에 대한 셸 액세스 및 서비스 관리 권한 +- 활성 데이터 디렉토리 외부에 보호된 백업을 위한 충분한 디스크 공간 +- 배포에 대한 노드 홈, 서비스 이름 및 설치된 바이너리 경로 +- [메인넷 버전 기록](/ko/reference/mainnet-version-history) 또는 [테스트넷 버전 기록](/ko/reference/testnet-version-history)의 릴리스 항목 -# 중요 데이터 백업 -cp -r ~/.stabled/config ~/stable-backup-$(date +%Y%m%d)/ +아래 예시에서는 이 경로들을 사용합니다. 배포에 맞게 변경하세요. -# 유효성 검사기만 해당: 유효성 검사기 상태 백업 -cp ~/.stabled/data/priv_validator_state.json ~/stable-backup-$(date +%Y%m%d)/ +```bash +export STABLED_HOME="/var/lib/stabled" +export STABLED_SERVICE="stabled" +export STABLED_BIN="/usr/local/bin/stabled" +export STABLED_ARCH="amd64" # ARM 호스트에서는 arm64를 사용합니다. +``` -# 디스크 공간 확인 (현재 데이터 크기의 2배 필요) -df -h ~/.stabled +```text +출력 없음. ``` -### 2단계: 새 바이너리 다운로드 +## 1. 실행 중인 노드 확인 + +노드를 변경하기 전에 현재 빌드 및 동기화 상태를 기록합니다. ```bash -# v1.2.0-rc1 업그레이드 (2026년 1월 22일) -# 아키텍처 선택: +"$STABLED_BIN" version --long +curl -fsS http://localhost:26657/status \ + | jq '{catching_up: .result.sync_info.catching_up, latest_block_height: .result.sync_info.latest_block_height}' +``` -# Linux AMD64 -BINARY_URL="https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.2.0-rc1-linux-amd64-testnet.tar.gz" +```text +<현재 빌드 정보> +{ + "catching_up": false, + "latest_block_height": "<현재 높이>" +} +``` -# 또는 Linux ARM64 -BINARY_URL="https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.2.0-rc1-linux-arm64-testnet.tar.gz" +`catching_up`이 `false`가 될 때까지 계속하지 마십시오. -# 새 바이너리 다운로드 -wget $BINARY_URL +## 2. ID 및 구성 백업 -# 임시 위치에 압축 해제 -tar -xvzf stabled-1.2.0-rc1-linux-*.tar.gz -C /tmp/ +검증자 키와 서명 상태를 비공개로 유지합니다. 이 백업을 노드 운영자에게만 권한이 제한된 암호화된 저장소에 저장합니다. -# 새 버전 확인 -/tmp/stabled version --long +```bash +export STABLED_BACKUP="/var/backups/stabled/pre-upgrade" +sudo install -d -m 0700 "$STABLED_BACKUP" +sudo cp -a "$STABLED_HOME/config" "$STABLED_BACKUP/config" +sudo cp -a "$STABLED_HOME/data/priv_validator_state.json" \ + "$STABLED_BACKUP/priv_validator_state.json" +sudo cp -a "$STABLED_BIN" "$STABLED_BACKUP/stabled" +printf '백업이 %s에 저장되었습니다.\n' "$STABLED_BACKUP" ``` -### 3단계: 업그레이드 수행 - -#### 소프트 업그레이드의 경우 - -```bash -# 노드 중지 -sudo systemctl stop ${SERVICE_NAME} +```text +백업이 /var/backups/stabled/pre-upgrade에 저장되었습니다. +``` -# 현재 바이너리 백업 -sudo mv /usr/bin/stabled /usr/bin/stabled.backup +:::danger +절대 동일한 개인 검증자 키로 두 개의 검증자를 실행하지 마십시오. 키가 중복되면 이중 서명 및 슬래싱이 발생할 수 있습니다. +::: -# 새 바이너리 설치 -sudo mv /tmp/stabled /usr/bin/stabled -sudo chmod +x /usr/bin/stabled +## 3. 릴리스 다운로드 및 검사 -# 설치 확인 -stabled version --long +Stable 메인넷은 블록 `36,976,000`에서 v1.8.0을 활성화했습니다. 호스트 아키텍처에 맞는 아카이브를 다운로드하고 설치 전에 보고된 빌드를 검사합니다. -# 노드 시작 -sudo systemctl start ${SERVICE_NAME} +```bash +export STABLED_RELEASE="v1.8.0" +export STABLED_ARCHIVE="/tmp/stabled-1.8.0-linux-${STABLED_ARCH}-mainnet.tar.gz" +export STABLED_STAGE="/tmp/stabled-v1.8.0" + +curl -fL \ + "https://stable-data-dist.s3.us-east-1.amazonaws.com/mainnet/binary/stabled-1.8.0-linux-${STABLED_ARCH}-mainnet.tar.gz" \ + -o "$STABLED_ARCHIVE" +mkdir -p "$STABLED_STAGE" +tar -xzf "$STABLED_ARCHIVE" -C "$STABLED_STAGE" +"$STABLED_STAGE/stabled" version --long +``` -# 로그 모니터링 -sudo journalctl -u ${SERVICE_NAME} -f +```text + ``` -#### 하드 업그레이드의 경우 +다른 릴리스 또는 테스트넷의 경우 해당 버전 기록 테이블에서 정확한 바이너리 URL을 복사합니다. -```bash -# 업그레이드 높이 모니터링 -while true; do - HEIGHT=$(curl -s localhost:26657/status | jq -r '.result.sync_info.latest_block_height') - echo "현재 높이: $HEIGHT" - if [ $HEIGHT -ge $UPGRADE_HEIGHT ]; then - break - fi - sleep 10 -done - -# 노드는 업그레이드 높이에서 자동으로 중지됩니다. -# 로그에서 중지 메시지 대기 -sudo journalctl -u ${SERVICE_NAME} -f | grep "UPGRADE" - -# 중지되면 업그레이드 수행 -sudo systemctl stop ${SERVICE_NAME} -sudo mv /usr/bin/stabled /usr/bin/stabled.backup -sudo mv /tmp/stabled /usr/bin/stabled - -# 새 바이너리로 시작 -sudo systemctl start ${SERVICE_NAME} -``` +## 4. v1.8.0 구성 준비 -### 4단계: 업그레이드 후 확인 +v1.8.0은 `config.toml`과 `app.toml` 모두에 필요한 설정을 추가합니다. 메인넷 템플릿을 스테이징 디렉토리에 다운로드합니다. ```bash -# 노드 상태 확인 -curl -s localhost:26657/status | jq '.result' - -# 버전 확인 -curl -s localhost:26657/status | jq '.result.node_info.version' +export STABLED_CONFIG_STAGE="/tmp/stable-v1.8.0-config" +mkdir -p "$STABLED_CONFIG_STAGE" +curl -fL \ + "https://stable-data-dist.s3.us-east-1.amazonaws.com/mainnet/configuration/v1.8.0/partners/config.toml" \ + -o "$STABLED_CONFIG_STAGE/config.toml" +curl -fL \ + "https://stable-data-dist.s3.us-east-1.amazonaws.com/mainnet/configuration/v1.8.0/partners/app.toml" \ + -o "$STABLED_CONFIG_STAGE/app.toml" +printf '구성이 %s에 준비되었습니다.\n' "$STABLED_CONFIG_STAGE" +``` -# 피어 확인 -curl -s localhost:26657/net_info | jq '.result.n_peers' +```text +구성이 /tmp/stable-v1.8.0-config에 준비되었습니다. +``` -# 동기화 상태 모니터링 -watch -n 2 'curl -s localhost:26657/status | jq ".result.sync_info"' +이 템플릿에서 시작한 다음 백업에서 모든 노드별 값을 복원합니다. 다음을 최소한 확인하십시오. -# 오류 확인 -sudo journalctl -u ${SERVICE_NAME} --since "10 minutes ago" | grep -i error -``` +- `moniker` 및 `external_address`. +- 영구 피어, 시드 및 비공개 피어 설정. +- API, JSON-RPC, gRPC 및 메트릭 설정. +- 조직별 시간 초과 및 리소스 제한. +- 아카이브 노드의 가지치기 설정. -## 코스모바이저 설정 (자동 업그레이드) +배포된 `app.toml`은 기본 가지치기를 사용합니다. 가지치기된 기록은 로컬 노드에서 재구성할 수 없습니다. v1.8.0은 또한 `inter-block-cache`를 강제로 끕니다. -코스모바이저는 조율된 업그레이드를 위한 업그레이드 프로세스를 자동화합니다. +## 5. 노드 중지 및 파일 설치 -### 설치 +조정된 향후 업그레이드의 경우 노드가 게시된 높이에서 중단될 때까지 기다립니다. v1.8.0 메인넷 높이는 과거이므로 이전 메인넷 노드는 이 설치 전에 중지할 수 있습니다. ```bash -# 코스모바이저 설치 -go install cosmossdk.io/tools/cosmovisor/cmd/cosmovisor@latest +sudo systemctl stop "$STABLED_SERVICE" +systemctl is-active "$STABLED_SERVICE" || true +``` -# 또는 바이너리 다운로드 -wget https://github.com/cosmos/cosmos-sdk/releases/download/cosmovisor%2Fv1.7.0/cosmovisor-v1.7.0-linux-amd64.tar.gz -tar -xzf cosmovisor-v1.7.0-linux-amd64.tar.gz -sudo mv cosmovisor /usr/bin/ +```text +비활성 ``` -### 구성 +스테이징된 바이너리 및 완성된 구성 파일을 설치합니다. ```bash -# 환경 변수 설정 -cat >> ~/.bashrc < /dev/null < +{ + "catching_up": false, + "latest_block_height": "<현재 높이>" +} +``` -```bash -# 노드 중지 -sudo systemctl stop ${SERVICE_NAME} +노드를 정상 작동으로 되돌리기 전에 서비스 로그에서 반복되는 패닉, 합의 실패 또는 구성 구문 분석 오류가 있는지 확인하십시오. -# 현재 상태 백업 (필요한 경우) -cp -r ~/.stabled/data ~/.stabled/data.failed +## Cosmovisor로 향후 업그레이드 자동화 -# 업그레이드 전 스냅샷에서 복원 -cd ~/.stabled -rm -rf data/ -tar -I lz4 -xf ~/snapshots/pre-upgrade-snapshot.tar.lz4 +Cosmovisor는 온체인 업그레이드 핸들러가 구성된 높이에 도달하면 바이너리를 전환할 수 있습니다. [Cosmovisor 문서](https://docs.cosmos.network/main/build/tooling/cosmovisor)를 따르고 해당 거버넌스 제안의 업그레이드 이름을 사용하십시오. -# 이전 바이너리 복원 -sudo mv /usr/bin/stabled.backup /usr/bin/stabled +운영 정책이 구성된 소스를 명시적으로 신뢰하지 않는 한 자동 바이너리 다운로드를 비활성화된 상태로 유지하십시오. 활성화 높이 전에 릴리스 바이너리를 스테이징하고 확인하십시오. -# 노드 시작 -sudo systemctl start ${SERVICE_NAME} -``` +## 릴리스별 지침이 있는 경우에만 롤백 -## 비상 절차 +:::danger +Stable의 릴리스 지침에 필요한 경우가 아니면 활성 데이터 디렉토리를 삭제하거나 이전 스냅샷을 복원하지 마십시오. 최신 릴리스에 의해 작성된 상태에 대해 이전 바이너리를 시작하면 노드가 손상되거나 잘못된 체인을 따를 수 있습니다. +::: -```bash -# 체인이 예기치 않게 중지된 경우 -# 1. Discord에서 지침 확인 -# 2. 마지막으로 확인된 정상 높이에서 상태 내보내기 -stabled export --height > export.json +새 프로세스가 업그레이드된 블록을 실행하기 전에 실패하면 서비스를 중지하고 오류를 검사합니다. 릴리스 노트에서 롤백이 안전하다고 명시된 경우에만 이전 바이너리 및 구성을 복원하십시오. -# 3. 조정된 재시작 지침 대기 -``` +노드가 업그레이드된 블록을 실행한 경우 네트워크 운영자와 복구를 조정하십시오. 복구에는 릴리스별 바이너리 또는 합의된 높이의 신뢰할 수 있는 스냅샷이 필요할 수 있습니다. ## 다음 단계 -- [버전 기록](/ko/reference/testnet-version-history) - 전체 업그레이드 기록 및 릴리스 노트 -- 업그레이드 후 [노드 모니터링](/ko/how-to/monitor-node) -- 일반적인 문제에 대한 [문제 해결](/ko/how-to/troubleshoot-node) 검토 +- [**네트워크 업그레이드**](/ko/reference/network-upgrades): 각 프로토콜 릴리스의 호환성 및 운영자 영향을 식별합니다. +- [**노드 모니터링**](/ko/how-to/monitor-node): 업그레이드 후 동기화, 피어, 리소스 사용량 및 서비스 상태를 확인합니다. +- [**노드 문제 해결**](/ko/how-to/troubleshoot-node): 시작, 네트워킹, 합의 및 저장소 오류를 진단합니다. diff --git a/docs/pages/ko/how-to/use-system-modules.mdx b/docs/pages/ko/how-to/use-system-modules.mdx index 06f3293..216a677 100644 --- a/docs/pages/ko/how-to/use-system-modules.mdx +++ b/docs/pages/ko/how-to/use-system-modules.mdx @@ -1,46 +1,45 @@ --- source_path: how-to/use-system-modules.mdx -source_sha: cfd6ec43ac3c766ae5fdb7d0007a1cb6671ad955 +source_sha: fb55bfe49f1cc321f4a78da45af133aad15ab828 title: "시스템 모듈 사용" -description: "최소한의 ABI와 작동 예시를 사용하여 Solidity 및 ethers.js에서 Stable의 Bank, Distribution 및 Staking 사전 컴파일을 호출합니다." +description: "최소한의 ABI와 작동하는 예시를 사용하여 Solidity 및 ethers.js에서 Stable 프로토콜 사전 컴파일을 호출합니다." diataxis: "how-to" --- # 시스템 모듈 사용 -Stable은 고정 주소의 **사전 컴파일된 계약**을 통해 프로토콜 수준 결제 로직을 노출합니다. 사전 컴파일을 통해 EVM 코드는 Stable SDK 모듈(스테이킹, 보상 분배, STABLE 토큰 작업)을 다시 구현하지 않고도 호출할 수 있습니다. 프로토콜 수준에서 실행되므로 동등한 Solidity 구현보다 훨씬 더 가스 효율적입니다. - -이 가이드에서는 Solidity 및 ethers.js에서 사전 컴파일을 호출하는 방법과 일반 계약 대신 사전 컴파일을 사용해야 하는 경우를 보여줍니다. +Stable은 고정된 주소의 **사전 컴파일된 계약**을 통해 프로토콜 수준 로직을 노출합니다. 애플리케이션 계약에서 Stable SDK 동작을 다시 구현하는 대신 Solidity 또는 ethers.js에서 이러한 사전 컴파일을 호출할 수 있습니다. :::note -**개념**: 시스템 모듈의 기능과 사전 컴파일인 이유에 대한 자세한 내용은 [시스템 모듈](/ko/explanation/system-modules-overview)을 참조하십시오. 모듈별 메서드 시그니처 및 이벤트에 대한 자세한 내용은 [시스템 모듈 참조](/ko/reference/system-modules-api-overview)를 참조하십시오. +**개념**: 시스템 모듈이 하는 일과 사전 컴파일인 이유는 [시스템 모듈](/ko/explanation/system-modules-overview)을 참조하십시오. 모듈별 메서드 시그니처 및 이벤트에 대해서는 [시스템 모듈 참조](/ko/reference/system-modules-api-overview)를 참조하십시오. ::: ## 노출되는 내용 -| **모듈** | **사전 컴파일 주소** | **용도** | +| **모듈** | **사전 컴파일 주소** | **사용 목적** | | :--- | :--- | :--- | | Bank | `0x0000000000000000000000000000000000001003` | STABLE 토큰 전송 및 잔액 작업 | -| Distribution | `0x0000000000000000000000000000000000000801` | 스테이킹 보상 청구, 보상 쿼리, 수수료 관리 | -| Staking | `0x0000000000000000000000000000000000000800` | 위임, 위임 해제, 재위임, 검증자 쿼리 | -| Gov | `0x0000000000000000000000000000000000000805` | 제안, 집계 결과 및 온체인 투표 기록 | +| Distribution | `0x0000000000000000000000000000000000000801` | 스테이킹 보상 청구, 보상 조회, 수수료 관리 | +| Staking | `0x0000000000000000000000000000000000000800` | 위임, 위임 해제, 재위임, 검증자 조회 | +| Gov | `0x0000000000000000000000000000000000000805` | 제안, 집계 결과, 온체인 투표 기록 | | Slashing | `0x0000000000000000000000000000000000000806` | 검증자 서명 정보 및 가동 시간 | -| StableSystem | `0x0000000000000000000000000000000000009999` | 시스템 트랜잭션(언본딩 완료)을 위한 EVM 이벤트 방출 | +| StableSystem | `0x0000000000000000000000000000000000009999` | 보장된 블록스페이스 레인 조회 및 시스템 트랜잭션에 대한 EVM 이벤트 발생 | -이들 모두는 모든 EVM 계약 또는 오프체인 클라이언트에서 호출할 수 있습니다. 주소는 메인넷과 테스트넷에서 안정적이며 동일합니다. +읽기 메서드는 모든 EVM 계약 또는 오프체인 클라이언트에서 호출할 수 있습니다. 일부 상태 변경 메서드는 호출자 승인을 강제하며, `notifySystemTxLogs()`는 프로토콜에서 생성된 시스템 트랜잭션만 허용합니다. 주소는 메인넷과 테스트넷에서 동일합니다. ## 사전 컴파일과 일반 계약을 호출하는 경우 -- 작업이 Stable SDK 모듈(스테이킹, 보상 분배, STABLE 토큰 작업)에 매핑되는 경우 **사전 컴파일을 사용**합니다. 사전 컴파일을 호출하는 것이 더 저렴하고 프로토콜 수준 동작을 트리거하는 유일한 방법입니다. -- 작업이 애플리케이션 로직(에스크로, 가격 책정, 액세스 제어)인 경우 **일반 계약을 사용**합니다. 사용자 지정 권한 부여 또는 유효성 검사가 필요한 경우 사전 컴파일 호출을 사용자 지정 계약에 래핑하십시오. +- **사전 컴파일 사용**: 작업이 Stable SDK 모듈(스테이킹, 보상 분배, STABLE 토큰 작업)에 매핑될 때 사용합니다. 사전 컴파일을 호출하는 것이 비용도 저렴하고 프로토콜 수준 동작을 트리거하는 유일한 방법입니다. +- **일반 계약 사용**: 작업이 애플리케이션 로직(에스크로, 가격 책정, 접근 제어)일 때 사용합니다. 사용자 지정 승인 또는 유효성 검사가 필요한 경우 사전 컴파일 호출을 자체 계약으로 래핑합니다. -사전 컴파일은 애플리케이션 계약을 대체하는 것이 아닙니다. 기본 프로토콜에 대한 안정적인 인터페이스입니다. +사전 컴파일은 애플리케이션 계약을 대체하지 않습니다. 이는 기본 프로토콜에 대한 안정적인 인터페이스입니다. ## Solidity에서 호출 -필요한 메서드에 대한 인터페이스를 선언한 다음, 마치 배포된 계약처럼 사전 컴파일을 호출합니다. +필요한 메서드에 대한 인터페이스를 선언한 다음, 배포된 계약인 것처럼 사전 컴파일을 호출합니다. ```solidity +// SAFE: the precompile address is fixed on Stable. // SPDX-License-Identifier: MIT pragma solidity ^0.8.24; @@ -61,7 +60,7 @@ contract StakingHelper { address constant STAKING_PRECOMPILE = 0x0000000000000000000000000000000000000800; - /// @notice 이 계약에서 검증자에게 STABLE 토큰을 위임합니다. + /// @notice Delegate STABLE tokens to a validator from this contract. function delegateToValidator( string calldata validatorAddress, uint256 amount @@ -73,7 +72,7 @@ contract StakingHelper { ); } - /// @notice 이 계약의 검증자에 대한 현재 위임을 읽습니다. + /// @notice Read the current delegation of this contract to a validator. function myDelegation(string calldata validatorAddress) external view @@ -87,15 +86,11 @@ contract StakingHelper { } ``` -Foundry 또는 Hardhat으로 컴파일 및 배포합니다. 사전 컴파일 주소는 상수 슬롯에서 계약에 번인되므로 배포 후 연결할 것이 없습니다. - -```solidity -// SAFE: 사전 컴파일 주소는 Stable에 고정되어 있으며 변경되지 않습니다. -``` +Foundry 또는 Hardhat으로 컴파일하고 배포합니다. 사전 컴파일 주소는 상수 슬롯에 계약에 직접 기록되므로 배포 후 연결할 것이 없습니다. ## ethers.js에서 호출 -오프체인 클라이언트의 경우, 최소한의 ABI와 동일한 인터페이스를 선언하고 사전 컴파일 주소를 가리키는 계약을 인스턴스화합니다. +오프체인 클라이언트의 경우, 최소 ABI와 동일한 인터페이스를 선언하고 사전 컴파일 주소를 가리키는 계약을 인스턴스화합니다. ```typescript // queryDelegation.ts @@ -115,7 +110,7 @@ const staking = new ethers.Contract( ); const delegator = "0xDelegatorAddress"; -const validator = "stablevaloper1..."; // bech32 검증자 운영자 주소 +const validator = "stablevaloper1..."; // bech32 validator operator address const [shares, balance] = await staking.delegation(delegator, validator); console.log("Delegation shares: ", shares.toString()); @@ -133,13 +128,13 @@ Delegation balance: 1000.0 STABLE ## 시스템 트랜잭션 이벤트 구독 -일부 Stable SDK 작업(예: 언본딩 완료)은 자연적으로 EVM 이벤트를 방출하지 않습니다. Stable은 다음 블록에서 표준 EVM 이벤트를 방출하기 위해 `StableSystem` 사전 컴파일을 호출하는 검증자 생성 트랜잭션인 **시스템 트랜잭션**으로 이러한 격차를 해소합니다. +일부 Stable SDK 작업(예: 언본딩 완료)은 EVM 이벤트를 자연스럽게 발생시키지 않습니다. Stable은 **시스템 트랜잭션**으로 이러한 격차를 해소합니다. 이는 다음 블록에서 표준 EVM 이벤트를 발생시키기 위해 `StableSystem` 사전 컴파일을 호출하는 검증자 생성 트랜잭션입니다. -`UnbondingCompleted`를 보려면 모든 ERC-20 `Transfer` 리스너처럼 사전 컴파일 주소에서 구독하십시오. +`UnbondingCompleted`를 보려면 ERC-20 `Transfer` 리스너처럼 사전 컴파일 주소에서 구독합니다. ```typescript // watchUnbonding.ts -import { ethers } from "ethers"; +import { ethers from "ethers"; const provider = new ethers.JsonRpcProvider("https://rpc.testnet.stable.xyz"); @@ -148,13 +143,14 @@ const STABLE_SYSTEM = "0x0000000000000000000000000000000000009999"; const stableSystem = new ethers.Contract( STABLE_SYSTEM, [ - "event UnbondingCompleted(address indexed delegator, address indexed validator, uint256 amount)", + "event UnbondingCompleted(address indexed delegator, address indexed validator, uint64 indexed originBlockHeight, uint256 amount)", ], provider ); -stableSystem.on("UnbondingCompleted", (delegator, validator, amount, event) => { +stableSystem.on("UnbondingCompleted", (delegator, validator, originBlockHeight, amount, event) => { console.log("Unbonding completed for:", delegator); + console.log("Origin block:", originBlockHeight.toString()); console.log("Amount:", ethers.formatEther(amount), "STABLE"); console.log("Tx:", event.log.transactionHash); }); @@ -169,23 +165,24 @@ npx tsx watchUnbonding.ts ```text Listening for UnbondingCompleted events... Unbonding completed for: 0xabcd... +Origin block: 36975999 Amount: 100.0 STABLE Tx: 0x12ab... ``` -전체 시스템 트랜잭션 메커니즘 및 사용자 필터링/기록 쿼리 패턴에 대한 자세한 내용은 [언본딩 완료 추적](/ko/how-to/track-unbonding)을 참조하십시오. +전체 시스템 트랜잭션 메커니즘과 사용자별 필터링/과거 쿼리 패턴에 대해서는 [언본딩 추적](/ko/how-to/track-unbonding)을 참조하십시오. ## 모듈별 참조 -각 사전 컴파일의 전체 메서드 목록, 이벤트 및 권한 부여 규칙은 해당 참조 페이지에 있습니다. +각 사전 컴파일의 전체 메서드 목록, 이벤트 및 권한 부여 규칙은 참조 페이지에 있습니다. -- [Bank 사전 컴파일](/ko/reference/bank-module-api): STABLE 토큰 전송 및 공급 쿼리. +- [Bank 사전 컴파일](/ko/reference/bank-module-api): STABLE 토큰 전송 및 공급량 조회. - [Distribution 사전 컴파일](/ko/reference/distribution-module-api): 보상 청구 및 수수료. -- [Staking 사전 컴파일](/ko/reference/staking-module-api): 위임, 위임 해제, 재위임, 검증자 쿼리. +- [Staking 사전 컴파일](/ko/reference/staking-module-api): 위임, 위임 해제, 재위임, 검증자 조회. - [시스템 트랜잭션](/ko/reference/system-transactions-api): StableSystem 이벤트 형식 및 권한 부여. -## 다음 권장 사항 +## 다음 단계 -- [**언본딩 완료 추적**](/ko/how-to/track-unbonding): StableSystem 사전 컴파일을 통해 방출된 UnbondingCompleted 이벤트를 구독합니다. +- [**언본딩 완료 추적**](/ko/how-to/track-unbonding): StableSystem 사전 컴파일을 통해 발생한 UnbondingCompleted 이벤트를 구독합니다. - [**시스템 모듈 참조**](/ko/reference/system-modules-api-overview): 모듈별 ABI, 메서드 시그니처 및 이벤트 스키마로 이동합니다. -- [**시스템 모듈 개념**](/ko/explanation/system-modules-overview): Stable이 사전 컴파일을 통해 SDK 모듈을 노출하는 이유를 이해합니다. +- [**시스템 모듈 개념**](/ko/explanation/system-modules-overview): Stable이 SDK 모듈을 사전 컴파일을 통해 노출하는 이유를 이해합니다. diff --git a/docs/pages/ko/reference/network-upgrades.mdx b/docs/pages/ko/reference/network-upgrades.mdx index 8e2994c..9b6b948 100644 --- a/docs/pages/ko/reference/network-upgrades.mdx +++ b/docs/pages/ko/reference/network-upgrades.mdx @@ -1,40 +1,152 @@ --- source_path: reference/network-upgrades.mdx -source_sha: cdcb426b3580e25ac41f039bd750b4356f3803ce +source_sha: 5f1fc33d12d32aa730cd5949a3cf5645be11733f title: "네트워크 업그레이드" -description: "Stable 네트워크 프로토콜 버전에 대한 릴리스 노트: 각 릴리스에서 변경된 사항 및 조치해야 할 사용자." +description: "각 Stable 릴리스에서 변경된 사항과 노드 또는 애플리케이션에 업데이트가 필요한지 여부를 확인하세요." diataxis: "reference" --- # 네트워크 업그레이드 -아래 각 항목은 StableChain 릴리스에서 변경된 내용, 중요한 이유 및 필요한 조치 사항에 대해 설명합니다. 릴리스는 최신 버전부터 나열됩니다. 바이너리, 커밋 해시 및 업그레이드 블록 높이에 대해서는 [메인넷 버전 히스토리](/ko/reference/mainnet-version-history) 및 [테스트넷 버전 히스토리](/ko/reference/testnet-version-history)를 참조하세요. +아래 각 항목은 StableChain 릴리스에서 변경된 내용, 중요성 및 수행해야 할 작업을 설명합니다. 릴리스는 최신순으로 나열됩니다. 바이너리, 커밋 해시 및 업그레이드 블록 높이에 대한 자세한 내용은 [메인넷 버전 기록](/ko/reference/mainnet-version-history) 및 [테스트넷 버전 기록](/ko/reference/testnet-version-history)을 참조하세요. ## 이 노트 읽는 방법 몇 가지 용어가 나옵니다. 의미는 다음과 같습니다. -- **상태를 깨는 업그레이드 (State-breaking upgrade)**: 모든 노드는 거버넌스 제안을 통해 조정된 동일한 블록 높이에서 새 바이너리를 실행해야 합니다. 이러한 릴리스는 버전 히스토리 테이블에 업그레이드 높이가 있습니다. 검증자를 실행하는 경우, 일정에 맞춰 업그레이드하지 않으면 노드가 체인을 따르지 않습니다. -- **하위 호환 가능한 업그레이드 (Backward-compatible upgrade)**: 새 바이너리가 이전 바이너리와 호환되므로, 조정된 전환이 필요하지 않습니다. 이러한 릴리스에는 업그레이드 높이가 없습니다. 바이너리를 교체하여 원하는 시점에 언제든지 업그레이드할 수 있습니다. -- **가스 면제 (Gas waiver)**: 트랜잭션 수수료를 후원자가 부담하여 발신자가 가스 토큰을 보유하지 않고도 트랜잭션을 처리할 수 있도록 하는 StableChain 기능입니다. -- **시스템 트랜잭션 (System transaction)**: 일반 사용자가 아닌 프로토콜 자체가 내부 작업을 실행하기 위해 발행하는 특별한 트랜잭션입니다. -- **프리컴파일 (Precompile)**: 고정된 주소에 위치한 내장 컨트랙트로, EVM 바이트코드 대신 네이티브 코드를 실행하여 빠르게 처리해야 하는 일반적인 작업에 사용됩니다. +- **상태를 깨는 업그레이드**: 모든 노드는 거버넌스 제안을 통해 조정된 동일한 블록 높이에서 새 바이너리를 실행해야 합니다. 이러한 릴리스는 버전 기록 테이블에 업그레이드 높이가 있습니다. 검증자를 실행하는 경우 일정에 따라 업그레이드해야 합니다. 그렇지 않으면 노드가 체인을 따르지 않습니다. +- **하위 호환 가능한 업그레이드**: 새 바이너리는 이전 바이너리와 함께 작동하므로 조정된 전환이 없습니다. 이러한 릴리스에는 업그레이드 높이가 없습니다. 바이너리를 교체하여 원하는 시기에 업그레이드할 수 있습니다. +- **가스 면제**: 스폰서가 트랜잭션 수수료를 지불할 수 있도록 하는 StableChain 기능이므로 발신자는 가스 토큰을 보유하지 않고도 트랜잭션을 수행할 수 있습니다. +- **시스템 트랜잭션**: 일반 사용자가 아닌 프로토콜 자체에서 발행하는 특수 트랜잭션으로, 내부 작업을 실행하는 데 사용됩니다. +- **프리컴파일**: 고정 주소에 있는 내장 계약으로, EVM 바이트코드 대신 네이티브 코드를 실행하며, 빨라야 하는 일반적인 작업에 사용됩니다. -노드가 실행 중인 버전을 확인하려면 다음을 수행하세요. +노드가 실행 중인 버전을 확인하려면 다음을 수행합니다. ```bash stabled version ``` ```text -v1.3.1 +v1.8.0 ``` -## v1.4.0 (예정) :badge[테스트넷]{warning} +## v1.8.0 :badge[현재]{success} -성능 및 예측 가능성 릴리스로, 현재 테스트넷에서 릴리스 후보로 운영 중이며 아직 메인넷에는 적용되지 않았습니다. 이 릴리스는 블록 처리 속도 향상과 우선 순위 트래픽의 트랜잭션 포함 예측 가능성이라는 두 가지 주제 아래 네 가지 변경 사항을 그룹화합니다. +2026년 8월 26일 블록 `36,976,000`에서 활성화된 상태 머신을 깨는 메인넷 업그레이드입니다. 이 업그레이드는 더 빠른 블록 처리 및 우선 순위 트래픽에 대한 예측 가능한 포함이라는 두 가지 주제 아래 네 가지 변경 사항을 그룹화합니다. -| **구상** | **블록 단계** | **변경 내용** | **예상 결과** | +| **이니셔티브** | **블록 단계** | **변경 사항** | **의도된 결과** | | :--- | :--- | :--- | :--- | -| 낙관적 병렬 실행(OPE) | 실행 | 블록-STM이 순차적인 트랜잭션 실행을 대체합니다. | 멀티코어 실행, 약 10,000 TPS 목표. | -| 선택적 RecheckTx | 커밋 후 멤풀 재확인 | 노드는 커밋된 블록에 의해 +| 낙관적 병렬 실행(OPE) | 실행 | Block-STM이 순차적 트랜잭션 실행을 대체합니다. | 약 10,000 TPS를 목표로 하는 멀티코어 실행. | +| 선택적 RecheckTx | 커밋 후 멤풀 재확인 | 노드는 커밋된 블록에 의해 변경된 계정에서만 트랜잭션을 재확인합니다. | 측정된 최상의 경우 지속적인 처리량이 최대 두 배 증가하고 노드 CPU 사용량은 31~34% 감소합니다. | +| MemIAVL | 상태 지속성 | 메모리 매핑된 스냅샷과 WAL(쓰기 전 로그)이 LevelDB 기반 저장소를 대체합니다. | 쓰기 증폭이 10~50배에서 약 1회 쓰기로 감소합니다. | +| 2D 논스 및 엔터프라이즈 블록스페이스 | 제출 및 블록 제안 | 독립적인 논스 채널이 예약된 레인별 가스 용량과 결합됩니다. | 적격 엔터프라이즈 트랜잭션에 대한 결정론적 다음 블록 포함. | + +이러한 변경 사항은 단일 블록 라이프사이클의 여러 단계를 다룹니다. + +1. **제출**: 2D 논스를 사용하면 계정이 독립적인 논스 채널을 통해 트랜잭션을 제출할 수 있습니다. 한 채널에서 중단된 트랜잭션은 다른 채널을 차단하지 않습니다. +2. **제안**: 보장된 블록스페이스는 블록을 엔터프라이즈, 트랜잭션 유형 및 일반 레인으로 나눕니다. 각 레인에는 제안 및 유효성 검사 중에 적용되는 예약된 가스 예산이 있습니다. +3. **실행**: OPE는 Block-STM을 통해 트랜잭션을 동시에 실행한 다음 고정된 블록 내 순서에 대해 유효성을 검사합니다. 모든 노드는 여전히 동일한 상태를 생성합니다. +4. **커밋**: MemIAVL은 하나의 메모리 매핑된 스냅샷에 대해 변경 사항을 WAL에 추가합니다. 이렇게 하면 LevelDB 압축 및 반복적인 디스크 쓰기가 방지됩니다. +5. **커밋 후 재확인**: 선택적 RecheckTx는 블록의 상태 변경 델타를 사용하여 전체 멤풀을 스캔하는 대신 영향을 받는 발신자만 재확인합니다. + +### 처리량 변경 사항 + +OPE는 트랜잭션 실행을 하나의 CPU 코어에서 여러 코어로 이동합니다. 트랜잭션은 낙관적으로 실행되고, 충돌은 재실행을 트리거하며, 고정된 트랜잭션 순서는 결정론적 결과를 유지합니다. + +선택적 RecheckTx는 각 커밋 후에 작업을 제거합니다. 고유한 발신자의 보류 중인 트랜잭션 10,000개에 대한 최상의 테스트에서 처리량은 700 TPS에서 1,400 TPS로 증가했습니다. 더 일반적인 워크로드의 예상 개선은 1.5-1.7배입니다. CometBFT는 애플리케이션이 선택적 재확인을 지원하는지 감지하고 지원하지 않는 경우 전체 재확인으로 폴백합니다. + +MemIAVL은 상태 저장소 경로에서 LevelDB를 제거합니다. 쓰기는 원시 변경 세트를 포함하는 순차적 WAL 항목이 됩니다. 읽기는 운영 체제의 페이지 캐시로의 포인터 조회입니다. RocksDB가 지원하는 별도의 VersionDB는 가장 오래된 보존된 스냅샷보다 오래된 기록 상태를 제공합니다. + +### 예측 가능한 포함 + +2D 논스는 각 계정에 여러 독립적인 논스 채널을 제공합니다. `NonceKey`가 채널을 선택합니다. `NonceKey = 0`은 일반적인 EVM 호환 시퀀스를 유지하는 반면, 프로토콜은 `uint64` 범위의 상위 절반을 자체 용도로 예약합니다. `MaxUint64`는 `TimeoutTimestamp`를 사용하여 리플레이 방지를 위한 정렬되지 않은 트랜잭션을 표시합니다. + +이 릴리스는 기존 EVM 트랜잭션 형식과 함께 트랜잭션 유형 `0x3F`인 `CustomTx`를 추가합니다. 비트 63이 설정된 `NonceKey`는 `MaxUint64`를 제외한 엔터프라이즈 레인 트랜잭션을 식별합니다. + +보장된 블록스페이스는 각 블록을 별도의 가스 할당량을 가진 엔터프라이즈, 트랜잭션 유형 및 일반 레인으로 나눕니다. 거버넌스는 하나의 `MsgUpdateParams` 제안을 통해 레인 매개변수를 제어하며, 승인된 업데이트는 다음 블록에 적용됩니다. + +메인넷 활성화는 `max_blockspace_gas_weight = 20`과 가중치 `50`을 가진 하나의 엔터프라이즈 레인을 시드했습니다. 트랜잭션 유형 레인은 시드하지 않았습니다. 적격 엔터프라이즈 트랜잭션은 검증자가 정직하게 행동하고 네트워크가 동기 상태를 유지할 때 결정론적 다음 블록 포함을 받습니다. + +`StableSystem` 프리컴파일은 이제 `blockspaceLanes()`를 노출합니다. 모든 클라이언트는 `eth_call`을 통해 활성 레인 레지스트리를 쿼리하고 프로토콜의 분류 규칙을 재현할 수 있습니다. + +레인 모델에 대한 자세한 내용은 [보장된 블록스페이스](/ko/explanation/guaranteed-blockspace)를 참조하거나 쿼리 ABI에 대한 [StableSystem 참조](/ko/reference/system-transactions-api)를 참조하십시오. + +### 활성화 및 노드 구성 + +v1.8.0 핸들러는 모듈 마이그레이션을 실행하고, NonceKey 프리컴파일을 활성화하고, EIP-2935 기록 저장소를 설치하고, `max_gas_per_tx`를 `40,000,000`으로 설정합니다. + +이 릴리스는 `config.toml`과 `app.toml` 모두에 구성 키를 추가합니다. 운영자는 활성화 전에 v1.8.0 템플릿을 설치한 다음 노드별 설정을 복원해야 했습니다. 문서화된 메인넷 업그레이드에는 상태 내보내기, 가져오기 또는 스냅샷 재설정이 필요하지 않았습니다. + +바이너리는 `inter-block-cache`를 강제로 비활성화합니다. 아카이브 노드 운영자는 기본 `app.toml` 템플릿을 설치한 후 원래 가지치기 설정을 복원해야 합니다. + +### 안정성 및 보안 변경 사항 + +- 논스는 최종 상태에 대해 확인되어 교차 블록 트랜잭션 리플레이를 닫습니다. +- 제안 처리는 승인 및 합의 시 레인 예산 및 트랜잭션별 가스 상한을 적용합니다. +- 순차 및 Block-STM 실행은 이제 동일한 누적 EVM 로그 인덱스와 `LastResultsHash`를 생성합니다. +- JSON-RPC는 비용이 많이 드는 요청, WebSocket 구독, 증명 저장소 키 및 추적 출력에 제한을 적용합니다. +- 스트리밍 블록 결과 및 `BlockResultsForLogs`는 대규모 로그 쿼리 중에 메모리 사용량을 제한합니다. +- MemIAVL 및 VersionDB는 버전 격차에서 실패 시 닫히고 중단된 WAL 또는 스냅샷 쓰기에서 안전하게 복구됩니다. + +**조치해야 할 대상:** 활성화 후 조인하거나 업그레이드하는 노드는 v1.8.0 바이너리 및 구성 템플릿을 사용해야 합니다. [노드 업그레이드](/ko/how-to/upgrade-node)를 따르고 [메인넷 버전 기록](/ko/reference/mainnet-version-history)에서 현재 바이너리를 확인하십시오. + +## v1.3.1 + +하위 호환 패치입니다. 조정된 업그레이드 높이 없이 출시되었으므로 노드 운영자는 언제든지 바이너리를 교체하여 채택할 수 있었습니다. + +## v1.3.0 + +가스 면제 기능을 더욱 유연하게 만든 보안 중심의 상태를 깨는 업그레이드입니다. 가스 면제 변경으로 인해 지갑 및 거래소와 같은 새로운 파트너가 매번 상태를 깨는 업그레이드가 필요 없이 나중에 거버넌스 제안을 통해 온보딩될 수 있습니다. + +**조치해야 할 대상:** 모든 노드 운영자는 예정된 높이에서 업그레이드해야 합니다. 정확한 높이는 [메인넷 버전 기록](/ko/reference/mainnet-version-history)을 참조하십시오. + +**보안 개선 사항:** + +- 비공개 JSON-RPC 네임스페이스는 더 이상 등록되지 않으며, `AllowInsecureUnlock=true`일 때만 서명 API가 활성화됩니다. +- 가스 면제 입력이 강화되었습니다: 주소는 EIP-55 표준 형식을 사용해야 하며, 쿼리 입력은 길이 및 형식 제한이 있으며, 래퍼 유형, 체인 ID 및 EIP-7702 내부 트랜잭션 유효성 검사가 강화되었습니다. +- 시스템 트랜잭션은 이제 `from` 주소뿐만 아니라 `to` 주소 및 메서드 선택자에 대해서도 유효성이 검사됩니다. 이는 수수료 없는 실행을 트리거할 수 있는 경로를 차단합니다. +- 프라하 프리컴파일 주소 범위가 차단된 주소 목록에 추가되었으며, 알 수 없는 프리컴파일 메서드는 이제 쿼리 가스가 필요합니다. + +**버그 수정 및 안정성:** + +- 실패한 상태 저장 프리컴파일 호출에 대한 가스 회계가 수정되었습니다. +- ERC-20 내부 호출 실패 후 환불 비활성화 상태 누출이 해결되었습니다. +- 프리컴파일 웜셋 추적 및 `COINBASE` opcode 동작이 수정되었습니다. +- EIP-7702 권한 부여 롤백이 사양에 맞게 조정되었습니다. +- `from=0x0`으로 보고된 시스템 트랜잭션 응답, `feeHistory` 오류 로깅 및 기록 전체 트랜잭션 응답에서 체인 ID 일관성이 수정되었습니다. + +## v1.2.2 + +StableChain을 공식 업스트림 합의 릴리스와 일치시키고 두 가지 쿼리 동작을 정리하는 하위 호환 선택적 업그레이드입니다. + +**조치해야 할 대상:** 아무도 필요하지 않습니다. 이 업그레이드는 거버넌스 제안이 필요하지 않습니다. 노드 운영자는 편리할 때마다 바이너리를 교체하여 채택할 수 있습니다. + +**변경 사항:** + +- CometBFT가 공식 `v0.38.21`로 업그레이드되었습니다. 이는 v1.1.4에서 이전에 배포된 보안 패치를 따르며, 외부 파트너가 네트워크가 실행하는 정확한 합의 버전을 확인할 수 있도록 합니다. +- 가스 면제 트랜잭션 쿼리에서 중복 로그 인덱스가 제거되었습니다. +- 시스템 트랜잭션 쿼리에 대한 RPC 응답에 안전 장치가 추가되었습니다. + +## v1.2.1 + +악용될 경우 체인을 중단시킬 수 있는 두 가지 문제를 해결한 하위 호환 핫픽스입니다. + +**조치해야 할 대상:** 검증자는 업그레이드해야 합니다. RPC 제공자를 포함한 다른 노드 운영자의 경우 업그레이드는 선택 사항입니다. 거버넌스 제안이 필요하지 않습니다. + +**수정 사항:** + +- 사용자가 `MsgEthereumTx.From == 0x1`을 설정하여 인증을 우회하고 시스템 전용 프리컴파일을 호출한 다음 스푸핑된 트랜잭션을 사용하여 `ProcessProposal`이 블록을 반복적으로 거부하고 합의를 중단시키도록 강제할 수 있는 시스템 트랜잭션 스푸핑 경로를 닫았습니다. +- `ExtensionOptionsWaiver` 트랜잭션이 `CheckTx`를 통과할 수 있지만 `ProcessProposal`이 전체 블록을 거부하도록 만들 수 있는 멤풀 포이즌 체인 중단이 수정되었습니다. + +## 이전 릴리스 + +자세한 릴리스 노트는 v1.2.1부터 시작합니다. v1.2.0 및 이전 릴리스(제네시스 릴리스 포함)에 대한 바이너리, 커밋 해시 및 업그레이드 높이는 버전 기록 테이블을 참조하십시오. + +- [메인넷 버전 기록](/ko/reference/mainnet-version-history): 모든 메인넷 버전과 바이너리 및 업그레이드 높이. +- [테스트넷 버전 기록](/ko/reference/testnet-version-history): 릴리스 후보를 포함한 모든 테스트넷 버전. + +## 다음으로 이동할 곳 + +- [**노드 업그레이드**](/ko/how-to/upgrade-node): 노드를 새 버전으로 이동하는 단계별 절차를 따르십시오. +- [**메인넷 버전 기록**](/ko/reference/mainnet-version-history): 모든 메인넷 릴리스에 대한 커밋 해시, 바이너리 및 업그레이드 높이를 찾아보십시오. +- [**메인넷 정보**](/ko/reference/mainnet-information): 체인 ID, RPC 엔드포인트 및 현재 네트워크 매개변수를 가져옵니다. diff --git a/docs/pages/ko/reference/system-transactions-api.mdx b/docs/pages/ko/reference/system-transactions-api.mdx index 4a55733..93ded86 100644 --- a/docs/pages/ko/reference/system-transactions-api.mdx +++ b/docs/pages/ko/reference/system-transactions-api.mdx @@ -1,360 +1,179 @@ --- source_path: reference/system-transactions-api.mdx -source_sha: 14ee7e0538b5323f809b63454db35d954d8db488 -title: "시스템 트랜잭션 레퍼런스" -description: "StableSystem 프리컴파일 레퍼런스: 인터페이스, 발신자 인증, 배치 제한, 가스 회계." +source_sha: a8f5d4cbdfe52da5101751e74b8efb7a8390d16d +title: "시스템 트랜잭션 참조" +description: "StableSystem 프리컴파일을 통해 보장된 블록 공간 레인을 쿼리하고 프로토콜 이벤트를 소비합니다." diataxis: "reference" --- -# 시스템 트랜잭션 레퍼런스 +# 시스템 트랜잭션 참조 + +`StableSystem` 프리컴파일은 고정된 EVM 계약 인터페이스를 통해 Stable 프로토콜 데이터 및 이벤트를 노출합니다. v1.8.0에서는 모든 클라이언트가 보장된 블록 공간 레지스트리를 쿼리할 수 있으며, 프로토콜에서 생성된 트랜잭션만 시스템 로그를 내보낼 수 있습니다. :::note -**개념:** 시스템 트랜잭션이 SDK 이벤트를 EVM에 어떻게 연결하며 왜 중요한지에 대해서는 [시스템 트랜잭션](/ko/explanation/system-transactions)을 참조하세요. +시스템 트랜잭션 흐름 및 보안 모델에 대한 자세한 내용은 [시스템 트랜잭션](/ko/explanation/system-transactions)을 참조하십시오. ::: -## 개요 - -시스템 트랜잭션은 Stable 프로토콜이 Stable SDK 작업에 대해 EVM 이벤트를 발생시킬 수 있는 방법을 제공합니다. 언본딩 완료와 같은 스테이킹 이벤트가 SDK 레이어에서 발생하면, 프로토콜은 자동으로 해당 이벤트를 발생시키는 EVM 트랜잭션을 생성합니다. 이를 통해 이러한 작업들이 EVM 도구 및 애플리케이션에 완전히 가시화됩니다. - -## 동기 - -여러분과 Stable 위의 애플리케이션은 `eth_getLogs`와 같은 표준 EVM 인터페이스를 통해 블록체인 이벤트를 모니터링하기를 기대합니다. 하지만 중요한 작업들은 자연스럽게 EVM 이벤트를 발생시키지 않는 Stable SDK 모듈에서 일어납니다. 이로 인해 가시성 격차가 발생합니다: EVM dApp은 사용자의 토큰이 언제 언본딩을 마치는지 쉽게 추적할 수 없습니다. - -시스템 트랜잭션은 이 격차를 메웁니다. 스테이킹 모듈이 언본딩 작업을 완료하면, Stable의 x/stable 모듈이 이벤트를 감지하고 StableSystem 프리컴파일(`0x0000000000000000000000000000000000009999`)을 호출하는 시스템 트랜잭션을 생성합니다. 그러면 프리컴파일은 어떤 dApp이든 구독할 수 있는 적절한 EVM 이벤트를 발생시킵니다. 시스템 트랜잭션은 프로토콜만 사용할 수 있는 특별한 발신자 주소(`0x8888888888888888888888888888888888888888`)로 실행됩니다. 이는 누구도 프로토콜 이벤트를 위조하지 못하도록 막으면서 이벤트 발생을 신뢰가 필요 없고 온체인에서 검증 가능하게 유지합니다. - -## 사양 +## 계약 -시스템 트랜잭션은 세 가지 주요 구성 요소를 통해 작동합니다: x/stable 모듈의 EndBlocker, PrepareProposal 핸들러, 그리고 StableSystem 프리컴파일입니다. +프리컴파일은 메인넷과 테스트넷에서 동일한 주소를 사용합니다: -### 아키텍처 개요 +`0x0000000000000000000000000000000000009999` -시스템 트랜잭션 아키텍처 +| **메서드** | **셀렉터** | **액세스** | **가스 한도** | **목적** | +| :--- | :--- | :--- | :--- | :--- | +| `blockspaceLanes()` | `0x2c0ac3be` | 누구나, 읽기 전용 | `10,000` | 활성 엔터프라이즈 및 트랜잭션 유형 레인 레지스트리를 반환합니다. | +| `notifySystemTxLogs()` | `0xe8e983b7` | 시스템 트랜잭션 발신자만 | `50,000` | 대기 중인 시스템 로그 항목을 최대 100개까지 처리합니다. | -### StableSystem 프리컴파일 - -StableSystem 프리컴파일은 `0x0000000000000000000000000000000000009999`에 위치하며 EVM 이벤트를 발생시켜야 하는 프로토콜 수준의 작업을 처리합니다. 현재는 언본딩 완료 알림을 지원합니다. +v1.8.0 ABI에 이 솔리디티 인터페이스를 사용하십시오. ```solidity -interface IStableSystem { - /// @notice Processes queued unbonding completions and emits EVM events - /// @param blockHeight The block height at which to process completions - /// @dev Only callable by system transactions (from = 0x8888888888888888888888888888888888888888) - /// @dev Processes up to 100 completions per call - /// @dev Automatically deletes processed completions from the queue - function notifyUnbondingCompletions(int64 blockHeight) external; - - /// @notice Emitted when an unbonding operation completes - /// @param delegator The address that delegated the tokens - /// @param validator The validator address the tokens were delegated to - /// @param amount The amount of tokens that finished unbonding (in uusdc) - event UnbondingCompleted( - address indexed delegator, - address indexed validator, - uint256 amount - ); - - /// @notice The caller is not authorized (not system transaction sender) - error Unauthorized(); +// SAFE: This interface matches the Stable v1.8.0 StableSystem ABI. +struct EnterpriseLane { + uint64 id; + string name; + uint32 weight; } -``` - -### 시스템 트랜잭션 발신자 - -시스템 트랜잭션은 `0x8888888888888888888888888888888888888888`을 발신자 주소로 사용합니다. 이 주소는: - -- 서명 검증이 필요하지 않습니다 -- PrepareProposal에서 생성된 트랜잭션에서만 사용할 수 있습니다 -- 사용자나 컨트랙트가 위조할 수 없습니다 -- SystemTxDecorator ante 핸들러를 통해 수수료 공제를 건너뜁니다 - -EVM은 `msg.sender == 0x8888888888888888888888888888888888888888`을 확인하여 시스템 트랜잭션을 인식합니다. 프리컴파일은 이를 사용하여 프로토콜 전용 작업을 제한할 수 있습니다. - -### 이벤트 기반 흐름 - -사용자의 언본딩 기간이 완료되면 다음과 같은 일이 발생합니다: - -1. **Stable SDK 레이어:** 스테이킹 모듈의 EndBlocker가 언본딩을 완료하고 위임자 주소, 검증자 주소, 금액과 함께 EventTypeCompleteUnbonding을 발생시킵니다. -2. **감지:** x/stable 모듈의 EndBlocker가 스테이킹 이후에 실행되어 블록의 이벤트 로그에서 언본딩 이벤트를 스캔합니다. 각 완료에 대해, 위임자 주소, 검증자 주소, 금액, 블록 높이와 함께 상태에 항목을 큐에 추가합니다. -3. **시스템 TX 생성:** 다음 블록의 PrepareProposal에서, 앱은 큐에 들어 있는 모든 완료를 쿼리합니다. 항목이 존재하면, 현재 블록 높이와 함께 StableSystem.notifyUnbondingCompletions(blockHeight)를 호출하는 시스템 트랜잭션을 생성합니다. 이 트랜잭션은 어떤 사용자 트랜잭션보다도 앞서 블록의 맨 앞에 위치합니다. -4. **실행:** 블록 실행 중에 시스템 트랜잭션이 먼저 실행됩니다. 프리컴파일은 해당 블록 높이에서 큐에 들어 있는 완료를 상태에서 쿼리하고, 각각(최대 100개)에 대해 UnbondingCompleted 이벤트를 발생시키며, 큐에서 삭제합니다. -5. **EVM 가시성:** 이벤트는 트랜잭션 영수증과 로그에 나타나, eth\_getLogs 쿼리, 블록 탐색기, 그리고 StableSystem 프리컴파일을 모니터링하는 모든 애플리케이션에 가시화됩니다. - -### 배치 처리 -블록이 너무 커지는 것을 방지하기 위해, 시스템은 블록당 최대 100개의 언본딩 완료를 처리합니다. 150개의 완료가 큐에 들어 있으면: - -- 블록 N: 완료 0-99를 처리하는 시스템 트랜잭션 생성 -- 블록 N+1: 완료 100-149를 처리하는 시스템 트랜잭션 생성 - -프리컴파일은 calldata로 완료 데이터를 받는 대신 상태를 직접 쿼리합니다. 이렇게 하면 트랜잭션 크기를 예측 가능하게 유지하고 비싼 calldata에서 더 저렴한 상태 읽기로 데이터를 옮길 수 있습니다. - -## 사용 예제 - -가장 일반적인 사용 사례는 사용자의 언본딩 기간이 완료될 때 사용자에게 알려야 하는 스테이킹 대시보드입니다. 다음은 언본딩 완료에 대한 리스너를 설정하는 방법입니다. - -```javascript -import { ethers } from 'ethers'; - -// StableSystem precompile address -const STABLE_SYSTEM_ADDRESS = '0x0000000000000000000000000000000000009999'; - -// ABI for the UnbondingCompleted event -const STABLE_SYSTEM_ABI = [ - 'event UnbondingCompleted(address indexed delegator, address indexed validator, uint256 amount)' -]; - -// Connect to the Stable network -const provider = new ethers.JsonRpcProvider('https://rpc.testnet.stable.xyz'); -const stableSystem = new ethers.Contract( - STABLE_SYSTEM_ADDRESS, - STABLE_SYSTEM_ABI, - provider -); - -// Subscribe to all unbonding completions -stableSystem.on('UnbondingCompleted', (delegator, validator, amount, event) => { - console.log('Unbonding completed!'); - console.log('Delegator:', delegator); - console.log('Validator:', validator); - console.log('Amount:', ethers.formatEther(amount), 'tokens'); - console.log('Block:', event.log.blockNumber); - console.log('Tx Hash:', event.log.transactionHash); -}); - -``` - -이 리스너는 어떤 사용자의 언본딩이 완료될 때마다 실행됩니다. 프로덕션 dApp의 경우, 아래와 같이 특정 사용자에 대한 이벤트를 필터링하세요. - -### 특정 사용자에 대한 이벤트 필터링 - -특정 위임자 주소에 대한 이벤트만 받으려면, 인덱싱된 이벤트 매개변수를 사용하여 필터를 생성하세요: - -```javascript -// Only watch unbondings for a specific user -const userAddress = '0xabcd...'; - -const filter = stableSystem.filters.UnbondingCompleted(userAddress); - -stableSystem.on(filter, (delegator, validator, amount, event) => { - // This only fires for the specified user's unbondings - showNotification(`Your unbonding of ${ethers.formatEther(amount)} tokens completed!`); - refreshUserBalance(userAddress); -}); -``` - -검증자별 대시보드를 구축하는 경우 검증자로도 필터링할 수 있습니다: - -```javascript -// Watch all unbondings from a specific validator -const validatorAddress = '0x1234...'; - -const validatorFilter = stableSystem.filters.UnbondingCompleted(null, validatorAddress); - -stableSystem.on(validatorFilter, (delegator, validator, amount) => { - updateValidatorStats(validator, amount); -}); -``` - -### 과거 이벤트 쿼리 - -dApp이 과거의 언본딩 완료 내역을 표시해야 하는 경우, 블록 범위와 함께 이벤트 필터를 사용하여 과거 이벤트를 쿼리할 수 있습니다: - -```javascript -// Get all unbondings for a user in the last 1000 blocks -const currentBlock = await provider.getBlockNumber(); -const filter = stableSystem.filters.UnbondingCompleted(userAddress); - -const events = await stableSystem.queryFilter( - filter, - currentBlock - 1000, - currentBlock -); - -const unbondingHistory = events.map(event => ({ - delegator: event.args.delegator, - validator: event.args.validator, - amount: ethers.formatEther(event.args.amount), - blockNumber: event.blockNumber, - txHash: event.transactionHash -})); - -console.log('Recent unbondings:', unbondingHistory); - -``` - -## 통합 가이드 - -### 1단계: Stable System 컨트랙트 인터페이스 추가 +struct TxTypeLane { + uint64 id; + string name; + address[] toAddrs; + bytes4[] methods; + uint8[] txTypes; + uint64[] nonceKeys; + address[] senders; + uint32 weight; + bool noOverflow; +} -먼저, 프로젝트에 StableSystem 프리컴파일 인터페이스를 추가합니다. Foundry나 Hardhat을 사용하는 경우, 새 인터페이스 파일을 생성하세요: +struct BlockspaceLanes { + uint32 maxBlockspaceGasWeight; + EnterpriseLane[] enterpriseLanes; + TxTypeLane[] txTypeLanes; +} -```solidity interface IStableSystem { event UnbondingCompleted( address indexed delegator, address indexed validator, + uint64 indexed originBlockHeight, uint256 amount ); -} -``` - -Solidity 컨트랙트 없이 순수 프런트엔드 dApp을 구축하는 경우, 이벤트에 대한 ABI 조각만 있으면 됩니다: - -```javascript -const STABLE_SYSTEM_ABI = [ - 'event UnbondingCompleted(address indexed delegator, address indexed validator, uint256 amount)' -]; -``` - -### 2단계: 이벤트 리스너 설정 - -ethers.js 프로바이더를 초기화하고 StableSystem 프리컴파일 주소를 가리키는 컨트랙트 인스턴스를 생성합니다. 프리컴파일은 Stable Testnet과 Stable Mainnet 모두에서 항상 `0x00000000000....0000009999`에 배포됩니다. - -*참고: 프리컴파일은 아직 Stable Mainnet에 배포되지 않았으며, v1.2.0 업그레이드 이후에 제공될 예정입니다.* - -```javascript -const provider = new ethers.JsonRpcProvider(RPC_URL); -const stableSystem = new ethers.Contract( - '0x0000000000000000000000000000000000009999', - STABLE_SYSTEM_ABI, - provider -); -``` -### 3단계: 애플리케이션 로직에서 이벤트 처리 + function notifySystemTxLogs() external; -이벤트를 구독하고 그에 따라 애플리케이션 상태를 업데이트합니다. 일반적인 패턴은 다음과 같습니다: - -- **잔액 업데이트**: 언본딩이 완료되면 사용자의 토큰 잔액을 새로 고칩니다 -- **알림 시스템**: 사용자의 언본딩이 완료되면 토스트 알림을 표시합니다 -- **대시보드 통계**: 스테이킹 메트릭과 차트를 실시간으로 업데이트합니다 -- **트랜잭션 내역**: 완료된 언본딩을 사용자의 활동 피드에 추가합니다 - -### 4단계: 연결 문제 처리 - -이벤트 구독은 지속적인 웹소켓 연결에 의존하므로, 프로덕션 dApp을 위한 재연결 로직을 구현하세요: - -```javascript -let reconnectAttempts = 0; -const MAX_RECONNECT_ATTEMPTS = 5; - -function setupEventListener() { - const provider = new ethers.WebSocketProvider('wss://rpc.testnet.stable.xyz'); - - provider.on('error', (error) => { - console.error('Provider error:', error); - if (reconnectAttempts < MAX_RECONNECT_ATTEMPTS) { - reconnectAttempts++; - setTimeout(() => setupEventListener(), 5000); - } - }); - - const stableSystem = new ethers.Contract( - '0x0000000000000000000000000000000000009999', - STABLE_SYSTEM_ABI, - provider - ); - - stableSystem.on('UnbondingCompleted', handleUnbonding); + function blockspaceLanes() + external + view + returns (BlockspaceLanes memory lanes); } ``` -## 왜 이 접근 방식인가? - -### 커스텀 인덱서와의 비교 - -이전에는 Stable SDK에서 SDK 이벤트를 감시하고 데이터베이스에 저장하는 커스텀 인덱서를 실행해야 했습니다. 이는 운영 부담을 가중시키고 잠재적인 장애 지점을 유발합니다. - -시스템 트랜잭션을 사용하면 별도의 인덱서 인프라가 필요하지 않습니다. 이벤트는 모든 RPC 노드가 이미 인덱싱하고 제공하는 EVM의 로그 시스템을 통해 기본적으로 사용할 수 있습니다. 어떤 표준 web3 라이브러리든 추가 도구 없이 이러한 이벤트를 구독할 수 있습니다. +## `blockspaceLanes()` -### SDK 엔드포인트 폴링과의 비교 +`blockspaceLanes()`는 블록 제안 및 유효성 검사 중에 사용되는 거버넌스 제어 레인 레지스트리를 반환합니다. 이것은 사용자 정의 JSON-RPC 메서드가 아닌 일반 `eth_call`이며, 엔터프라이즈 게이트웨이를 필요로 하지 않습니다. -시스템 트랜잭션이 없으면, EVM dApp은 언본딩 기간이 완료되었는지 확인하기 위해 주기적으로 Stable SDK REST 엔드포인트를 호출해야 합니다. 이로 인해 여러 문제가 발생합니다: +두 레인 배열은 `id`에 따라 오름차순으로 정렬됩니다. 낮은 ID는 더 높은 일치 우선 순위를 가집니다. -- **증가한 지연 시간**: 5-10초의 폴링 간격은 사용자가 업데이트를 보기까지 그만큼 기다려야 함을 의미합니다 -- **높은 부하**: 엔드포인트를 폴링하는 모든 dApp 인스턴스가 RPC 인프라의 부하를 증가시킵니다 -- **복잡성**: dApp은 web3 프로바이더(EVM 상호작용용)와 Stable SDK REST 클라이언트(SDK 쿼리용)를 모두 처리해야 합니다 -- **실시간 업데이트 부재**: 폴링은 본질적으로 즉각적인 알림을 제공할 수 없습니다 +### 반환 값 -시스템 트랜잭션은 dApp이 EVM 상호작용을 위해 이미 사용하고 있는 동일한 웹소켓 연결을 통해 실시간 이벤트 알림을 제공합니다. 이는 개발자 경험을 단순화하고 인프라 비용을 줄입니다. +| **필드** | **유형** | **설명** | +| :--- | :--- | :--- | +| `maxBlockspaceGasWeight` | `uint32` | 구성된 모든 레인에 걸쳐 예약된 블록 가스 한도의 0에서 100까지의 백분율입니다. | +| `enterpriseLanes` | `EnterpriseLane[]` | 엔터프라이즈 레인 정의. 거버넌스는 최대 하나의 엔터프라이즈 레인을 허용합니다. | +| `txTypeLanes` | `TxTypeLane[]` | 일치 규칙이 트랜잭션 필드를 검사하는 레인입니다. | -## 보안 보장 +### 엔터프라이즈 레인 -### 신뢰가 필요 없는 이벤트 발생 +`NonceKey`의 63비트가 설정된 모든 `CustomTx`는 `MaxUint64`를 제외하고 구성된 엔터프라이즈 레인으로 라우팅됩니다. 하위 63비트는 레인이 아닌 독립적인 논스 채널을 선택합니다. -시스템 트랜잭션은 검증자만 실행할 수 있는 `PrepareProposal` ABCI 단계에서 생성됩니다. 사용자가 제출한 트랜잭션은 시스템 발신자 주소(`0x8888888888888888888888888888888888888888`)를 위조할 수 없습니다. EVM의 상태 전이 로직은 StableSystem 프리컴파일 주소로의 트랜잭션만 서명 검증을 건너뛸 수 있도록 강제합니다. +| **필드** | **유형** | **설명** | +| :--- | :--- | :--- | +| `id` | `uint64` | 드레인 순서 우선 순위 및 식별자. | +| `name` | `string` | 사람이 읽을 수 있는 레인 이름. | +| `weight` | `uint32` | 레인에 할당된 예약된 블록 공간 풀의 0에서 100까지의 백분율입니다. | -이는 다음을 의미합니다: +### 트랜잭션 유형 레인 -- 사용자는 언본딩 완료 이벤트를 위조할 수 없습니다 -- 사용자는 자신의 트랜잭션에서 `notifyUnbondingCompletions`를 호출할 수 없습니다 -- `UnbondingCompleted` 이벤트를 발생시키는 유일한 방법은 Stable SDK 스테이킹 모듈에서 실제 언본딩이 완료되는 것입니다 +트랜잭션은 채워진 모든 매처 필드와 일치해야 합니다. 한 필드 내의 항목은 대안이며, 빈 매처는 와일드카드입니다. -### 추가적인 신뢰 가정 없음 +| **필드** | **유형** | **설명** | +| :--- | :--- | :--- | +| `id` | `uint64` | 레인 우선 순위 및 식별자. 낮은 ID가 먼저 일치합니다. | +| `name` | `string` | 사람이 읽을 수 있는 레인 이름. | +| `toAddrs` | `address[]` | 허용되는 대상 주소. 비어 있으면 모든 대상을 일치시킵니다. | +| `methods` | `bytes4[]` | 허용되는 4바이트 함수 셀렉터. 비어 있으면 모든 셀렉터를 일치시킵니다. | +| `txTypes` | `uint8[]` | 허용되는 트랜잭션 형식. 비어 있거나 `0` 항목은 모든 형식을 일치시킵니다. | +| `nonceKeys` | `uint64[]` | 허용되는 논스 키. 비어 있거나 `0` 항목은 모든 키를 일치시킵니다. | +| `senders` | `address[]` | 허용되는 발신자 주소. 비어 있으면 모든 발신자를 일치시킵니다. | +| `weight` | `uint32` | 레인에 할당된 예약된 블록 공간 풀의 0에서 100까지의 백분율입니다. | +| `noOverflow` | `bool` | `true`인 경우, 사용되지 않은 용량은 나중 레인으로 넘어가지 않습니다. | -시스템 트랜잭션은 블록체인 합의에 이미 필요한 것 이상의 새로운 보안 가정을 도입하지 않습니다. 검증자가 블록을 올바르게 실행한다고 신뢰한다면, 시스템 트랜잭션 이벤트가 Stable SDK 상태 변경을 정확하게 반영한다고 신뢰할 수 있습니다. +`txTypes`는 다음 `TxFormat` 값을 사용합니다. -이벤트 발생 과정은 결정론적입니다: `EndBlock`에서 동일한 SDK 이벤트가 주어지면, 모든 정직한 검증자는 `PrepareProposal` 동안 동일한 시스템 트랜잭션을 생성합니다. 합의 메커니즘은 검증자가 어떤 시스템 트랜잭션을 포함할지 동의하도록 보장합니다. +| **값** | **트랜잭션 형식** | **EVM 유형** | +| :--- | :--- | :--- | +| `0` | 와일드카드 | 모든 | +| `1` | 레거시 | `0x00` | +| `2` | 액세스 목록 | `0x01` | +| `3` | 동적 수수료 | `0x02` | +| `4` | 코드 설정 | `0x04` | +| `5` | 2차원 논스 | `0x3F` | -### 블록 최종성 +### 레지스트리 쿼리 -Stable 블록체인은 StableBFT의 합의 메커니즘을 통한 빠른 최종성을 사용합니다. 블록이 커밋되면 즉시 최종 확정되며 재구성될 수 없습니다. 이는 일단 `UnbondingCompleted` 이벤트를 받으면 그것이 영구적이라고 신뢰할 수 있음을 의미합니다. +Foundry의 `cast` 명령으로 프리컴파일을 호출합니다. -확률적 최종성 체인처럼 여러 번의 확인을 기다릴 필요가 없습니다. dApp은 이벤트를 받는 즉시 사용자 잔액을 업데이트하고 알림을 표시할 수 있습니다. - -## 성능 및 제한 사항 - -### 배치 크기 제약 - -각 블록은 시스템 트랜잭션을 통해 최대 100개의 언본딩 완료를 처리합니다. 이 제한은 언본딩 활동이 많은 기간 동안 무제한적인 블록 크기를 방지하기 위해 존재합니다. - -실제로 블록당 100개의 완료는 평균 블록 시간 0.7초를 가정할 때 분당 약 9000개의 완료 처리량을 제공합니다. 정상적인 스테이킹 활동은 이 한계에 거의 도달하지 않습니다. 예외적인 상황에서는 완료가 완전히 처리되기 전에 여러 블록 동안 큐에 대기할 수 있습니다. - -### 가스 소비 - -시스템 트랜잭션은 실행 중에 가스를 소비하며, 이는 블록의 가스 한도에 포함됩니다. 가스 비용은 처리되는 완료 수에 따라 선형적으로 증가합니다: - -- 기본 함수 호출: \~21,000 가스 -- 이벤트 발생당: \~3,000 가스 -- 상태 읽기: 완료당 \~2,000 가스 - -100개의 완료로 구성된 전체 배치는 약 521,000 가스를 소비합니다. Stable의 블록 가스 한도는 100,000,000이므로, 이는 사용 가능한 블록 공간의 0.6% 미만에 해당합니다. - -### 알림 지연 시간 +```bash +cast call \ + 0x0000000000000000000000000000000000009999 \ + "blockspaceLanes()((uint32,(uint64,string,uint32)[],(uint64,string,address[],bytes4[],uint8[],uint64[],address[],uint32,bool)[]))" \ + --rpc-url https://rpc.stable.xyz +``` -블록 N 동안 언본딩 기간이 완료되면: +v1.8.0 메인넷 활성화는 20%의 예약된 풀과 해당 풀의 50%를 가진 하나의 엔터프라이즈 레인을 시드했습니다. 거버넌스는 이 출력을 변경할 수 있습니다. -1. Stable 모듈의 `EndBlock`이 블록 N의 상태에 완료를 큐에 추가합니다 -2. 블록 N+1의 `PrepareProposal`이 시스템 트랜잭션을 생성합니다 -3. 시스템 트랜잭션이 블록 N+1 동안 실행되어 이벤트를 발생시킵니다 +```text +(20, [(1, "enterprise", 50)], []) +``` -이는 언본딩 완료와 EVM 이벤트 발생 사이에 한 블록의 지연(약 0.7초)이 있음을 의미합니다. 언본딩 기간 자체가 7일이므로 대부분의 사용 사례에서 이 지연 시간은 허용 가능합니다. +## `notifySystemTxLogs()` -### 높은 부하 시나리오 +`notifySystemTxLogs()`는 대기 중인 프로토콜 로그 항목을 상태에서 읽고 호출당 최대 100개까지 처리합니다. 인수를 받지 않으며 반환 값도 없습니다. -언본딩 완료가 블록당 100개보다 빠르게 도착하면, 큐에 누적됩니다. 큐는 FIFO 순서로 처리되므로, 가장 오래된 완료가 항상 먼저 알림됩니다. +발신자 `0x0000000000000000000000000000000000000001`가 있는 시스템 트랜잭션만 이 메서드를 호출할 수 있습니다. 사용자 또는 계약의 호출은 되돌려집니다. -지속적인 높은 부하 동안 큐는 일시적으로 늘어날 수 있습니다. 하지만 급증이 가라앉으면, 완료가 더 적은 후속 블록들이 점차 큐를 비웁니다. 시스템은 이벤트를 누락하지 않고 급증을 처리하도록 설계되었습니다. +언본딩이 완료되면 흐름은 다음과 같습니다. -## 향후 확장 +1. 스테이킹 모듈은 작업을 완료하고 SDK 이벤트를 기록합니다. +2. `x/stable` 모듈은 이벤트 데이터와 원래 블록 높이를 대기열에 추가합니다. +3. 다음 블록 제안자는 `notifySystemTxLogs()`를 호출하는 시스템 트랜잭션을 생성합니다. +4. 프리컴파일은 최대 100개의 대기 중인 항목에 대해 EVM 로그를 내보냅니다. +5. 클라이언트는 `eth_getLogs`, WebSocket 구독 또는 블록 탐색기를 사용하여 로그를 읽습니다. -시스템 트랜잭션 메커니즘은 모든 Stable SDK 작업을 EVM 이벤트 공간으로 연결하는 일반적인 패턴을 제공합니다. 현재는 언본딩 완료에만 사용되지만, 이 아키텍처는 추가적인 사용 사례를 다루도록 확장할 수 있습니다: +배치 제한을 초과하는 항목은 나중 블록을 위해 대기열에 유지됩니다. -### 스테이킹 작업 +## `UnbondingCompleted` 이벤트 -언본딩 외에도, 다른 스테이킹 이벤트가 EVM 알림을 발생시킬 수 있습니다: +| **매개변수** | **유형** | **인덱싱됨** | **설명** | +| :--- | :--- | :--- | :--- | +| `delegator` | `address` | 예 | 언본딩을 마친 위임된 토큰의 주소. | +| `validator` | `address` | 예 | 유효성 검사기 운영자 주소에서 파생된 유효성 검사기 주소. | +| `originBlockHeight` | `uint64` | 예 | SDK 계층 언본딩이 원래 완료된 블록 높이. | +| `amount` | `uint256` | 아니오 | 언본딩을 마친 금액. | -- 검증자에 의한 수수료율 변경 -- 검증자 수감 및 수감 해제 +EVM 로그는 시스템 트랜잭션을 포함하는 블록에 나타납니다. 원래 SDK 이벤트의 높이가 필요한 경우 `originBlockHeight`를 사용하십시오. -### 거버넌스 실행 +## 보안 모델 -거버넌스 제안이 통과되어 실행될 때, 시스템 트랜잭션은 제안 ID와 실행 결과와 함께 이벤트를 발생시킬 수 있습니다. 이를 통해 dApp은 거버넌스 모듈을 폴링하지 않고도 매개변수 변경이나 업그레이드에 반응할 수 있습니다. +- 프로토콜은 블록 제안 중에 시스템 트랜잭션을 생성합니다. +- EVM 상태 전환 규칙은 시스템 트랜잭션에 대해 발신자 `0x0000000000000000000000000000000000000001`을 예약합니다. +- 사용자 트랜잭션은 발신자를 위조하거나 `notifySystemTxLogs()`를 성공적으로 호출할 수 없습니다. +- `blockspaceLanes()`는 의도적으로 공개되어 있으며 상태를 변경할 수 없습니다. -### 일반 이벤트 브리지 +## 다음으로 이동할 곳 -이 패턴은 각 모듈이 어떤 SDK 이벤트를 EVM에 미러링할지 등록하는 구성 가능한 이벤트 브리지로 일반화될 수 있습니다. 이는 모듈별 커스텀 로직 없이도 모든 Stable SDK 작업에 대한 포괄적인 가시성을 제공합니다. 핵심 아키텍처 원칙은 시스템 트랜잭션이 블록 제안 동안 검증자에 의해서만 생성되는 프로토콜 수준 기능으로 유지된다는 것입니다. +- [**보장된 블록 공간**](/ko/explanation/guaranteed-blockspace): 반환된 가중치 및 매처가 예약된 용량을 어떻게 제어하는지 이해합니다. +- [**언본딩 완료 추적**](/ko/how-to/track-unbonding): `UnbondingCompleted`를 구독하고 과거 이벤트를 쿼리합니다. +- [**시스템 트랜잭션**](/ko/explanation/system-transactions): 프로토콜 이벤트가 EVM 로그가 되는 방법을 이해합니다. diff --git a/docs/pages/ko/reference/testnet-version-history.mdx b/docs/pages/ko/reference/testnet-version-history.mdx index 6a43cbd..5f515c0 100755 --- a/docs/pages/ko/reference/testnet-version-history.mdx +++ b/docs/pages/ko/reference/testnet-version-history.mdx @@ -1,14 +1,14 @@ --- source_path: reference/testnet-version-history.mdx -source_sha: 050f5652f63ca9f7d67ab44ad1b5798f243fc236 +source_sha: a341ad196aefb3dbe2c44e3df89474344c069155 title: 버전 기록 -description: "Stable 테스트넷 네트워크의 버전 기록 및 업그레이드 일정." +description: "Stable Testnet 릴리스, 업그레이드 높이, 커밋, 다운로드 가능한 노드 바이너리를 찾아보세요." diataxis: "reference" --- # 버전 기록 -Stable Testnet의 전체 버전 기록 및 관련 문서. +Stable Testnet은 현재 `v1.8.0-rc1`을 실행하고 있습니다. 각 릴리스, 활성화 높이 및 노드 바이너리를 식별하려면 이 기록을 사용하세요. ## 현재 버전 정보 @@ -21,10 +21,11 @@ Stable Testnet의 전체 버전 기록 및 관련 문서. ### 현재 및 이전 버전 -| 버전 | 커밋 | 업그레이드 높이 | 바이너리 | 상태 | -|---------|--------|----------------|--------|-------------------------------| +| **버전** | **커밋** | **업그레이드 높이** | **바이너리** | **상태** | +| :--- | :--- | :--- | :--- | :--- | | **v1.8.0-rc1** | `a07c551` | 64,956,000 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.8.0-rc1-linux-amd64-testnet.tar.gz) / [ARM64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.8.0-rc1-linux-arm64-testnet.tar.gz) | 현재 | | **v1.8.0-rc0** | `4cc6813` | 61,689,000 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.8.0-rc0-linux-amd64-testnet.tar.gz) / [ARM64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.8.0-rc0-linux-arm64-testnet.tar.gz) | | +| **v1.4.0-rc2** | `75c2934` | 60,110,000 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.4.0-rc2-linux-amd64-testnet.tar.gz) / [ARM64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.4.0-rc2-linux-arm64-testnet.tar.gz) | | | **v1.4.0-rc1** | `4744d2d` | 58,520,000 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.4.0-rc1-linux-amd64-testnet.tar.gz) / [ARM64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.4.0-rc1-linux-arm64-testnet.tar.gz) | | | **v1.4.0-rc0** | `83b5efb` | 57,806,500 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.4.0-rc0-linux-amd64-testnet.tar.gz) / [ARM64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.4.0-rc0-linux-arm64-testnet.tar.gz) | | | **v1.3.1-rc0** | `75bb546` | - | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.3.1-rc0-linux-amd64-testnet.tar.gz) / [ARM64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.3.1-rc0-linux-arm64-testnet.tar.gz) | | @@ -38,17 +39,17 @@ Stable Testnet의 전체 버전 기록 및 관련 문서. | **v1.1.1** | `8becd6b` | 33,152,000 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.1.1-linux-amd64-testnet.tar.gz) / [ARM64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.1.1-linux-arm64-testnet.tar.gz) | | | **v1.1.0** | `17ceaa7` | 32,309,700 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.1.0-linux-amd64-testnet.tar.gz) / [ARM64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-1.1.0-linux-arm64-testnet.tar.gz) | | | **v0.8.1** | `1eb65d5` | 30,770,000 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.8.1-linux-amd64-testnet.tar.gz) / [ARM64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.8.1-linux-arm64-testnet.tar.gz) | | -| **v0.8.0** | `e55efb6` | 29,410,999 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.8.0-linux-amd64-testnet.tar.gz) / [ARM64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.8.0-linux-arm64-testnet.tar.gz) | 뱅크 프리컴파일 개선 | +| **v0.8.0** | `e55efb6` | 29,410,999 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.8.0-linux-amd64-testnet.tar.gz) / [ARM64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.8.0-linux-arm64-testnet.tar.gz) | 뱅크 사전 컴파일 개선 | | **v0.7.2** | `3c53e14` | 27,258,000 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.7.2-linux-amd64-testnet.tar.gz) / [ARM64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.7.2-linux-arm64-testnet.tar.gz) | StableBFT 통합 | | **v0.6.0** | `5cc1ad6` | 19,587,000 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.6.0-linux-amd64-testnet.tar.gz) | 사소한 수정 | | **v0.5.0** | `919281d` | 18,719,000 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.5.0-linux-amd64-testnet.tar.gz) | 사소한 수정 | | **v0.4.0** | `c6240c0` | 18,666,150 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.4.0-linux-amd64-testnet.tar.gz) | Stable SDK v0.53.4 | -| **v0.3.0** | `a4f5ac5` | 9,166,131 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.3.0-linux-amd64-testnet.tar.gz) | EVM 값 전송 허용 목록 | -| **v0.2.1** | `53e6e073` | - | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.2.1-linux-amd64-testnet.tar.gz) | 비파괴 업데이트 | +| **v0.3.0** | `a4f5ac5` | 9,166,131 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.3.0-linux-amd64-testnet.tar.gz) | EVM 가치 전송 허용 목록 | +| **v0.2.1** | `53e6e073` | - | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.2.1-linux-amd64-testnet.tar.gz) | 비파괴적 업데이트 | | **v0.2.0** | `8bdd771` | 8,956,584 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.2.0-linux-amd64-testnet.tar.gz) | 기능 업데이트 | | **v0.1.0** | `10dfg542` | 제네시스 | [AMD64](https://stable-data-dist.s3.us-east-1.amazonaws.com/testnet/binary/stabled-0.1.0-linux-amd64-testnet.tar.gz) | 제네시스 (2025-04-07) | -## 관련 문서 +## 다음으로 이동할 곳 -- [업그레이드 가이드](/ko/how-to/upgrade-node) - 단계별 업그레이드 절차 -- [테스트넷 정보](/ko/reference/testnet-information) - 현재 네트워크 세부 정보 +- [**노드 업그레이드**](/ko/how-to/upgrade-node): 조율된 네트워크 업그레이드를 위해 노드 바이너리 및 구성 파일을 교체합니다. +- [**테스트넷 정보**](/ko/reference/testnet-information): 현재 체인 ID, 엔드포인트 및 컨트랙트 주소로 Stable Testnet에 연결합니다.