Add data dicts for hubble api docs #176
Closed
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Preview is available here: |
There was a problem hiding this comment.
i'll help with the formatting of the actual docs tomorrow, this is a great first pass and will help make formatting tomorrow easy :)
i didn't review the larger tables (history_operations and enriched_history_operations) because those will be easier to review when i'm able to preview the docs instead of reading raw markdown
Comment on lines
+8
to
+10
| | batch_id | string | String representation of the run id for a given DAG in Airflow. Takes the form of "scheduled__<batch_end_date>-<dag_alias>". Batch ids are unique to the batch and help with monitoring and rerun capabilities | | ||
| | batch_run_date | datetime | The start date for the batch interval. When taken with the date in the batch_id, the date represents the interval of ledgers processed. The batch run date can be seen as a proxy of closed_at for a ledger. | | ||
| | batch_insert_ts | timestamp | The timestamp in UTC when a batch of records was inserted into the database. This field can help identify if a batch executed in real time or as part of a backfill. The timestamp should not be used during ad hoc analysis and is useful for data engineering purposes. | |
There was a problem hiding this comment.
What do you think about us dropping the batch fields from the docs? Since they really don't serve a purpose to the community, I wonder if we should just drop them from docs or make a one time note that batch_id and batch_insert_ts shouldn't be used
| | selling_liabilities | float64 | The sum of all sell offers owned by this account for XLM only<br /><br />- Required Field<br /><br />#### Notes:<br />The `accounts` table only reports monetary balances for XLM. Any other asset class is reported in the `trust_lines` table. | | ||
| | sequence_number | int64 | The account's current sequence number. The sequence number controls operations applied to an account. Operations must submit a unique sequence number that is incremented by 1 in order to apply the operation to the account so that account changes will not collide within a ledger.<br /><br />- Natural Key<br />- Required Field | | ||
| | num_subentries | int64 | The total number of ledger entries connected to this account. Ledger entries include: trustlines, offers, signers, and data entries. (Claimable balances are counted under sponsoring entries, not subentries). Any newly created trustline, offer, signer or data entry will increase the number of subentries by 1. Accounts may have up to 1,000 subentries<br /><br />- Required Field<br /><br />#### Notes:<br />Each entry on a ledger takes up space, which is expensive to store on the blockchain. For each entry, an account is required to hold a [minimum XLM balance](https://developers.stellar.org/docs/fundamentals-and-concepts/lumens#minimum-balance). The reserve is calculated by (2 + num_subentries - num_sponsoring + num_sponsored) * 0.5XLM | | ||
| | inflation_destination | string | Deprecated: The account address to receive an inflation payment when they are disbursed on the network.<br /><br />#### Notes:<br />Inflation was discontinued in 2019 by validator vote. | |
There was a problem hiding this comment.
Should we bold deprecated?
| | num_subentries | int64 | The total number of ledger entries connected to this account. Ledger entries include: trustlines, offers, signers, and data entries. (Claimable balances are counted under sponsoring entries, not subentries). Any newly created trustline, offer, signer or data entry will increase the number of subentries by 1. Accounts may have up to 1,000 subentries<br /><br />- Required Field<br /><br />#### Notes:<br />Each entry on a ledger takes up space, which is expensive to store on the blockchain. For each entry, an account is required to hold a [minimum XLM balance](https://developers.stellar.org/docs/fundamentals-and-concepts/lumens#minimum-balance). The reserve is calculated by (2 + num_subentries - num_sponsoring + num_sponsored) * 0.5XLM | | ||
| | inflation_destination | string | Deprecated: The account address to receive an inflation payment when they are disbursed on the network.<br /><br />#### Notes:<br />Inflation was discontinued in 2019 by validator vote. | | ||
| | flags | int64 | Denotes the enabling and disabling of certain asset issuer privileges.<br /><br />- Required Field<br /><br />#### Notes:<br />Flags are set on the issuer accounts for an asset. When user accounts trust an asset, the flags applied to the asset originate from this account. Depending on the state table, flags can have various meanings.<br /><br />#### `accounts` and `claimable_balances`:<br /><br /><table> <thead> <tr> <th>Flag</th> <th>Meaning</th> </tr> </thead> <tbody> <tr> <td>0</td> <td>None - Default</td> </tr> <tr> <td>1</td> <td>Auth Required (all trustlines by default are untrusted and require manual trust established)</td> </tr> <tr> <td>2</td> <td>Auth Revocable (allows trustlines to be revoked if account no longer trusts asset)</td> </tr> <tr> <td>4</td> <td>Auth Immutable (all auth flags are read only when set)</td> </tr> <tr> <td>8</td> <td>Auth Clawback Enabled (asset can be clawed back from the user)</td> </tr> </tbody> </table> <h4><code>offers</code>:</h4> <table> <thead> <tr> <th>Flag</th> <th>Meaning</th> </tr> </thead> <tbody> <tr> <td>0</td> <td>Default</td> </tr> <tr> <td>1</td> <td>Passive (offer with this flag will not act on and take a reverse offer of equal price)</td> </tr> </tbody> </table> <h4><code>trust_lines</code>:</h4> <p>Flags are set on the issuer accounts for an asset. When user accounts trust an asset, the flags applied to the asset originate from this account.</p> <table> <thead> <tr> <th>Flag</th> <th>Meaning</th> </tr> </thead> <tbody> <tr> <td>0</td> <td>None, Default</td> </tr> <tr> <td>1</td> <td>Authorized (issuer has authorized account to perform transaction with its credit)</td> </tr> <tr> <td>2</td> <td>Authorized to Maintain Liabilities (issuer has authorized account to maintain and reduce liabilities for its credit)</td> </tr> <tr> <td>4</td> <td>Clawback Enabled (issuer has specified that it may clawback its credit, including claimable balances)</td> </tr> </tbody> </table> | | ||
| | home_domain | string | The domain that hosts this account's stellar.toml file.<br /><br />- Required Field<br /><br />#### Notes:<br />Only applies to asset issuer accounts. The stellar.toml file contains metadata about the asset issuer which helps identify who the issuer is and instills trust in the asset | |
There was a problem hiding this comment.
nit: i don't think home domain is actually required. we might want to double check that.
| | batch_id | string | String representation of the run id for a given DAG in Airflow. Takes the form of "scheduled__<batch_end_date>-<dag_alias>". Batch ids are unique to the batch and help with monitoring and rerun capabilities | | ||
| | batch_run_date | datetime | The start date for the batch interval. When taken with the date in the batch_id, the date represents the interval of ledgers processed. The batch run date can be seen as a proxy of closed_at for a ledger. | | ||
| | batch_insert_ts | timestamp | The timestamp in UTC when a batch of records was inserted into the database. This field can help identify if a batch executed in real time or as part of a backfill. The timestamp should not be used during ad hoc analysis and is useful for data engineering purposes. | | ||
| | sponsor | string | The account address of the sponsor who is paying the reserves for this ledger entry.<br /><br />The following ledger entry types can be sponsored:<br /><br /> - accounts<br /> - account signers<br /> - claimable balances<br /> - trust lines<br /><br />#### Notes:<br />Sponsors of claimable balances are the accounts that created the balance. | |
There was a problem hiding this comment.
Even though these fields are appended on to the end of the table, does it make sense to move up past batch fields?
| | claimants.predicate.abs_before | string | Deadline for when the balance must be claimed. If a balance is claimed before the date then the clause of the condition is satisfied. | | ||
| | claimants.predicate.abs_before_epoch | int64 | A UNIX epoch value in seconds representing the same deadline date as abs_before. | | ||
| | claimants.predicate.rel_before | int64 | A relative deadline for when the claimable balance can be claimed. The value represents the number of seconds since the close time of the ledger which created the claimable balance<br /><br />#### Notes:<br />This condition is useful when creating a timebounds based on creation conditions. If the creator wanted a balance only claimable one week after creation, this condition would satisfy that rule. | | ||
| | claimants.predicate.unconditional | bool | If true it means this clause of the condition is always satisfied.<br /><br />#### Notes:<br />When the predicate is only unconditional = true, it means that the balance can be claimed under any conditions | |
There was a problem hiding this comment.
The notes here sound awkward. Would reword slightly
Comment on lines
+27
to
+28
| | selling_asset_id | int64 | Unique identifier for the asset code, type and issuer combination. This is not a primary key on the table<br /><br />- Natural Key<br />- Required | | ||
| | buying_asset_id | int64 | Unique identifier for the asset code, type and issuer combination. This is not a primary key on the table<br /><br />- Natural Key<br />- Required | |
There was a problem hiding this comment.
Might be worthwhile to point out that joining on asset_id is more efficient since it's an integer. That's the only reason why we added these fields onto the table
| | time_bounds | string | A transaction precondition that can be set to determine when a transaction is valid. The user can set a lower and upper timebound, defined as a UNIX timestamp when the transaction can be executed. <br />If the transaction attempts to execute outside of the time range, the transaction will fail | | ||
| | successful | bool | Indicates if this transaction was successful or not<br /><br />#### Notes:<br />A transaction's success does not indicate whether it was included and written to a ledger. It only indicates whether the operations in the transaction were successfully applied to mutate the ledger state. | | ||
| | fee_charged | int64 | The fee (in stroops) paid by the source account to apply this transaction to the ledger. At minimum, a transaction is charged # of operations * base fee. The minimum base fee is 100 stroops<br /><br />#### Notes:<br />The stroop is the fractional representation of a lumen (XLM). 1 stroop is 0.0000001 XLM. | | ||
| | inner_transaction_hash | string | AAAA | |
There was a problem hiding this comment.
todo: needs definition
Comment on lines
+26
to
+29
| | tx_envelope | string | AAAA | | ||
| | tx_result | string | AAAA | | ||
| | tx_meta | string | AAAA | | ||
| | tx_fee_meta | string | AAAA | |
There was a problem hiding this comment.
todo: add definitions
There was a problem hiding this comment.
One thing that might be good for us to note in the table description is if a liquidity pool is deleted and the same asset pair is created in a new pool, the pool will have the same pool id as the original pool.
Comment on lines
+11
to
+12
| | buying_liabilities | float64 | The sum of all buy offers owned by this account for XLM only<br /><br />- Required Field<br /><br />#### Notes:<br />The `accounts` table only reports monetary balances for XLM. Any other asset class is reported in the `trust_lines` table. For buy offers, the account must hold the amount of asset to complete the transaction | | ||
| | selling_liabilities | float64 | The sum of all sell offers owned by this account for XLM only<br /><br />- Required Field<br /><br />#### Notes:<br />The `accounts` table only reports monetary balances for XLM. Any other asset class is reported in the `trust_lines` table. | |
There was a problem hiding this comment.
copy/paste errors from the accounts tables
|
Close in favor of newer PR https://github.com/stellar/stellar-docs/pull/670/files |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Adding data dictionaries for hubble api docs
TODO: organize and add correct api doc formatting/structure to each mdx