stellar / stellar-docs Goto Github PK
View Code? Open in Web Editor NEWDocumentation for Stellar
Home Page: https://developers.stellar.org
License: Apache License 2.0
Documentation for Stellar
Home Page: https://developers.stellar.org
License: Apache License 2.0
There are a number of instances where knowing how to initialize the environment with a ledger snapshot would prove useful.
e.g. https://discord.com/channels/897514728459468821/1063544780170219601
A new, likely section of or additional page to, the testing section detailing how to load up the env with a ledger snapshot.
For the asset related issues you can use the example token contract vs the token spec.
e.g. https://github.com/stellar/soroban-examples/blob/main/single_offer/src/test.rs#L8
https://developers.stellar.org/docs/encyclopedia/fees-surge-pricing-fee-strategies
Stroop: the smallest unit of a lumen, one millionth of a lumen (.0000001 XLM).
Stroop: the smallest unit of a lumen, one ten-millionth of a lumen (.0000001 XLM).
There is a lack of "discoverability" for certain helpers and features in the JavaScript SDK.
People ask questions on Discord frequently about things that are very easy to do if you know about them, but knowing about them requires unnecessarily intimate knowledge about the SDK. Now that it has stabilized, we should take the time to raise the visibility of these helpful devX features.
Like with State Expiration, there should be brief demonstrations of how things are done via the JS SDK. Here's a non-exhaustive list:
Server.getEvents
and humanizeEvents
authorizeInvocation
and friends as well as buildInvocationTree
.Server.simulateTransaction
and its related utilitiesA lot of this already exists in example dapps and other "fully featured" demos, but this hurts discoverability and ramping up for new users.
On pages like this one, there is use of LaTeX syntax for math, but it does not render correctly. It's probably missing a MathJax script?
The docs state that stellar-core can be installed from Ubuntu packages, but don't provide any instruction on how to do that, or what the custom apt repo is.
I think we should tell people what they need to do to configure the Stellar apt repo, as well as how to install the packages if we're discussing the package installation method here.
stellar-docs/docs/run-core-node/installation.mdx
Lines 42 to 46 in e9a03c0
We don't currently have a page that talks concretely and practically with examples for how to evaluate the cost of a contract, and how to improve the efficiency of contract functions.
This page should probably be in the form of a tutorial with a concrete example of how to view the cost of executing a contract function, then making a change to improve the efficiency of the contract, then re-running the contract and viewing the improved cost.
The tutorial should ideally touch on the derived cpu/mem costs as well as the individual costs that lead to the derived values, so that folks know how to identify where their costs are coming from.
Partner Experience initiative - Not much direction is provided in Running docs for how best to configure horizon and it's supporting infrastructure as containers, rather settings are documented individually and left to user to figure out best combinations.
Provide updated copy under the Running section, it should provide opinionated directions(and brief reason why) to informs reader on how they can deploy horizon in containers:
What should the containerization boundaries look like, should postgresql be internal to the same container as horizon?
Should a watcher core node be in same container as horizon?
How should command line parameters be passed to the horizon container, as environment variables?
When, where and how should shared external volumes be defined on any containers to enable larger storage requirements(most containers only get like 32G or less for default ephemeral storage).
Update the dockerfiles at https://github.com/stellar/go/blob/master/services/horizon/docker, consider adding a new examples
directory with new Dockerfile(s) that codify the recommendations here in docs.
Latest public docs site:
https://developers.stellar.org/docs/encyclopedia/claimable-balances#claim-claimable-balance
We were running into "op_no_trust" issues when attempting to claim an asset that destination account did not trust. We incorrectly assumed that claiming a claimable balance would also establish a trustline, but were incorrect. Clearer messaging about this in the docs would have saved us some time and trial/error.
The above linked page implies this, but it could be more explicit:
The balance on the entry will be moved to the source account if there are no limit or trustline issues (for non-native assets).
A note underneath that line that says something to the effect of:
For non-native assets, claimant account must have a trustline to the asset or claim will result in
op_no_trust
error.
No mention in the docs (that I could find) where it says a trustline must first be established before a balance can be claimed (for non-native assets).
Latest docs online (main-branch).
The JS example for the channel-accounts documentation uses an outdated method Network.useTestNetwork()
.
Usage of up-to-date code in example-snippet (as suggested in #34).
Not much insight is given on metrics published by horizon in docs. https://developers.stellar.org/docs/run-api-server/monitoring
Update https://developers.stellar.org/docs/run-api-server/monitoring.
Add More details on the metrics that are published, do they follow a standard such as OpenMetrics or just Prometheus?
Provide details on main family/grouping of metrics keys available.
What are the prometheus server settings to scrape metrics from horizon?
What config settings to horizon if any for metrics? best practices here.
Reference to some links of sample Grafana dashboards that have queries against the horizon metrics keys to demonstrate what's possible.
The docs does not shows how to pass arguements to contracts method via the soroban js client.
It has only one scenario of a contract method call without arguments.
Could anyone assist me with how to pass arguements to a contract method via the soroban js client.
The include_failed
parameter on various endpoints, such as transactions and operations, is documented as includefailed
.
Example: https://developers.stellar.org/api/resources/get-operations-by-account-id
The parameter key should be include_failed
.
The documentation reflects it as includefailed
.
Using the parameter as documented doesn't work
With include_failed
: https://horizon.stellar.org/accounts/GBFVU7QY6EMTYSF3WKH54CO5CE46BC72HOKZBBXH5YBJBLDVT3RNSNM2/operations?cursor=122568453843611647&limit=2&include_failed=true
With includefailed
: https://horizon.stellar.org/accounts/GBFVU7QY6EMTYSF3WKH54CO5CE46BC72HOKZBBXH5YBJBLDVT3RNSNM2/operations?cursor=122568453843611647&limit=2&includefailed=true
The transaction 3cdbcbef533c834095cee2719b812d51394f95043e17e0f92a5251faf5b318f5
is only reflected when the correct parameter name is used, as expected
We don't have an easy/quick way to garner feedback from site readers.
As a follow-up to stellar-deprecated/soroban-docs#586, we can provide users with a simple set of thumbsup/thumbsdown buttons. Essentially, it's exactly the same thing, just here.
Don't have the buttons? Use some third-party?
We might forget to update the docs to match as we change soroban-rpc.
Automatic generation or at least verification that the docs match the API as expected. This is an "eventually" wishlist item following on from stellar-deprecated/soroban-docs#247, where there is some previous work linked.
Do it manually
Horizon ingestion docs refer to many aspects of ingestion with variations of configuration, approach, and references to command line flag, environment variables some of which have become obsolete or not relevant. It may lead to confusion or un-necessary steps for readers.
Horizon ingestion docs are updated to present smaller copy, with direct, opinionated writeup on what/why ingestion is needed, the best strategy to follow for desired outcome, and concise updated examples of using the latest(and least number of) command line flags and config variables.
Review state verification and history retention(reaper) aspects and concise configuration examples to achieve.
Mention how to use ingestion filtering. Include concise configuration examples of Asset and Account filter rules and how there outcomes affect data stored in history.
Discuss the need to use captive core mode of ingestion only, and the config settings for ensuring on-disk usage.
Should we mention trying to do full history or discourage that in docs with explanation and recommend using DataWarehouse/Hubble for those concerns?
No copy present in current docs https://developers.stellar.org/docs/run-api-server/ for how to upgrade a recent installed horizon to newer version. There is copy on migrating from 1.x which is obsolete now?
horizon db migrate status
... what else is better to do here?I was chatting with a friend today and I showed them the soroban docs and they said they wanted to know how it compared to other smart contract platforms, especially wasm-based ones (cosmwasm, solana, elrond, etc.)
I think this would be a useful thing to add to the learn section, for people who want a quick summary and don't want to have to build a mental model of all the systems from the bottom up.
We're nearing the end of all the content that we want to produce in the partner_experience
branch. We should:
Create a tutorial dedicated to the topic of integration testing
multiple contracts together in a test.
We demonstrate testing of contracts in most examples. A couple examples involve multiple contracts and also happen to demonstrate how to run integration tests where multiple contracts are in use during the test.
However, if a developer was wanting to learn how to specifically do integration testing, gazing at our docs they would probably come to the conclusion it isn't supported as there is no tutorial focused on that topic alone.
Given it is an important topic, and a topic we have good support for, we would benefit from a tutorial that focuses solely on that.
There are two ways to run integration tests, and both should be demonstrated in a tutorial:
The "wasm" way
The primary contract being tested is loaded natively with dependencies loaded as .wasm using contractimport!
. The primary could also be loaded as wasm.
Good for:
Benefits:
The "native" way
The primary contract and dependencies are compiled natively as part of building the test. This requires having the source, and importing the dependency into the primary's Rust project.
Good for:
Benefits:
Both ways can be used together where tests have some dependencies as wasm and some native.
We have a fuzz testing tutorial that was added in stellar-deprecated/soroban-docs#486 (thanks @brson). Fuzz testing situations that require multiple contracts to be loaded into the VM benefit from the native testing approach, as it allows the fuzzer to identify inputs that cause branches in logic of dependencies which will help the fuzzer get increased code coverage. When we add the integration test page, we should link to the section on native testing from the fuzz testing docs.
Partner Experience initiative - consolidate horizon config docs section, review and update/refactor the copy to be lighter footprint but with more opinionated direction towards a single group of settings to enable user's to quickly get through it and have a decent running system afterwards, rather than documenting all settings individually and letting the user figure out how to group/associate them:
How much history should they retain?
Should they use in-memory or on-disk mode?
How often should they run state verification? Use the new config params …
What version of postgresql should they run?
How often (hopefully, never) do they need to manually vacuum their db?
Updated copy on horizon config in https://developers.stellar.org/docs/run-api-server/configuring
See this discussion on discord
Add to Tools
Integrate CLI docs into Consolidated Developer Docs, making them searchable and easily accessible
As identified in stellar/rs-soroban-sdk#1095 and further discussed in stellar/rs-soroban-sdk#1082 we need docs, and maybe a tutorial, for how to test contract consistency overtime. We need docs that discuss the concepts and importance of this as much as we need tutorials.
The docs need to emphasize the importance of this.
If we add a tutorial, or multiple tutorials, some options would be:
Generating the sample JSON requests and responses is pretty laborious manual task.
It looks like at some point we've lost tutorials and instructions for how to use quickstart in the main soroban docs. We used to at an early point in the getting started guide help folks run their contracts on their own private network using the stellar/quickstart image.
What I see today is no mention of it, instead only using testnet:
Ref: https://soroban.stellar.org/docs/getting-started/deploy-to-testnet
I think really early on in the developer journey we need to expose them to quickstart. It ideally should be step 3 in this flow. Quickstart is faster to develop against, albeit with some additional setup cost.
We should definitely promote testnet at the same points to and let folks hitup testnet directly. But still include quickstart as the recommended place to test and run contracts.
Helps docs users get help faster when navigating through the docs.
A footer at the bottom of the page that says something like: "Questions? Ask in the Stellar Developer Discord or Stellar Stack Exchange"
Appears that there's some missing word(s) here: https://developers.stellar.org/docs/run-core-node/configuring#updating-and-coordinating-your-quorum-set The text reads like this:
That way, you can and coordinate changes.
Something belongs between can
and and
, or the and
doesn't belong.
Placeholder issue for building ???-by-example.com website to teach new devs how to write stellar contracts.
Inspired by: https://solidity-by-example.org, and https://gobyexample.com. Largely, this depends on a lot of example contracts, building up from hello world, to complex defi examples.
These are the following resources about events
Events
(Basic Tutorials): a guide on publishing events targeting contract developersEvents
(Fundamentals and Concepts): contains two parts. The first describes events under the txmeta hood, targeting a fairly advanced audience. The second is an explanation on diagnostic events without going to specifics.getEvents
json-rpc referenceI suggest the following changes:
Consuming Events
section at the end of the Events
basic tutorial that demonstrated querying the RPC service for the events emitted in the tutorial.Events
fundamentals and concepts section. Digging into the txmeta is not something that we do elsewhere in the docs and seems a bit more confusing than beneficial, especially since we expect people to consume events through the rpc's getEvents
methodDiagnostic Events
reference section that outlines all known diagnostic eventsDebugging
section on using diagnostic events and link to the reference from itIn stellar/rs-soroban-env#613 we added an env.json
file that describes all of the host functions.
We should publish this interface in the docs. It will be useful for developers making SDKs. And developers working at a lower level.
We can generate the docs page based off the env.json
file.
The https://developers.stellar.org/docs/run-api-server/prerequisites has a lot of information, some duplication and obsolete facets may be present and may be difficult for readers to make correct conclusions for current day horizon capabilities.
Simplify/condense compute requirements tables stated for catch-up and real-time ingestion down to single section for horizon and db. Follow a more opinionated stance to reduce the amount of overall content, try to avoid explaining all settings individually, instead just state the combination that is recommended and why.
Focus recommendation towards `on-disk mode of captive core and don't mention in-memory settings. Describe why IOPSon the volume used to host captive core db needs to be fast SSD, and highest IOPS can afford, bare min of at least 3k r/w a second.
Mention ballpark estimates on how much it will be expected to cost in terms of compute, for those considering a cloud deployment.
latest docs
the docs use java sdk snippets that are pre-protocol 19 changes, after that the Transction build and submit class interfaces have changed a bit with preconditions, etc. community members are getting a bit confused to still see the old examples in these docs.
https://discord.com/channels/897514728459468821/921506043966656552/1009105031724802069
latest java.sdk, 0.37 class interfaces used for Transaction building/submit example code snippet.
older java.sdk, 0.31 and earlier class interfaces used for Transaction building/submit example code snippets in docs.
The "Create An App" article has some instructions regarding the soroban contract bindings
command in v0.9.4
.
Assuming those caveats and workarounds are no longer needed, we should update/modify/remove language here as necessary to reflect the new release.
@chadoh Can you update this page as needed? If you don't have time with Meridian coming up, I can get a PR started for you to review?
Our current cross contract call example panics when the called contract panics.
However, often times the calling contract would be interested in handling the error, rather than panicing. It would be beneficial to either add this to our existing cross contract how-to or potentially somewhere else.
For example, instead of this call, which will panic when add()
panics:
let client = contract_a::ContractClient::new(&env, contract_id);
client.add(&x, &y)
We can introduce something like this call, which will return 0 when add()
panics:
let client = contract_a::ContractClient::new(&env, contract_id);
client.try_add(&x, &y).unwrap_or(Ok(0)).unwrap()
Users are encountering errors when going through the Examples on this page: https://developers.stellar.org/docs/encyclopedia/liquidity-on-stellar-sdex-liquidity-pools#examples.
We need to update code snippets to avoid further errors. See specific conversation here: https://discord.com/channels/897514728459468821/907476473739354153/1137130480454610964
The getLedgerEntries
method is pretty powerful, you can retrieve any piece of state from the ledger: accounts, trustlines, offers, data, liquidity pools, contract wasms, contract instances, contract storage, yada yada.
However, there are two challenges associated with that:
However, our coding examples use pre-built keys and don't parse the results. I think that modifying our JS and Python examples in this page to include these can help unlock human potential
It is not clear how to represent a Rust Option
type in XDR. The custom-types documentation does not include any information about Option types.
Also, it would be helpful to have more tooling or at least a link to a reference implementation which converts Soroban types into their corresponding XDR structures. Otherwise, you are left guessing at how values should be encoded as SCVals.
We're getting a lot of questions that relate to the transaction lifecycle and don't have a great resource to send people to.
The regular Stellar resources are confusing because (a) they don't have any information on preflight and (b) soroban-rpc's tx submission is async
I think need to add a "Guides" section that provide education about how to do certain things at a higher level, and across a broader set of tools including wallets.
Right now the docs are really narrowly focused on specific areas. At the moment only one area: building the contracts themselves. Soon another narrow area: building dapps.
We don't have any documentation that tackle the bigger topics that @tyvdh has been highlighting need addressing:
The idea with the Guides is that they form higher level education, but are still focused on step-by-step instruction.
These guides ideally need to cover some categories, and within those categories there are specific more narrow tasks we need to be teaching:
I imagine there are many more topics than this, so anyone is welcome to please update this list.
In the referenced docs, it is stated "Every time the counter is incremented, this storage gets bumped by 100 ledgers, or about 500 seconds."
However, that is not the effect of env.storage().instance().bump(100, 100);
I would propose a correction, but I'm confused on the actual functioning and nomenclature myself.
(as per discussion with @tomerweller) It would be nice to have some guidelines on storing large sets of data on chain. For example, when storing a list of accounts, it's not immediately obvious that a scalable approach is to have each individual account as a separate key (instead of having one key "accounts" and a list as a value). An explanation that each key-val pair creates a ledger entry in core that is strictly limited in size would also be helpful.
Maybe something like:
✅ It is safe for all wallets to implement sending to muxed accounts.
❗ If you wish to receive deposits to muxed accounts please keep in mind that they are not yet supported by all wallets and exchanges
@Shaptic @leighmcculloch thoughts?
Keeps documentation up to date
Documentation here https://developers.stellar.org/api/horizon/resources/operations/object should include the new operation types that have been added for soroban
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.