diff --git a/docs/developers/index.md b/docs/developers/index.md index a4c5c62a..1aaf763b 100644 --- a/docs/developers/index.md +++ b/docs/developers/index.md @@ -55,7 +55,9 @@ This comprehensive resource hub is designed to empower developers to leverage th --- - Introducing the Harbinger testnet for the Koinos blockchain, a dedicated environment where developers can experiment with Koinos features, test smart contracts, and simulate real-world scenarios before deploying on the mainnet. The Harbinger testnet provides a safe and sandboxed environment for developers to validate their applications and gain insights into the capabilities and performance of the Koinos blockchain platform. + The Koinos Foundation public testnet gives developers a resettable + environment for testing applications and contracts with valueless tokens + before deploying to mainnet. [:octicons-arrow-right-24: Let's prototype](testnet.md) diff --git a/docs/developers/rest.md b/docs/developers/rest.md index 8c5a6898..aeccad7b 100644 --- a/docs/developers/rest.md +++ b/docs/developers/rest.md @@ -1,11 +1,66 @@ --- icon: fontawesome/solid/server hide: -- toc + - toc --- # REST API -The REST API provided by Koinos offers developers a convenient and straightforward way to interact with the blockchain using standard HTTP methods. This API simplifies integration and development by abstracting complex blockchain interactions into intuitive HTTP endpoints, making it accessible to a wider audience of developers who are familiar with web technologies. With the REST API, developers can easily query blockchain data, submit transactions, and interact with smart contracts without the need for specialized blockchain knowledge, streamlining the development process for decentralized applications (dApps) on the Koinos platform. + +The Koinos REST API exposes HTTP endpoints for reading blockchain data, +interacting with contracts, preparing transactions, and submitting signed +transactions. + +## Public endpoints + +| Network | REST base | Interactive reference | +| --- | --- | --- | +| Mainnet | `https://api.koinos.io/v1/...` | [Mainnet Swagger UI](https://api.koinos.io/swagger) | +| Public testnet | `https://testnet.koinosfoundation.org/v1/...` | Use the same route structure | + +Use JSON-RPC for raw Koinos service methods: + +- mainnet: `https://api.koinos.io/jsonrpc` +- public testnet: `https://testnet.koinosfoundation.org/jsonrpc` + +## Read chain data + +Read the current mainnet head: + +```bash +curl -sS https://api.koinos.io/v1/chain/head_info +``` + +The equivalent public-testnet route is: + +```text +https://testnet.koinosfoundation.org/v1/chain/head_info +``` + +## Prepare and submit transactions + +The prepare endpoint can populate transaction header fields. This request +prepares an empty example transaction but does not sign or broadcast it: + +```bash +curl -sS https://api.koinos.io/v1/transaction/prepare \ + -H 'content-type: application/json' \ + --data '{ + "header": { + "rc_limit": "200000000", + "payer": "17CmTGbriMyCypF6WdTRJGhzur3SoJXAG5" + }, + "operations": [] + }' +``` + +Submitting to `/v1/transaction/submit` requires a prepared transaction with the +necessary signatures. Applications remain responsible for protecting keys, +reviewing operations, and signing with a Koinos-compatible wallet, SDK, or +signing service. + +See the [REST interaction guide](../interacting/rest-api.md) for executable +examples, error handling, and retry guidance. --- + diff --git a/docs/developers/swagger.json b/docs/developers/swagger.json index 9aa23ac0..916840f1 100644 --- a/docs/developers/swagger.json +++ b/docs/developers/swagger.json @@ -10,8 +10,8 @@ "description": "Koinos Mainnet" }, { - "url": "https://harbinger-api.koinos.io", - "description": "Koinos Harbinger Testnet" + "url": "https://testnet.koinosfoundation.org", + "description": "Koinos Foundation Public Testnet" } ], "components": { @@ -2135,4 +2135,3 @@ } } } - diff --git a/docs/developers/testnet.md b/docs/developers/testnet.md index 2ec27871..e3679e75 100644 --- a/docs/developers/testnet.md +++ b/docs/developers/testnet.md @@ -2,70 +2,83 @@ icon: fontawesome/solid/network-wired --- -# Testnet -A blockchain testnet serves as a sandbox environment for developers and users to experiment, test, and deploy smart contracts, decentralized applications (DApps), and other blockchain-related functionalities without using real cryptocurrency or affecting the main blockchain network. Testnets mimic the behavior of the main blockchain but operate with fake or test tokens, allowing users to simulate real-world scenarios and interactions in a risk-free environment. They provide a platform for developers to debug code, identify potential vulnerabilities, and gauge the performance and scalability of their applications before deploying them on the mainnet. Testnets also facilitate collaboration among developers and enable the community to contribute to the improvement and evolution of blockchain protocols and applications through feedback and testing. +# Public Testnet ---- -## Harbinger -While anyone has the ability to spin up a testnet, Koinos Group provides a testnet for general use called Harbinger. To target a particular testnet one must retrieve the chain ID. The chain ID prevents your transaction from being valid on any other blockchain other than the one you are targeting. - -It is important to retrieve a fresh chain ID from Harbinger when doing work on testnet as it is not uncommon for the testnet to be restarted with a new chain ID. In other words, do not just copy this chain ID, retrieve it yourself before you use it. - -!!! example - An example of retrieving the Chain ID through JSON-RPC. - ```sh - curl -d '{"jsonrpc":"2.0", "id":0, "method":"chain.get_chain_id", "params":{}}' 'https://api.harbinger.koinos.pro/jsonrpc?apikey=' - ``` - ```json - { - "jsonrpc": "2.0", - "result": { - "chain_id": "EiBncD4pKRIQWco_WRqo5Q-xnXR7JuO3PtZv983mKdKHSQ==" - }, - "id": 0 - } - ``` - -Using the chain ID retrieved and your preferred Harbinger endpoint, you can use the testnet to deploy contracts and test your dApp. As you know, every action on Koinos requires Mana so we will need to acquire KOIN for testing. On testnet we call it tKOIN. +The Koinos Foundation maintains a public testnet for application and contract +development. Its tokens have no monetary value, and its chain state, deployed +contracts, and chain ID can change after a reset. ---- -## tKOIN and the faucet -tKOIN is the Koinos blockchain testnet token symbol. +!!! warning "Do not treat testnet state as permanent" + + Keep mainnet funds and production state away from the public testnet. + Retrieve the current chain ID before constructing or signing a transaction. + +## Current connection details + +| Service | URL | +| --- | --- | +| JSON-RPC | `https://testnet.koinosfoundation.org/jsonrpc` | +| JSON-RPC compatibility root | `https://testnet.koinosfoundation.org/` | +| REST | `https://testnet.koinosfoundation.org/v1/...` | +| REST compatibility path | `https://testnet.koinosfoundation.org/rest/...` | +| Health | `https://testnet.koinosfoundation.org/health` | +| Faucet | [KoinosTestnetFaucetBot](https://t.me/KoinosTestnetFaucetBot) | -Once you have your public address you can join our [Discord](https://discord.koinos.io) server and request some tKOIN in the `#faucet` channel under the Developer section by sending the following message to the faucet bot: +The operational source of truth is +[koinos/koinos-testnet](https://github.com/koinos/koinos-testnet). -### Example of acquiring tKOIN -The command to receive tKOIN from the faucet is as follows: +## Check availability + +```bash +curl -sS https://testnet.koinosfoundation.org/health ``` -!faucet + +The expected healthy response is: + +```text +ok ``` -!!! example - Given that your public address is `1ENxxuH81kytBdYe81fD9tBdYe81fD9Qxe`, within the `#faucet` channel write the following text command. - ```sh - !faucet 1ENxxuH81kytBdYe81fD9tBdYe81fD9Qxe - ``` +## Retrieve the current chain ID -!!! success - Upon success, you were see the following response from the Harbinger Faucet. - ```{ .txt, .no-copy } - Transferring 100.000000 tKOIN to address 1ENxxuH81kytBdYe81fD9tBdYe81fD9Qxe. - ``` +```bash +curl -sS https://testnet.koinosfoundation.org/jsonrpc \ + -H 'content-type: application/json' \ + --data '{"jsonrpc":"2.0","id":1,"method":"chain.get_chain_id","params":{}}' +``` -### Example of checking your tKOIN balance -The command to check your balance from the faucet is as follows: +Use the value returned in `result.chain_id`. Do not copy a testnet chain ID into +a long-lived configuration because it can change after a reset. + +## Get test tokens + +Open the [Telegram faucet](https://t.me/KoinosTestnetFaucetBot) and send: + +```text +/faucet YOUR_KOINOS_ADDRESS ``` -!balance + +Check the faucet's available balance with: + +```text +/balance ``` -!!! example - Given that your public address is `1ENxxuH81kytBdYe81fD9tBdYe81fD9Qxe`, within the `#faucet` channel write the following text command. - ```sh - !balance 1ENxxuH81kytBdYe81fD9BdYe81fD9Qxe - ``` - -!!! success - Upon success, you were see the following response from the Harbinger Faucet. - ```{ .txt, .no-copy } - Balance at address 1ENxxuH81kytBdYe81fD9tBdYe81fD9Qxe is 100.000000 tKOIN. - ``` \ No newline at end of file +The faucet currently distributes valueless **vKOIN**. Allocation sizes, +cooldowns, and daily limits can change, so follow the bot response and the +public testnet repository instead of relying on values copied into an +application. + +## Recommended development workflow + +1. Use a wallet reserved for testnet development. +2. Confirm the health endpoint responds. +3. Retrieve the current chain ID. +4. Request vKOIN for the wallet's public address. +5. Connect clients to the explicit `/jsonrpc` endpoint. +6. Expect balances and contracts to change after a reset. + +For runnable examples, continue with +[Testnet Development](../interacting/testnet.md). For the network comparison +and safety checklist, see +[Mainnet vs Testnet](../getting-started/mainnet-vs-testnet.md). diff --git a/docs/exchanges/multisig.md b/docs/exchanges/multisig.md index 417e7b50..82fb82a3 100644 --- a/docs/exchanges/multisig.md +++ b/docs/exchanges/multisig.md @@ -7,6 +7,13 @@ The most common use case for multisig on Koinos is paying for another address' t Below you can find examples of how to perform multisig using a variety of supported tools. +!!! warning "Recreate historical transaction data" + + The serialized CLI transcript below was produced on an earlier testnet. + Its chain ID, nonce, signatures, and encoded transaction are historical and + cannot be submitted to the current public testnet. Retrieve the current + chain ID and rebuild every transaction before signing. + === "Koinos CLI" Multisig using the Koinos CLI can be done using the `sign_transaction` command. The `sign_transaction` command accepts a transaction encoded in base64, signs it with the open wallet, and then outputs the transaction in base64 with the additional signature added. You can then use `submit_transaction` to submit the new transaction to the blockchain. @@ -67,8 +74,8 @@ Below you can find examples of how to perform multisig using a variety of suppor Base64: CiISIBi1R__zgY16nsHh5_Fb4c5vcZ2RNmLbdK8S14n8Xrh6EocBCiISIGdwPikpEhBZyj9ZGqjlD7GddHsm47c-1m_3zeYp0odJEIDC1y8aAigBIiISIKOpklf8aTYyWEznjTSfcsxYAeij5YlyGD5rew7hxKHvKhkAld7Gt6Kcrgx74cp4Bu_njyA2IGaZDR5YMhkAYdZB07coryO66Iuhp1Eu5_fj30VjGeuYGmESXwoZAJ_lH9WcjJMQmBCDCX0CXh1NdTgPLp-Z_BDK7dW_Aho8ChkAYdZB07coryO66Iuhp1Eu5_fj30VjGeuYEhkAld7Gt6Kcrgx74cp4Bu_njyA2IGaZDR5YGICU69wDIkEfyNwas3pxwjEYVubcI6En9e91L1fl-R7q-Gj4Y5fVfZE074Nqf0ZUbkJkcYfAuuVnJi604i-yOG90Jm2hHlYgiw== - 🚫 🔓 > connect https://api.harbinger.koinos.pro/jsonrpc?apikey=APIKEY - Connected to endpoint https://api.harbinger.koinos.pro/jsonrpc?apikey=APIKEY + 🚫 🔓 > connect https://testnet.koinosfoundation.org/jsonrpc + Connected to endpoint https://testnet.koinosfoundation.org/jsonrpc 🔓 > open wallets/test.wallet password Opened wallet: wallets/test.wallet diff --git a/docs/exchanges/offline-signing.md b/docs/exchanges/offline-signing.md index 9977099b..e57c7099 100644 --- a/docs/exchanges/offline-signing.md +++ b/docs/exchanges/offline-signing.md @@ -1,15 +1,21 @@ # Offline signing Regardless of your method of signing a transaction offline, you will need to manually set the Chain ID, nonce, and RC limit for the transaction. +!!! warning "Never broadcast copied transaction data" + + Serialized transactions and signatures shown on this page are historical + examples. Nonces, chain IDs, signatures, and resource limits must be + retrieved or recreated for the intended network and transaction. + --- ## Chain ID The Chain ID is a unique identifier for the specific chain you are transacting on. This prevents transactions from one chain from being valid on another. The Chain ID is derived from the genesis data, including the genesis key, which ensures uniqueness between Koinos based blockchains. It is encoded as a base64 string. -| Blockchain | Chain ID | -|-------------------|----------------------------------------------------| -| Koinos Mainnet | `EiBZK_GGVP0H_fXVAM3j6EAuz3-B-l3ejxRSewi7qIBfSA==` | -| Harbinger Testnet | `EiBncD4pKRIQWco_WRqo5Q-xnXR7JuO3PtZv983mKdKHSQ==` | +| Blockchain | Chain ID | +| --- | --- | +| Koinos Mainnet | `EiBZK_GGVP0H_fXVAM3j6EAuz3-B-l3ejxRSewi7qIBfSA==` | +| Koinos Foundation public testnet | [Retrieve the current chain ID](../getting-started/mainnet-vs-testnet.md#retrieve-the-current-chain-id) | --- ## Nonce diff --git a/docs/exchanges/rest.md b/docs/exchanges/rest.md index dee15402..bb8db4d5 100644 --- a/docs/exchanges/rest.md +++ b/docs/exchanges/rest.md @@ -7,6 +7,17 @@ The Koinos REST API provides a clean and simple way of interacting with the Koin You can view the [REST documentation](../developers/rest.md) to learn more. -The REST API is available on [Koinos**Pro**](https://koinos.pro). You can sign up for a free account and begin working with the REST API immediately. +Public REST endpoints are available at: -You can also access the REST API by running your own Koinos node. Learn how to run a Koinos node [here](../validators/guides/running-a-node.md). To enable the REST API, you will need to have `rest`, `api`, or `all` set in your `COMPOSE_PROFILES`. +- mainnet: `https://api.koinos.io/v1/...` +- public testnet: `https://testnet.koinosfoundation.org/v1/...` + +Preparing a transaction does not sign it. Submitting a transaction requires the +necessary signatures, which must be produced by a Koinos-compatible wallet, +SDK, or signing service. + +The REST API is also available on +[Koinos**Pro**](https://koinos.pro) and through a node you operate. See +[Running a Koinos node](../nodes/running-node.md) and +[Docker Compose profiles](../nodes/docker-profiles.md) for the relevant +services.