merge master

docs/2.develop/lake/structures/block.mdx

@@ -0,0 +1,140 @@
+---
+sidebar_position: 2
+sidebar_label: Block
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CodeBlock from '@theme/CodeBlock';
+
+# `Block` Structure
+
+## Definition
+
+`Block` is the main entity in NEAR Protocol blockchain. `Blocks` are produced in NEAR Protocol every second.
+
+It contains the info:
+- about the `Block` producer (`AccountId` of the validator responsible for particular `Block` production)
+- Block Header
+- List of Chunk Headers
+
+## Representation
+
+### `Block`
+
+<Tabs>
+  <TabItem value="rust" label="Rust" default>
+
+```rust links=1
+pub struct BlockView {
+    pub author: AccountId,
+    pub header: BlockHeaderView,
+    pub chunks: Vec<ChunkHeaderView>,
+}
+```
+
+  </TabItem>
+  <TabItem value="typescript" label="TypeScript">
+
+```ts links=1
+export interface Block {
+  author: string;
+  header: BlockHeader;
+  chunks: ChunkHeader[];
+};
+```
+
+  </TabItem>
+</Tabs>
+
+
+### `BlockHeaderView`
+
+`BlockHeaderView` contains main info about the block.
+
+<Tabs>
+  <TabItem value="rust" label="Rust">
+
+```rust
+pub struct BlockHeaderView {
+    pub height: BlockHeight,
+    pub prev_height: Option<BlockHeight>,
+    pub epoch_id: CryptoHash,
+    pub next_epoch_id: CryptoHash,
+    pub hash: CryptoHash,
+    pub prev_hash: CryptoHash,
+    pub prev_state_root: CryptoHash,
+    pub chunk_receipts_root: CryptoHash,
+    pub chunk_headers_root: CryptoHash,
+    pub chunk_tx_root: CryptoHash,
+    pub outcome_root: CryptoHash,
+    pub chunks_included: u64,
+    pub challenges_root: CryptoHash,
+    /// Legacy json number. Should not be used.
+    pub timestamp: u64,
+    pub timestamp_nanosec: u64,
+    pub random_value: CryptoHash,
+    pub validator_proposals: Vec<ValidatorStakeView>,
+    pub chunk_mask: Vec<bool>,
+    pub gas_price: Balance,
+    pub block_ordinal: Option<NumBlocks>,
+    /// TODO(2271): deprecated.
+    pub rent_paid: Balance,
+    /// TODO(2271): deprecated.
+    pub validator_reward: Balance,
+    pub total_supply: Balance,
+    pub challenges_result: ChallengesResult,
+    pub last_final_block: CryptoHash,
+    pub last_ds_final_block: CryptoHash,
+    pub next_bp_hash: CryptoHash,
+    pub block_merkle_root: CryptoHash,
+    pub epoch_sync_data_hash: Option<CryptoHash>,
+    pub approvals: Vec<Option<Signature>>,
+    pub signature: Signature,
+    pub latest_protocol_version: ProtocolVersion,
+}
+```
+
+  </TabItem>
+
+  <TabItem value="typescript" label="TypeScript">
+
+```ts links=1
+export interface BlockHeader {
+  approvals: (string | null)[];
+  blockMerkleRoot: string;
+  blockOrdinal: number;
+  challengesResult: ChallengeResult[];
+  challengesRoot: string;
+  chunkHeadersRoot: string;
+  chunkMask: boolean[];
+  chunkReceiptsRoot: string;
+  chunkTxRoot: string;
+  chunksIncluded: number;
+  epochId: string;
+  epochSyncDataHash: string | null;
+  gasPrice: string;
+  hash: string;
+  height: number;
+  lastDsFinalBlock: string;
+  lastFinalBlock: string;
+  latestProtocolVersion: number;
+  nextBpHash: string;
+  nextEpochId: string;
+  outcomeRoot: string;
+  prevHash: string;
+  prevHeight: number;
+  prevStateRoot: string;
+  randomValue: string;
+  rentPaid: string;
+  signature: string;
+  timestamp: number;
+  timestampNanosec: string;
+  totalSupply: string;
+  validatorProposals: [];
+  validatorReward: string;
+};
+```
+
+  </TabItem>
+</Tabs>

docs/2.develop/lake/structures/chunk.mdx

@@ -0,0 +1,109 @@
+---
+sidebar_position: 3
+sidebar_label: Chunk
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# `Chunk` Structure
+
+## Definition
+
+`Chunk` of a [`Block`](./block.mdx) is a part of a [`Block`](./block.mdx) from a [Shard](./shard.mdx). The collection of Chunks of the Block forms the NEAR Protocol [`Block`](./block.mdx)
+
+Chunk contains all the structures that make the Block:
+- [Transactions](./transaction.mdx)
+- [Receipts](./receipt.mdx)
+- [ChunkHeader](#chunkheaderview)
+
+## `IndexerChunkView`
+
+<Tabs>
+  <TabItem value="rust" label="Rust">
+
+```rust links=1
+pub struct ChunkView {
+    pub author: AccountId,
+    pub header: ChunkHeaderView,
+    pub transactions: Vec<IndexerTransactionWithOutcome>,
+    pub receipts: Vec<ReceiptView>,
+}
+```
+
+  </TabItem>
+  <TabItem value="typescript" label="TypeScript">
+
+```ts links=1
+export interface Chunk {
+  author: string;
+  header: ChunkHeader;
+  transactions: IndexerTransactionWithOutcome[];
+  receipts: Receipt[],
+}
+```
+
+  </TabItem>
+</Tabs>
+
+## `ChunkHeaderView`
+
+<Tabs>
+  <TabItem value="rust" label="value">
+
+```rust links=1
+pub struct ChunkHeaderView {
+    pub chunk_hash: CryptoHash,
+    pub prev_block_hash: CryptoHash,
+    pub outcome_root: CryptoHash,
+    pub prev_state_root: StateRoot,
+    pub encoded_merkle_root: CryptoHash,
+    pub encoded_length: u64,
+    pub height_created: BlockHeight,
+    pub height_included: BlockHeight,
+    pub shard_id: ShardId,
+    pub gas_used: Gas,
+    pub gas_limit: Gas,
+    /// TODO(2271): deprecated.
+    #[serde(with = "u128_dec_format")]
+    pub rent_paid: Balance,
+    /// TODO(2271): deprecated.
+    #[serde(with = "u128_dec_format")]
+    pub validator_reward: Balance,
+    #[serde(with = "u128_dec_format")]
+    pub balance_burnt: Balance,
+    pub outgoing_receipts_root: CryptoHash,
+    pub tx_root: CryptoHash,
+    pub validator_proposals: Vec<ValidatorStakeView>,
+    pub signature: Signature,
+}
+```
+
+  </TabItem>
+  <TabItem value="typescript" value="TypeScript">
+
+```ts links=1
+export interface ChunkHeader {
+  balanceBurnt: number;
+  chunkHash: string;
+  encodedLength: number;
+  encodedMerkleRoot: string;
+  gasLimit: number;
+  gasUsed: number;
+  heightCreated: number;
+  heightIncluded: number;
+  outcomeRoot: string;
+  outgoingReceiptsRoot: string;
+  prevBlockHash: string;
+  prevStateRoot: string;
+  rentPaid: string;
+  shardId: number;
+  signature: string;
+  txRoot: string;
+  validatorProposals: ValidatorProposal[];
+  validatorReward: string;
+};
+```
+
+  </TabItem>
+</Tabs>

docs/2.develop/lake/structures/execution_outcome.mdx

@@ -0,0 +1,134 @@
+---
+id: execution-outcome
+sidebar_position: 6
+sidebar_label: ExecutionOutcome
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# `ExecutionOutcome` Structure
+
+## Definition
+
+ExecutionOutcome is the result of execution of [Transaction](./transaction.mdx) or [Receipt](./receipt.mdx)
+
+:::info Transaction's ExecutionOutcome
+
+In the result of the Transaction execution will always be a Receipt.
+
+:::
+
+## `ExecutionOutcomeWithIdView`
+
+<Tabs>
+  <TabItem value="rust" label="Rust">
+
+```rust links=1
+pub struct ExecutionOutcomeWithIdView {
+    pub proof: MerklePath,
+    pub block_hash: CryptoHash,
+    pub id: CryptoHash,
+    pub outcome: ExecutionOutcomeView,
+}
+```
+
+  </TabItem>
+  <TabItem value="typescript" label="TypeScript">
+
+```ts links=1
+export type ExecutionOutcomeWithReceipt = {
+  executionOutcome: {
+    blockHash: string;
+    id: string;
+    outcome: {
+      executorId: string,
+      gasBurnt: number,
+      logs: string[],
+      metadata: {
+        gasProfile: string | null;
+        version: number;
+      };
+      receiptIds: string[],
+      status: ExecutionStatus,
+      tokensBurnt: string
+    };
+    proof: ExecutionProof[];
+  };
+  receipt: Receipt | null;
+};
+```
+
+  </TabItem>
+</Tabs>
+
+## `ExecutionOutcomeView`
+
+<Tabs>
+  <TabItem value="rust" label="Rust">
+
+```rust links=1
+pub struct ExecutionOutcomeView {
+    /// Logs from this transaction or receipt.
+    pub logs: Vec<String>,
+    /// Receipt IDs generated by this transaction or receipt.
+    pub receipt_ids: Vec<CryptoHash>,
+    /// The amount of the gas burnt by the given transaction or receipt.
+    pub gas_burnt: Gas,
+    /// The amount of tokens burnt corresponding to the burnt gas amount.
+    /// This value doesn't always equal to the `gas_burnt` multiplied by the gas price, because
+    /// the prepaid gas price might be lower than the actual gas price and it creates a deficit.
+    #[serde(with = "u128_dec_format")]
+    pub tokens_burnt: Balance,
+    /// The id of the account on which the execution happens. For transaction this is signer_id,
+    /// for receipt this is receiver_id.
+    pub executor_id: AccountId,
+    /// Execution status. Contains the result in case of successful execution.
+    pub status: ExecutionStatusView,
+    /// Execution metadata, versioned
+    #[serde(default)]
+    pub metadata: ExecutionMetadataView,
+}
+```
+
+  </TabItem>
+  <TabItem value="typescript" label="TypeScript">
+
+  [ExecutionOutcomeWithIdView TypeScript](#executionoutcomewithidview) defines this structure already an nested
+
+  </TabItem>
+</Tabs>
+
+
+## `ExecutionStatusView`
+
+<Tabs>
+  <TabItem value="rust" label="Rust">
+
+```rust links=1
+pub enum ExecutionStatusView {
+    /// The execution is pending or unknown.
+    Unknown,
+    /// The execution has failed.
+    Failure(TxExecutionError),
+    /// The final action succeeded and returned some value or an empty vec encoded in base64.
+    SuccessValue(String),
+    /// The final action of the receipt returned a promise or the signed transaction was converted
+    /// to a receipt. Contains the receipt_id of the generated receipt.
+    SuccessReceiptId(CryptoHash),
+}
+```
+
+  </TabItem>
+  <TabItem value="typescript" label="TypeScript">
+
+```ts links=1
+export type ExecutionStatus =
+  | { Unknown: unknown }
+  | { Failure: unknown }
+  | { SuccessValue: string }
+  | { SuccessReceiptId: string };
+```
+
+  </TabItem>
+</Tabs>