diff --git a/access-token-authorization/access-token-authorization.mdx b/access-token-authorization/access-token-authorization.mdx new file mode 100644 index 0000000..9fc5cb9 --- /dev/null +++ b/access-token-authorization/access-token-authorization.mdx @@ -0,0 +1,20 @@ +--- +title: "Access Token Authorization" +--- + +Access tokens generated on the platform are critical for securely authenticating API requests. These tokens grant access to specific resources or actions, as defined by the permissions assigned to them. + +For security reasons, the platform **does not store the token itself**. Instead, it maintains metadata associated with the token, such as its name, creation date, and expiration date, ensuring secure token management. + +**Access Token Utilization** + +Access tokens can be used to authorize interactions with the platform’s APIs in a secure and streamlined manner. The following header must be included in API requests to authenticate them: + +```text +Authorization: Bearer {accessToken} +``` + +This ensures that: + +- Only authorized users or applications can access the specified API resources. +- All API requests are securely authenticated and aligned with the token's permissions. \ No newline at end of file diff --git a/access-token-authorization/cloud-api.mdx b/access-token-authorization/cloud-api.mdx index 2efe743..f80c6f5 100644 --- a/access-token-authorization/cloud-api.mdx +++ b/access-token-authorization/cloud-api.mdx @@ -2,15 +2,11 @@ title: "Cloud Api" --- -## Cloud API - Manage Cloud nodes over a REST JSON API. ## Base URL -```text -https://cloud-api.thunderstack.org -``` +`[https://cloud-api.thunderstack.org]` ## Authentication @@ -26,7 +22,9 @@ Each request must include: -H "Authorization: Bearer ${CLOUD_API_TOKEN}" ``` -Examples below use `curl` and show paths relative to the base URL. + + Examples below use `curl` and show paths relative to the base URL. + ## List nodes @@ -61,23 +59,44 @@ Example response: ## Create a node -`POST /api/nodes` +**POST** `/api/nodes` -Body fields: `name` (string, required), `network` (string, required): regtest or testnet, `settings` (object, optional): webhookUrl +Body fields: + +- `name` (string, required) +- `network` (string, required): `regtest` or `testnet` +- `settings` (object, optional) + - webhookUrl (string, optional) ```text curl -s \ -H "Authorization: Bearer ${CLOUD_API_TOKEN}" \ -H "Content-Type: application/json" \ - -d '{"name":"my-node","network":"regtest","settings":{"webhookUrl":"https://example.com/webhooks/thunderstack"}}' \ + -d '{ + "name":"my-node", + "network":"regtest", + "settings":{"webhookUrl":"https://example.com/webhooks/thunderstack"} +}' \ "https://cloud-api.thunderstack.org/api/nodes" ``` -Example response: `{ "data": { "nodeId": "", "name": "my-node", "network": "regtest", "status": "STARTING" }, "message": "" }` +Example response: + +```text +{ + "data": { + "nodeId": "", + "name": "my-node", + "network": "regtest", + "status": "STARTING" + }, + "message": "" +} +``` ## Get a node -`GET /api/nodes/{id}` +**GET** `/api/nodes/{id}` ```text curl -s \ @@ -87,7 +106,13 @@ curl -s \ ## Destroy a node -`DELETE /api/nodes` — Body: `destroyNodeId` (string, required). This endpoint expects a JSON body on a DELETE request. +DELETE `/api/nodes` + +Body: `destroyNodeId` (string, required). + + + This endpoint expects a JSON body on a DELETE request. + ```text curl -s -X DELETE \ @@ -97,9 +122,15 @@ curl -s -X DELETE \ "https://cloud-api.thunderstack.org/api/nodes" ``` +Example response: + +```text +{ "message": "" } +``` + ## Webhooks: public key -`GET /api/webhook-public-key` — Returns the public key used to verify webhook signatures. +**GET** `/api/webhook-public-key` — Returns the public key used to verify webhook signatures. ```text curl -s \ @@ -107,11 +138,15 @@ curl -s \ "https://cloud-api.thunderstack.org/api/webhook-public-key" ``` -Example response: `{ "data": "" }` +Example response: + +```text +{ "data": "" } +``` ## RLN images: latest version -`GET /api/nodes/latest-rln-image` +**GET** `/api/nodes/latest-rln-image` ```text curl -s \ @@ -119,11 +154,15 @@ curl -s \ "https://cloud-api.thunderstack.org/api/nodes/latest-rln-image" ``` -Example response: `{ "data": "" }` +Example response: + +```text +{ "data": "" } +``` ## RLN images: upgrade node -`POST /api/nodes/{id}/upgrade` +**POST** `/api/nodes/{id}/upgrade` ```text curl -s -X POST \ @@ -131,9 +170,17 @@ curl -s -X POST \ "https://cloud-api.thunderstack.org/api/nodes//upgrade" ``` +Example response: + +```text +{ "message": "" } +``` + ## Node settings: update -`POST /api/nodes/{id}/settings` — Use this to change node settings like `webhookUrl`. +**POST** `/api/nodes/{id}/settings` + +Use this to change node settings like `webhookUrl`. ```text curl -s -X POST \ @@ -143,9 +190,15 @@ curl -s -X POST \ "https://cloud-api.thunderstack.org/api/nodes//settings" ``` +Example response: + +```text +{ "message": "" } +``` + ## Node lifecycle: start -`POST /api/nodes/{id}/start` +**POST** `/api/nodes/{id}/start` ```text curl -s -X POST \ @@ -155,7 +208,7 @@ curl -s -X POST \ ## Node lifecycle: stop -`POST /api/nodes/{id}/stop` +**POST** `/api/nodes/{id}/stop` ```text curl -s -X POST \ @@ -165,7 +218,9 @@ curl -s -X POST \ ## Logs: trigger export -`POST /api/nodes/{id}/logs` — Starts a log export job for a node. +**POST** `/api/nodes/{id}/logs` + + Starts a log export job for a node. ```text curl -s -X POST \ @@ -173,11 +228,15 @@ curl -s -X POST \ "https://cloud-api.thunderstack.org/api/nodes//logs" ``` -Example response: `{ "taskId": "" }` +Example response: + +```text +{ "taskId": "" } +``` ## Logs: get download URLs -`GET /api/nodes/{id}/logs?taskId={taskId}` +GET `/api/nodes/{id}/logs?taskId={taskId}` ```text curl -s \ @@ -185,4 +244,8 @@ curl -s \ "https://cloud-api.thunderstack.org/api/nodes//logs?taskId=" ``` -Example response: `{ "data": [""] }` \ No newline at end of file +Example response: + +```text +{ "data": [""] } +``` \ No newline at end of file diff --git a/access-token-authorization/create-api-token.mdx b/access-token-authorization/create-api-token.mdx index 032a0e5..e4bd9c9 100644 --- a/access-token-authorization/create-api-token.mdx +++ b/access-token-authorization/create-api-token.mdx @@ -2,11 +2,32 @@ title: "Create API Token" --- -1. **Navigate to the API Tokens page and create an access token** - Go to the API Tokens page and choose "Create Access Token". -2. **Provide a token name** - Input a name for the token. This helps manage multiple tokens. -3. **Revoking a token** - Tokens on this platform do not expire. They remain valid until manually revoked. - - To revoke an access token, return to the API Tokens section, find the token item, and click the **"Revoke"** button for that token. - - Revoking a token immediately deactivates it and prevents any further API access using that token. \ No newline at end of file + + + Go to the API Tokens page and choose "Create Access Token". + + + ![Image](/images/image-16.png) + + + + Input a name for the token. This helps manage multiple tokens. + + + + Tokens on this platform do not expire. They remain valid until manually revoked. + + + - To revoke an access token, return to the API Tokens section, find the token item, and click the **"Revoke"** button for that token. + + - Revoking a token immediately deactivates it and prevents any further API access using that token. + + + ![Image](/images/image-17.png) + + + + + + + \ No newline at end of file diff --git a/bridge/getting-started.mdx b/bridge/getting-started.mdx index 226b709..30a744e 100644 --- a/bridge/getting-started.mdx +++ b/bridge/getting-started.mdx @@ -2,98 +2,158 @@ title: "Getting Started" --- -# Getting Started - ## How Ethereum → RGB Transfers Work When transferring USDT from the Ethereum network to RGB, you receive an equivalent TUSDT token in the RGB network. The transfer is made through Utexo, with transactions signed in MetaMask and an RGB invoice used as the recipient address. -### 🔧 Requirements Before You Start + + 🔧 Requirements Before You Start + + **MetaMask** -**MetaMask** + - ETH balance (to pay for gas fees). + - USDT balance (the amount you will transfer). -- ETH balance (to pay for gas fees). -- USDT balance (the amount you will transfer). + **IRIS Wallet (Mobile App)** -**IRIS Wallet (Mobile App)** + - BTC balance (to pay the RGB transaction fee). + + **Connect RGB Wallet on the Bridge** — you can do this in two ways: -- BTC balance (to pay the RGB transaction fee). -- Connect RGB Wallet on the Bridge — you can do this in two ways: - Click CONNECT RGB WALLET at the bottom of the bridge form. - Open the wallet list in the top-right corner of the bridge page and click the power button next to RGBWallet. + + + + + **Enter the amount** — In the Amount field, enter the number of USDT tokens to transfer. + + **Enter the destination address** — In the Destination field, paste an RGB invoice generated in the IRIS Wallet mobile app: + + - Ensure your wallet has a BTC balance to cover the transaction fee. + - Open IRIS Wallet → select Receive assets. + - Generate the invoice and copy it. + - Paste this invoice into the Destination field on Utexo. + + +
+ Image -### 1. Enter the transfer details + Image +
+ -**Enter the amount** — In the Amount field, enter the number of USDT tokens to transfer. + + ![Image](/images/image-22.png) + + + + After filling in the form, a **Transaction Preview** will appear showing: -**Enter the destination address** — In the Destination field, paste an RGB invoice generated in the IRIS Wallet mobile app: + - **You will receive** — estimated amount of tUSDT after fees. + - **Estimated gas fee** — Ethereum network gas fee at live market rates. + - **Bridge commission** — fixed % fee charged by Utexo. -- Ensure your wallet has a BTC balance to cover the transaction fee. -- Open IRIS Wallet → select Receive assets. -- Generate the invoice and copy it. -- Paste this invoice into the Destination field on Utexo. + Click **Transfer**. MetaMask will request confirmation in three stages: -### 2. Review and confirm the transaction + **Approve token spending** — A MetaMask popup will appear asking you to approve USDT spending. Click Confirm. -After filling in the form, a **Transaction Preview** will appear showing: + **Confirm the transaction** — Wait 2–10 seconds for the second MetaMask popup. Review the details and click Confirm to complete the transfer. -- **You will receive** — estimated amount of TUSDT after fees. -- **Estimated gas fee** — Ethereum network gas fee at live market rates. -- **Bridge commission** — fixed % fee charged by Utexo. + +
+ Image -Click **Transfer**. MetaMask will request confirmation in three stages: + Image -**Approve token spending** — A MetaMask popup will appear asking you to approve USDT spending. Click Confirm. + Image +
+ + + + In the IRIS Wallet mobile app, wait until the tUSDT tokens are credited to your balance. -**Confirm the transaction** — Wait 2–10 seconds for the second MetaMask popup. Review the details and click Confirm to complete the transfer. + This may take longer than usual due to high Bitcoin network congestion. + + -### 3. Wait for TUSDT to be credited +## w RGB → Ethereum Transfers Work (TUSDT → USDT) -In the IRIS Wallet mobile app, wait until the TUSDT tokens are credited to your balance. + + + On Utexo, set: -This may take longer than usual due to high Bitcoin network congestion. + - **Send:** Blockchain – RGB, Token – TUSDT. + - **Receive:** Blockchain – Ethereum, Token – USDT. -## How RGB → Ethereum Transfers Work (TUSDT → USDT) + Enter the **Amount** of TUSDT you want to send. -### 1. Prepare the transaction on the bridge + In the **Destination address** field, enter your Ethereum address (MetaMask). -On Utexo, set: + Review the preview section, it will display: -- **Send:** Blockchain – RGB, Token – TUSDT. -- **Receive:** Blockchain – Ethereum, Token – USDT. + - **You will receive** - estimated amount of USDT after fees. + - **Estimated gas fee** and Commission. -Enter the **Amount** of TUSDT you want to send. + Click **TRANSFER**. -In the **Destination address** field, enter your Ethereum address (MetaMask). + +
+ Image -Review the preview section — it will display: **You will receive** — estimated amount of USDT after fees. **Estimated gas fee** and Commission. + Image +
+ + + + - Once the bridge generates the RGB invoice (popup with QR code), open the IRIS Wallet mobile app. + - Go to your TUSDT token. + - Tap **Send**. + - Tap the QR scanner icon and scan the QR code from the Utexo popup. + - Confirm sending in IRIS Wallet by pressing Send. -Click **TRANSFER**. + +
+ Image -### 2. Pay the RGB invoice + Image +
+ + + + After sending, the transaction will first appear with the status **WAITING\_COUNTERPARTY**. -Once the bridge generates the RGB invoice (popup with QR code), open the IRIS Wallet mobile app. + Refresh your wallet (tap the refresh icon). -- Go to your TUSDT token. -- Tap **Send**. -- Tap the QR scanner icon and scan the QR code from the Utexo popup. -- Confirm sending in IRIS Wallet by pressing Send. + Once refreshed, the transaction status should change to **WAITING\_CONFIRMATIONS**, meaning it is now being processed on the Bitcoin network. -### 3. Check transaction status in IRIS Wallet + +
+ Image -After sending, the transaction will first appear with the status **WAITING\_COUNTERPARTY**. + Image +
+ -Refresh your wallet (tap the refresh icon). + +
+ Image -Once refreshed, the transaction status should change to **WAITING\_CONFIRMATIONS**, meaning it is now being processed on the Bitcoin network. + Image +
+ + + -### 🔧 Additional notes + + 🔧 Additional notes -Transaction time may vary depending on Bitcoin network congestion — in some cases, it may take longer than expected. + Transaction time may vary depending on Bitcoin network congestion, in some cases, it may take longer than expected. -In IRIS Wallet, a finalized transaction is highlighted in: + In IRIS Wallet, a finalized transaction is highlighted in: -- **Red** – for RGB → Ethereum transfers (asset deduction). -- **Green** – for Ethereum → RGB transfers (asset credit). + - **Red** – for RGB → Ethereum transfers (asset deduction). + - **Green** – for Ethereum → RGB transfers (asset credit). + You're all set! Enjoy smooth and secure cross-chain transfers with Utexo. \ No newline at end of file diff --git a/cloud/getting-started.mdx b/cloud/getting-started.mdx index abc556c..a2bed42 100644 --- a/cloud/getting-started.mdx +++ b/cloud/getting-started.mdx @@ -2,8 +2,6 @@ title: "Getting Started" --- -# Getting Started - Create, connect, upgrade, back up, and destroy RLN nodes on Thunderstack. Use these guides to manage an RLN node end to end. diff --git a/cloud/rgb-lightning-node-api.mdx b/cloud/rgb-lightning-node-api.mdx index 3143d7b..9c899c5 100644 --- a/cloud/rgb-lightning-node-api.mdx +++ b/cloud/rgb-lightning-node-api.mdx @@ -9,62 +9,64 @@ Once nodes are running, they can be operated via REST JSON APIs. For example, using curl: ```text -curl -X POST -H "Content-type: application/json" -d '{"ticker": "USDT", "name": "Tether", "amounts": [666], "precision": 0}' http://localhost:3001/issueasset +curl -X POST -H "Content-type: application/json" \ + -d '{"ticker": "USDT", "name": "Tether", "amounts": [666], "precision": 0}'\ + http://localhost:3001/issueasset ``` The node currently exposes the following APIs: -- /address (POST) -- /assetbalance (POST) -- /assetmetadata (POST) -- /backup (POST) -- /btcbalance (POST) -- /changepassword (POST) -- /checkindexerurl (POST) -- /checkproxyendpoint (POST) -- /closechannel (POST) -- /connectpeer (POST) -- /createutxos (POST) -- /decodelninvoice (POST) -- /decodergbinvoice (POST) -- /disconnectpeer (POST) -- /estimatefee (POST) -- /failtransfers (POST) -- /getassetmedia (POST) -- /getchannelid (POST) -- /init (POST) -- /invoicestatus (POST) -- /issueassetcfa (POST) -- /issueassetnia (POST) -- /issueassetuda (POST) -- /keysend (POST) -- /listassets (POST) -- /listchannels (GET) -- /listpayments (GET) -- /listpeers (GET) -- /listswaps (GET) -- /listtransactions (POST) -- /listtransfers (POST) -- /listunspents (POST) -- /lninvoice (POST) -- /lock (POST) -- /makerexecute (POST) -- /makerinit (POST) -- /networkinfo (GET) -- /nodeinfo (GET) -- /openchannel (POST) -- /postassetmedia (POST) -- /refreshtransfers (POST) -- /restore (POST) -- /rgbinvoice (POST) -- /sendasset (POST) -- /sendbtc (POST) -- /sendonionmessage (POST) -- /sendpayment (POST) -- /shutdown (POST) -- /signmessage (POST) -- /sync (POST) -- /taker (POST) -- /unlock (POST) +- `/address` (POST) +- `/assetbalance` (POST) +- `/assetmetadata` (POST) +- `/backup` (POST) +- `/btcbalance` (POST) +- `/changepassword` (POST) +- `/checkindexerurl` (POST) +- `/checkproxyendpoint` (POST) +- `/closechannel` (POST) +- `/connectpeer` (POST) +- `/createutxos` (POST) +- `/decodelninvoice` (POST) +- `/decodergbinvoice` (POST) +- `/disconnectpeer` (POST) +- `/estimatefee` (POST) +- `/failtransfers` (POST) +- `/getassetmedia` (POST) +- `/getchannelid` (POST) +- `/init` (POST) +- `/invoicestatus` (POST) +- `/issueassetcfa` (POST) +- `/issueassetnia` (POST) +- `/issueassetuda` (POST) +- `/keysend` (POST) +- `/listassets` (POST) +- `/listchannels` (GET) +- `/listpayments` (GET) +- `/listpeers` (GET) +- `/listswaps` (GET) +- `/listtransactions` (POST) +- `/listtransfers` (POST) +- `/listunspents` (POST) +- `/lninvoice` (POST) +- `/lock` (POST) +- `/makerexecute` (POST) +- `/makerinit` (POST) +- `/networkinfo` (GET) +- `/nodeinfo` (GET) +- `/openchannel` (POST) +- `/postassetmedia` (POST) +- `/refreshtransfers` (POST) +- `/restore` (POST) +- `/rgbinvoice` (POST) +- `/sendasset` (POST) +- `/sendbtc` (POST) +- `/sendonionmessage` (POST) +- `/sendpayment` (POST) +- `/shutdown` (POST) +- `/signmessage` (POST) +- `/sync` (POST) +- `/taker` (POST) +- `/unlock` (POST) -To get more details about the available APIs see the OpenAPI specification. A Swagger UI is available at https://rgb-tools.github.io/rgb-lightning-node \ No newline at end of file +To get more details about the available APIs see the OpenAPI specification. A Swagger UI for the `master` branch is generated from the specification and available at [https://rgb-tools.github.io/rgb-lightning-node](https://rgb-tools.github.io/rgb-lightning-node) \ No newline at end of file diff --git a/cloud/rln-node/connect-rln-node.mdx b/cloud/rln-node/connect-rln-node.mdx index d26e052..2be83e8 100644 --- a/cloud/rln-node/connect-rln-node.mdx +++ b/cloud/rln-node/connect-rln-node.mdx @@ -2,35 +2,43 @@ title: "Connect to RLN Node" --- -## Connecting to Node with mTLS +### Connecting to Node with mTLS Follow these detailed steps to establish a secure connection to your node using the provided mTLS credentials: -### Access Node Connection Details - -- Navigate to the Connect Page: open your web browser and go to the /connect page. This page provides the connection details for your node. URL: `https://www.thunderstack.org/{nodeId}/connect` - -- View Connection Details: the connect page displays the unique endpoint URL for your node, along with the private key and certificate required for the mTLS connection. These credentials are automatically generated for your session and are required to establish a secure connection. - -### Obtain Connection Credentials and URL - -- Download Credentials from the /connect page: - - Private Key: a `.key` file (e.g., `privateKey.key`) containing your private key. - - Certificate: a `.pem` file (e.g., `certificate.pem`) containing your public key certificate. -- Copy Endpoint URL: the page will display the unique endpoint URL formatted like: `https://{userId}.thunderstack.org/nodes/{userId}/{nodeId}/` - -### Prepare the Request - -- Save the downloaded files in a secure location on your computer. You will reference these files when making requests. -- Use the example curl command shown on the /connect page as a template. Modify the example by replacing placeholders with the actual paths to your saved key and certificate files. - -- Example pattern (replace paths/placeholders accordingly): - -```text -curl --key /path/to/privateKey.key --cert /path/to/certificate.pem https://{userId}.thunderstack.org/nodes/{userId}/{nodeId}/ -``` - -## Connecting to Node with API token + + + - Navigate to the Connect Page: open your web browser and go to the /connect page. This page provides the connection details for your node. URL: `https://www.thunderstack.org/{nodeId}/connect` + + ![Image](/images/image-14.png) + + - View Connection Details: the connect page displays the unique endpoint URL for your node, along with the private key and certificate required for the mTLS connection. These credentials are automatically generated for your session and are required to establish a secure connection. + + + - Download Credentials from the /connect page: + - Private Key: a `.key` file (e.g., `privateKey.key`) containing your private key. + - Certificate: a `.pem` file (e.g., `certificate.pem`) containing your public key certificate. + - Copy Endpoint URL: the page will display the unique endpoint URL formatted like: `https://{userId}.thunderstack.org/nodes/{userId}/{nodeId}/` + + + ![Image](/images/image-11.png) + + + + - Save the downloaded files in a secure location on your computer. You will reference these files when making requests. + - Use the example curl command shown on the /connect page as a template. Modify the example by replacing placeholders with the actual paths to your saved key and certificate files. + + ![Image](/images/image-8.png) + + Example pattern (replace paths/placeholders accordingly): + + ```text + curl --key /path/to/privateKey.key --cert /path/to/certificate.pem https://{userId}.thunderstack.org/nodes/{userId}/{nodeId}/ + ``` + + + +### Connecting to Node with API token Follow these steps to connect using an API token. diff --git a/cloud/rln-node/create-rln-node.mdx b/cloud/rln-node/create-rln-node.mdx index 9b7ebe3..ad5b0ce 100644 --- a/cloud/rln-node/create-rln-node.mdx +++ b/cloud/rln-node/create-rln-node.mdx @@ -2,45 +2,59 @@ title: "Create RLN Node" --- -### Initiate RLN Node Creation - -- Navigate to the `/nodes` page. Here you'll see an overview of your current nodes and the option to create new ones. - -- Click the "Create Node" button. This redirects you to a page where you can begin the node creation process. - -### Configure Your RLN Node - -- On the redirected page, fill out the node creation form by entering a unique name for your new node. This name helps you identify the node in your dashboard. -- After entering a name, click the "Create" button to submit the form and start the node creation process. - -On the Regtest Network, block mining doesn't happen automatically. Manually mine blocks using the provided curl commands whenever you want the chain to advance or confirm activity. - -To mine blocks: - -```text -curl --location 'http://18.119.98.232:5000/execute' \ - --header 'Content-Type: application/json' \ - --data '{ "args": "mine 10" }' -``` - -If you need test BTC, use the `sendtoaddress` command (acts like a local faucet), then manually mine a block with the curl command above to confirm it: - -```text -curl --location 'http://18.119.98.232:5000/execute' \ - --header 'Content-Type: application/json' \ - --data '{ "args": "sendtoaddress
0.1" }' -``` - -### Monitor Node Creation Status - -- After submitting the form, a new item is added to the nodes table on the `/nodes` page. Initially it will display a status of IN\_PROGRESS while the node is being built. During this phase you cannot perform operations with the node. -- You can view detailed information by visiting `/nodes/{nodeId}`. That page shows current status, build progress, endpoint details, and other configurable options so you can monitor the node's setup process. - -#### Understanding statuses - -- **IN\_PROGRESS**: Node is under construction. No interactions can be made. -- **RUNNING**: Node has been successfully built and is fully operational. - -### Final Verification - -- Once the status changes to RUNNING, verify the node appears correctly in your dashboard and that you can access its features and settings. \ No newline at end of file + + + - Navigate to the `/nodes` page. Here you'll see an overview of your current nodes and the option to create new ones. + + ![Image](/images/image.png) + + Click the "Create Node" button. This redirects you to a page where you can begin the node creation process. + + + - On the redirected page, fill out the node creation form by entering a unique name for your new node. This name helps you identify the node in your dashboard. + - After entering a name, click the "Create" button to submit the form and start the node creation process. + + + ![Image](/images/image-2.png) + + + + On the Regtest Network, block mining doesn't happen automatically. Manually mine blocks using the provided curl commands whenever you want the chain to advance or confirm activity. + + To mine blocks: + + ```text + curl --location 'http://18.119.98.232:5000/execute' \ + --header 'Content-Type: application/json' \ + --data '{ "args": "mine 10" }' + ``` + + If you need test BTC, use the `sendtoaddress` command (acts like a local faucet), then manually mine a block with the curl command above to confirm it: + + ```text + curl --location 'http://18.119.98.232:5000/execute' \ + --header 'Content-Type: application/json' \ + --data '{ "args": "sendtoaddress
0.1" }' + ``` + + + + - After submitting the form, a new item is added to the nodes table on the `/nodes` page. Initially it will display a status of IN\_PROGRESS while the node is being built. During this phase you cannot perform operations with the node. + - You can view detailed information by visiting `/nodes/{nodeId}`. That page shows current status, build progress, endpoint details, and other configurable options so you can monitor the node's setup process. + + + ![Image](/images/image-3.png) + + + #### Understanding statuses + + - **IN\_PROGRESS:** Node is under construction. No interactions can be made. + - **RUNNING:** Node has been successfully built and is fully operational. + + + - Once the status changes to RUNNING, verify the node appears correctly in your dashboard and that you can access its features and settings. + + ![Image](/images/image-4.png) + + + \ No newline at end of file diff --git a/cloud/rln-node/destroy-rln-node.mdx b/cloud/rln-node/destroy-rln-node.mdx index a5f7e55..9787d93 100644 --- a/cloud/rln-node/destroy-rln-node.mdx +++ b/cloud/rln-node/destroy-rln-node.mdx @@ -2,11 +2,21 @@ title: "Destroy your Node" --- -1. **Initiate Node Destruction** - To begin the destruction process, navigate to the specific node's page by accessing `/nodes/{nodeId}`. -2. **Check Node Status** - Ensure that the node is in a `RUNNING` status. Nodes in this state are eligible for destruction. -3. **Destroy the Node** - Click the **"Destroy"** button available on the page. This action will initiate the destruction process, and the node's status will change to `IN_PROGRESS` to indicate that the destruction is underway. -4. **Final Status Update** - Once the node has been successfully destroyed, the status will update to `DESTROYED`. This confirms that the node has been decommissioned and all associated resources have been properly cleaned up. \ No newline at end of file + + + To begin the destruction process, navigate to the specific node's page by accessing `/nodes/{nodeId}`. + + + ![Image](/images/image-7.png) + + + + Ensure that the node is in a `RUNNING` status. Nodes in this state are eligible for destruction. + + + Click the **"Destroy"** button available on the page. This action will initiate the destruction process, and the node's status will change to `IN_PROGRESS` to indicate that the destruction is underway. + + + Once the node has been successfully destroyed, the status will update to `DESTROYED`. This confirms that the node has been decommissioned and all associated resources have been properly cleaned up. + + \ No newline at end of file diff --git a/cloud/rln-node/node-backup-restore.mdx b/cloud/rln-node/node-backup-restore.mdx index 05586ee..23749f7 100644 --- a/cloud/rln-node/node-backup-restore.mdx +++ b/cloud/rln-node/node-backup-restore.mdx @@ -2,32 +2,35 @@ title: "Node Backup/Restore" --- -### Access Backup Functionality - -Navigate to the specific node's backup page at nodes/{nodeId}/backup. - -### Create a Backup - -- If no backup has been previously created, the page will display a "Create Backup" button. -- Clicking the button triggers an AWS Lambda function that communicates with the RGB node's /backup API endpoint. -- Once the backup is successfully created, it is automatically uploaded to an Amazon S3 bucket. - -### Download - -A pre-signed URL is generated allowing direct download from S3. The URL expires 30 minutes after being issued. + + + Users can manage backups for their nodes by navigating to the specific node’s backup page at `nodes/{nodeId}/backup`. + + + - If no backup has been previously created, the page will display a "Create Backup" button in the "Backup Node" section. + - To initiate the backup process, the user clicks the "Create Backup" button. + - Clicking the button triggers an AWS Lambda function that communicates with the RGB node's `/backup` API endpoint to start the backup process on the node. + - Once the backup is successfully created, it is automatically uploaded to an Amazon S3 bucket. The bucket is structured to organize backups based on `userId` and `nodeId`, ensuring backups are easy to manage and retrieve. + + + A pre-signed URL is generated and provided to the user. This URL allows the user to download the backup directly from the S3 bucket. For security purposes, the URL is time-limited and expires 30 minutes after being issued. + + ## Node Restore -### Access Restore Functionality - -Navigate to the node's backup page and find the "Restore node" section at nodes/{nodeId}/backup. - -### Uploading the Backup File - -- Click "Upload" to generate an S3 upload URL. -- Select the backup file from your local device. The upload begins automatically. - -### Restoring Node - -- After the upload completes, a "Restore" button becomes active. -- Click the "Restore" button to start the restoration process via the node's /restore API. \ No newline at end of file + + + Users can manage backups for their nodes by navigating to the specific node’s backup page and find the "Restore node" section at `nodes/{nodeId}/backup`. + + + - Click "Upload" this button will generate an S3 upload URL. + - Once the S3 upload URL is generated, users are prompted to select the backup file from their local device. + - After selecting the file, the upload begins automatically, securely transferring the backup file to the designated S3 bucket. + + + - After the upload is successfully completed, a "Restore" button becomes active on the interface. + - Users click the "Restore" button to start the restoration process. It triggers the node’s `/restore` API. + - The `/restore` API facilitates the restoration by taking the backup data from S3 and applying it to the node. + + \ No newline at end of file diff --git a/cloud/rln-node/node-ui-actions.mdx b/cloud/rln-node/node-ui-actions.mdx index 60696c5..24a0e6a 100644 --- a/cloud/rln-node/node-ui-actions.mdx +++ b/cloud/rln-node/node-ui-actions.mdx @@ -2,28 +2,36 @@ title: "Node UI Actions" --- -On the Node Page (/node/{nodeId}), users have access to several interactive actions: /init, /lock, /unlock, and /nodeInfo. - -### /nodeInfo - -- Functionality: Automatically retrieves and displays the node's current status each time the node page is opened. -- Error handling: If the node is locked or encounters issues, the UI displays an appropriate error message. -- Use case: Provides real-time visibility into the node's status. - -### /init - -- Functionality: Initializes the node after its creation, making it ready for operation. -- Process: During initialization, the system generates a mnemonic and provides it to the user. The mnemonic must be securely saved. -- Use case: Mandatory step after node creation to enable further actions. - -### /lock - -- Functionality: Secures the node by locking it, preventing unauthorized access. -- Process: The user enters a password to lock the node. -- Use case: Protects sensitive node operations when not actively in use. - -### /unlock - -- Functionality: Unlocks the node, allowing it to resume normal operations. -- Process: The user enters the correct password to reverse the lock status. -- Use case: Enables the user to access and manage the node after it has been secured. \ No newline at end of file +On the Node Page (`/node/{nodeId}`), users have access to several interactive actions: `/init`, `/lock`, `/unlock`, and `/nodeInfo`. + + + + - Functionality: Automatically retrieves and displays the node's current status each time the node page is opened. + - Error handling: If the node is locked or encounters issues, the UI displays an appropriate error message. + - Use case: Provides real-time visibility into the node's status and helps diagnose any operational issues. + + + - Functionality: Initializes the node after its creation, making it ready for operation. + - Process: + - During initialization, the system generates a mnemonic and provides it to the user. + - The mnemonic is a critical security feature and must be securely saved by the user. + + The mnemonic is required for recovering the node in case of future issues and for ensuring secure access in all subsequent interactions. Save it securely. + + - Use case: Mandatory step after node creation to enable further actions. + + + - Functionality: Secures the node by locking it, preventing unauthorized access. + - Process: + - The user enters a password to lock the node. + - The node remains locked until the correct password is provided to unlock it. + - Use case: Protects sensitive node operations when not actively in use. + + + - Functionality: Unlocks the node, allowing it to resume normal operations. + - Process: + - The user enters the correct password to reverse the lock status. + - Once unlocked, the node becomes fully operational. + - Use case: Enables the user to access and manage the node after it has been secured. + + \ No newline at end of file diff --git a/cloud/rln-node/upgrade-rln-node.mdx b/cloud/rln-node/upgrade-rln-node.mdx index abf303f..6602bae 100644 --- a/cloud/rln-node/upgrade-rln-node.mdx +++ b/cloud/rln-node/upgrade-rln-node.mdx @@ -12,20 +12,27 @@ The notification will appear at the top of the node details page and include the > "Please note: Your current RLN image version is no longer supported. Update your node to the latest version." -### Steps to Upgrade the Node - -1. **Click the "Upgrade" Button** - - Navigate to the node page where the notification block appears. - - Click the **"Update"** button to trigger the upgrade process. - - This action initiates the upgrade to the latest RLN image version. -2. **Wait for the Upgrade to Complete** - - The upgrade process may take a few minutes. - - During this time, the node will be **locked**. -3. **Unlock the Node** - - Once the upgrade is complete, the node will remain **locked**. - - To resume using the node: - - Click the **"Unlock"** button displayed on the node page. - - After unlocking, the node will be fully operational and updated to the latest version. + + ![Image](/images/image-6.png) + + + + + - Navigate to the node page where the notification block appears. + - Click the **"Update"** button to trigger the upgrade process. + - This action initiates the upgrade to the latest RLN image version. + + + - The upgrade process may take a few minutes. + - During this time, the node will be **locked**. + + + - Once the upgrade is complete, the node will remain **locked**. + - To resume using the node: + - Click the **"Unlock"** button displayed on the node page. + - After unlocking, the node will be fully operational and updated to the latest version. + + ## Automatic Bulk Upgrade (Scale or Wallet Plan Feature) @@ -52,28 +59,45 @@ After the automatic upgrade, all upgraded nodes will be locked. To continue usin This section explains how to upgrade RLN nodes programmatically using API endpoints. Follow the steps below to check, trigger, and finalize an upgrade. -1. **Check the Latest RLN Image** - **Endpoint** - ```text - GET /api/nodes/latest-rln-image - ``` - **Description** - Fetch the latest version of the RLN node image available for upgrade. - **Action** - Compare your node's current `rln_commit_id` with the data in the response. If the values differ, an upgrade is required. -2. **Trigger the Node Upgrade** - **Endpoint** - ```text - POST /api/nodes/{id}/upgrade - ``` - **Description** - Trigger an upgrade for a specific node to the latest version. - **Action** - Initiate the upgrade process for the specified node. -3. **Unlock the Node After Upgrade** - **Endpoint** - ```text - POST https://node-api.thunderstack.org/${userId}/${nodeId}/unlock - ``` - **Description** - After the upgrade is complete, nodes remain locked. Unlock the node to continue using it. \ No newline at end of file + + + **Endpoint** + + ```text + GET /api/nodes/latest-rln-image + ``` + + **Description** + + Fetch the latest version of the RLN node image available for upgrade. + + **Action** + + - Compare your node's current `rln_commit_id` with the `data` in the response. + - If the values differ, an **upgrade is required**. + + + **Endpoint** + + ```text + POST /api/nodes/{id}/upgrade + ``` + + **Description** + + Trigger an upgrade for a specific node to the latest version. + + **Action** + + Initiate the upgrade process for the specified node. + + + **Endpoint** + + ```text + POST https://node-api.thunderstack.org/${userId}/${nodeId}/unlock + ``` + + **Description** After the upgrade is complete, nodes remain **locked**. Unlock the node to continue using it. + + \ No newline at end of file diff --git a/cloud/webhooks.mdx b/cloud/webhooks.mdx index ef3d432..579fd97 100644 --- a/cloud/webhooks.mdx +++ b/cloud/webhooks.mdx @@ -15,22 +15,39 @@ You can add a webhook endpoint to your node by editing the node's settings: ## Adding a Webhook When Creating a Node -When creating a new node via the API, you can provide a Webhook URL in the settings. +When creating a new node via the API, you can provide a Webhook URL in the settings. This allows to send webhook notifications to your specified endpoint. You can update this URL later through the node's settings if needed. ## Retrieve the Public Key -To verify webhook requests, retrieve the public key from: https://cloud-api.thunderstack.org/api/webhook-public-key +To verify webhook requests, retrieve the public key from: [https://cloud-api.thunderstack.org/api/webhook-public-key](https://cloud-api.thunderstack.org/api/webhook-public-key) This public key is used to validate the `X-ThunderStack-Signature` header included in each webhook event. ## How Webhooks Work -When an event is triggered, ThunderStack sends a POST request to your webhook endpoint including a JSON payload and a header named `X-ThunderStack-Signature`. +When an event is triggered, ThunderStack sends a POST request to your webhook endpoint. The request includes: + +1. A **JSON payload** with details about the event. +2. A header named `X-ThunderStack-Signature` containing a digital signature created with ThunderStack's private key. ## Verification Steps 1. **Validate the Signature**: Use the public key to verify the `X-ThunderStack-Signature` header. -2. **Validate the Payload**: Ensure the `nodeId` in the payload matches the expected node. +2. **Validate the Payload**: Ensure the `nodeId` in the payload matches the expected node or endpoint. + +**Payload Schema** The JSON payload sent to your webhook endpoint has the following structure: + +```json copy +{ + "eventType": "NODE_STATUS_UPDATED", + "eventTimestamp": "2026-04-16T12:00:00Z", + "details": { + "nodeId": "your-node-id", + "status": "RUNNING" + }, + "nodeId": "your-node-id" +} +``` ## Status Values @@ -42,6 +59,48 @@ When an event is triggered, ThunderStack sends a POST request to your webhook en ## Security Considerations -1. **Use HTTPS**: Always use HTTPS for your webhook endpoint. +1. **Use HTTPS**: Always use HTTPS for your webhook endpoint to ensure data security during transit. 2. **Signature Verification**: Validate the `X-ThunderStack-Signature` header using the public key. -3. **Payload Validation**: Ensure the `nodeId` field matches the expected node. \ No newline at end of file +3. **Payload Validation**: Ensure the `nodeId` field matches the expected node. + +This ensures secure, reliable, and real-time notifications for your nodes. + +**Example Webhook Handler** + +Here’s an example of a webhook handler in JavaScript/TypeScript: + +```javascript copy +import * as crypto from 'crypto'; + +// Main function to handle webhook events +export async function handleWebhookEvent(request) { + // Extract the signature and body + const receivedSignature = request.headers['x-thunderstack-signature'] || request.headers['X-ThunderStack-Signature']; + const body = typeof request.body === 'string' ? request.body : JSON.stringify(request.body); + + // Retrieve the public key for signature verification + const publicKey = 'YOUR_PUBLIC_KEY_HERE'; + + // Create a verifier to validate the signature using the public key + const verify = crypto.createVerify('RSA-SHA256'); + verify.update(body); + verify.end(); + + // Validate the signature + const isValid = verify.verify(publicKey, receivedSignature, 'base64'); + if (!isValid) { + console.error('Invalid signature'); + return { + statusCode: 403, + body: JSON.stringify({ message: 'Forbidden - Invalid Signature' }) + }; + } + + // Handle the validated webhook event here + console.log('Valid webhook event received'); + return { + statusCode: 200, + body: JSON.stringify({ message: 'Webhook event processed successfully' }) + }; +} +``` \ No newline at end of file diff --git a/docs.json b/docs.json index 4ef1de8..5faa096 100644 --- a/docs.json +++ b/docs.json @@ -11,11 +11,16 @@ "groups": [ { "group": "What Utexo Is", - "pages": ["what-utexo-is"] + "pages": [ + "what-utexo-is" + ] }, { "group": "Getting Started", - "pages": ["getting-started/the-problem", "getting-started/architecture"] + "pages": [ + "getting-started/the-problem", + "getting-started/architecture" + ] }, { "group": "Product Suite", @@ -23,7 +28,10 @@ "getting-started/product-suite", { "group": "SDK", - "pages": ["product-suite/sdk", "sdk/utexo-sdk"] + "pages": [ + "product-suite/sdk", + "sdk/utexo-sdk" + ] }, { "group": "Cloud", @@ -50,11 +58,15 @@ }, { "group": "Security", - "pages": ["security/rln-remote-signer"] + "pages": [ + "security/security", + "security/rln-remote-signer" + ] }, { "group": "Access Token Authorization", "pages": [ + "access-token-authorization/access-token-authorization", "access-token-authorization/create-api-token", "access-token-authorization/cloud-api" ] @@ -63,7 +75,10 @@ }, { "group": "Bridge", - "pages": ["product-suite/bridge", "bridge/getting-started"] + "pages": [ + "product-suite/bridge", + "bridge/getting-started" + ] }, { "group": "Swap", @@ -79,14 +94,17 @@ "swap/get-btc" ] }, - "swap/getting-started-btc" + "swap/swap-btc-to-rgb", + "swap/swap-rgb-to-btc" ] } ] }, { "group": "Business Applications", - "pages": ["business-applications"] + "pages": [ + "business-applications" + ] } ] } diff --git a/images/image-1.png b/images/image-1.png new file mode 100644 index 0000000..142069d Binary files /dev/null and b/images/image-1.png differ diff --git a/images/image-10.png b/images/image-10.png new file mode 100644 index 0000000..509a72c Binary files /dev/null and b/images/image-10.png differ diff --git a/images/image-11.png b/images/image-11.png new file mode 100644 index 0000000..509a72c Binary files /dev/null and b/images/image-11.png differ diff --git a/images/image-12.png b/images/image-12.png new file mode 100644 index 0000000..c42dd5b Binary files /dev/null and b/images/image-12.png differ diff --git a/images/image-13.png b/images/image-13.png new file mode 100644 index 0000000..c42dd5b Binary files /dev/null and b/images/image-13.png differ diff --git a/images/image-14.png b/images/image-14.png new file mode 100644 index 0000000..c42dd5b Binary files /dev/null and b/images/image-14.png differ diff --git a/images/image-15.png b/images/image-15.png new file mode 100644 index 0000000..7b67a0f Binary files /dev/null and b/images/image-15.png differ diff --git a/images/image-16.png b/images/image-16.png new file mode 100644 index 0000000..7b67a0f Binary files /dev/null and b/images/image-16.png differ diff --git a/images/image-17.png b/images/image-17.png new file mode 100644 index 0000000..efd3ce1 Binary files /dev/null and b/images/image-17.png differ diff --git a/images/image-18.png b/images/image-18.png new file mode 100644 index 0000000..a34cb8f Binary files /dev/null and b/images/image-18.png differ diff --git a/images/image-19.png b/images/image-19.png new file mode 100644 index 0000000..a34cb8f Binary files /dev/null and b/images/image-19.png differ diff --git a/images/image-2.png b/images/image-2.png new file mode 100644 index 0000000..142069d Binary files /dev/null and b/images/image-2.png differ diff --git a/images/image-20.png b/images/image-20.png new file mode 100644 index 0000000..89d7ed8 Binary files /dev/null and b/images/image-20.png differ diff --git a/images/image-21.png b/images/image-21.png new file mode 100644 index 0000000..a34cb8f Binary files /dev/null and b/images/image-21.png differ diff --git a/images/image-22.png b/images/image-22.png new file mode 100644 index 0000000..56ad17c Binary files /dev/null and b/images/image-22.png differ diff --git a/images/image-23.png b/images/image-23.png new file mode 100644 index 0000000..e7c0fd8 Binary files /dev/null and b/images/image-23.png differ diff --git a/images/image-24.png b/images/image-24.png new file mode 100644 index 0000000..6f2e868 Binary files /dev/null and b/images/image-24.png differ diff --git a/images/image-25.png b/images/image-25.png new file mode 100644 index 0000000..fd66beb Binary files /dev/null and b/images/image-25.png differ diff --git a/images/image-26.png b/images/image-26.png new file mode 100644 index 0000000..fd66beb Binary files /dev/null and b/images/image-26.png differ diff --git a/images/image-27.png b/images/image-27.png new file mode 100644 index 0000000..751192e Binary files /dev/null and b/images/image-27.png differ diff --git a/images/image-28.png b/images/image-28.png new file mode 100644 index 0000000..f0e2259 Binary files /dev/null and b/images/image-28.png differ diff --git a/images/image-29.png b/images/image-29.png new file mode 100644 index 0000000..577d4dc Binary files /dev/null and b/images/image-29.png differ diff --git a/images/image-3.png b/images/image-3.png new file mode 100644 index 0000000..8a69f10 Binary files /dev/null and b/images/image-3.png differ diff --git a/images/image-30.png b/images/image-30.png new file mode 100644 index 0000000..800e2d1 Binary files /dev/null and b/images/image-30.png differ diff --git a/images/image-31.png b/images/image-31.png new file mode 100644 index 0000000..8b31df5 Binary files /dev/null and b/images/image-31.png differ diff --git a/images/image-32.png b/images/image-32.png new file mode 100644 index 0000000..8592a4d Binary files /dev/null and b/images/image-32.png differ diff --git a/images/image-33.png b/images/image-33.png new file mode 100644 index 0000000..8537c26 Binary files /dev/null and b/images/image-33.png differ diff --git a/images/image-34.png b/images/image-34.png new file mode 100644 index 0000000..bab48c7 Binary files /dev/null and b/images/image-34.png differ diff --git a/images/image-4.png b/images/image-4.png new file mode 100644 index 0000000..80e1745 Binary files /dev/null and b/images/image-4.png differ diff --git a/images/image-5.png b/images/image-5.png new file mode 100644 index 0000000..a01b6b5 Binary files /dev/null and b/images/image-5.png differ diff --git a/images/image-6.png b/images/image-6.png new file mode 100644 index 0000000..a01b6b5 Binary files /dev/null and b/images/image-6.png differ diff --git a/images/image-7.png b/images/image-7.png new file mode 100644 index 0000000..69e95de Binary files /dev/null and b/images/image-7.png differ diff --git a/images/image-8.png b/images/image-8.png new file mode 100644 index 0000000..219e80c Binary files /dev/null and b/images/image-8.png differ diff --git a/images/image-9.png b/images/image-9.png new file mode 100644 index 0000000..509a72c Binary files /dev/null and b/images/image-9.png differ diff --git a/images/image.png b/images/image.png new file mode 100644 index 0000000..0f6d2dc Binary files /dev/null and b/images/image.png differ diff --git a/product-suite/cloud.mdx b/product-suite/cloud.mdx index 18d35a5..d4edc44 100644 --- a/product-suite/cloud.mdx +++ b/product-suite/cloud.mdx @@ -1,7 +1,6 @@ --- -title: Cloud +title: "Overview" --- -Overview Utexo Cloud Modules offers managed execution infrastructure for applications that require direct control over node-level components. @@ -19,4 +18,4 @@ controlled access and permissions versioned deployments -Website: https://cloud.utexo.com +Website: [https://cloud.utexo.com](https://cloud.utexo.com) \ No newline at end of file diff --git a/sdk/utexo-sdk.mdx b/sdk/utexo-sdk.mdx index fc02f27..2658017 100644 --- a/sdk/utexo-sdk.mdx +++ b/sdk/utexo-sdk.mdx @@ -27,6 +27,7 @@ The primary wallet class is **UTEXOWallet**: initialize with a mnemonic (or seed - `getAddress()` — Get deposit address (async) - `getBtcBalance()` — Get on-chain BTC balance (async) - `getXpub()` — Get vanilla and colored xpubs +- `getNetwork()`— Get current network - `listUnspents()` — List unspent UTXOs - `listAssets()` — List RGB assets held - `getAssetBalance(assetId)` — Get balance for a specific asset diff --git a/security/rln-remote-signer.mdx b/security/rln-remote-signer.mdx index 58e6025..90acd44 100644 --- a/security/rln-remote-signer.mdx +++ b/security/rln-remote-signer.mdx @@ -2,36 +2,59 @@ title: "RLN Remote Signer" --- -Validating Lightning Signer (VLS) is an open-source Rust library for secure, self-custodial Lightning signers. Unlike hot wallets or blind signers, VLS keeps your private keys off the node and validates each signing request, ensuring only legitimate channel operations are approved. +Validating Lightning Signer (VLS) is an open-source **Rust library for secure, self-custodial Lightning signers**. Unlike hot wallets or blind signers, VLS keeps your private keys off the node **and** validates each signing request, ensuring only legitimate channel operations are approved. In other words, even if your Lightning node were compromised, funds remain safe thanks to the signer’s rigorous policy checks. ## System Overview VLS splits Lightning key management into two primary components: -### Lightning Node - -Runs the usual LN logic: channel opening, routing, HTLC management. No private keys for signing are stored here. - -### Remote Validating Signer - -Stores private keys in a secure environment and validates each request before generating a signature. If the request fails policy checks, it denies signing. + + + Runs the usual LN logic: channel opening, routing, HTLC management, etc. But **no** private keys for signing are stored here. + + + Stores private keys in a secure environment and **validates** each request (e.g., channel updates, HTLC commitments) before generating a signature. If the request fails policy checks, it denies signing. + + ### Additional Components -- Policy Engine: A customizable set of rules ensuring no suspicious requests are signed. -- UTXO Oracle (Optional): The signer can be configured to receive chain data to detect remote breaches. -- State Storage: Provides secure, redundant cloud storage with anti-rollback protection. +- **Policy Engine**: A customizable set of rules ensuring no suspicious or off-protocol requests are signed. +- **UTXO Oracle (Optional)**: The signer can be configured to receive chain data to detect remote breaches or track on-chain states (e.g., unconfirmed inputs, HTLC expiries). +- **State Storage**: Provides secure, redundant cloud storage for Lightning nodes and signers with anti-rollback protection. ## Architecture Overview -### Validation Flow - -1. Node proposes a transaction or state update. -2. VLS checks protocol correctness and local policy. -3. If valid, the signer returns a signature. Otherwise, it rejects the request. +Below is a simplified technical breakdown of how VLS integrates with Lightning nodes: + + + + - **RGB LN Node** + + + 1. **Node** proposes a transaction or state update. + 2. **VLS** checks protocol correctness and local policy (e.g., channel open, HTLC amounts, no double revoke). + 3. **If valid**, the signer returns a signature. Otherwise, it rejects the request. + + + - VLS can run in a dedicated hardware security module (HSM), a secure enclave, or simply as a separate process/container. + - For extremely large LN balances, hardware isolation is recommended. + + + - Rust ensures efficient, safe concurrency. + - The overhead for real-time transaction signing is minimal compared to typical LN operations. + + ## Current Status -Support for a remote signer in the RGB Lightning Node is currently under active development. At this stage, remote signer support is not yet available in production and should be considered experimental. +Support for a **remote signer** in the RGB Lightning Node is currently **under active development**. + +The goal of this feature is to allow Lightning and RGB operations to be executed while keeping private keys **outside** of the RGB Lightning Node process. This enables stronger security models such as: + +- hardware-backed signing +- isolated signing services +- custodial or enterprise-grade deployments +- integration with external signing infrastructure -Progress is tracked publicly at: https://github.com/RGB-Tools/rgb-lightning-node/issues/43 \ No newline at end of file +At this stage, remote signer support is not yet available in production and should be considered experimental. Progress is tracked publicly at: [https://github.com/RGB-Tools/rgb-lightning-node/issues/43](https://github.com/RGB-Tools/rgb-lightning-node/issues/43) \ No newline at end of file diff --git a/security/security.mdx b/security/security.mdx new file mode 100644 index 0000000..2c791fa --- /dev/null +++ b/security/security.mdx @@ -0,0 +1,39 @@ +--- +title: "Security" +--- + +Authorization Methods in Utexo Cloud + +We prioritize the security of your interactions with nodes hosted on AWS through Cloud. To ensure robust protection, we provide two advanced methods of authorization for secure communication: **Cognito Authorization** and **mTLS Authorization**. These methods meet stringent security standards, safeguarding both user interactions via our interface + +**1. Cognito Authorization** + +**Cognito Authorization** is designed for users interacting with nodes through the **Cloud UI**. It ensures secure access and streamlined authentication for HTTPS requests. + +- **Key Features**: + - Leverages **Amazon Cognito** to manage user identities. + - Handles **authentication** and **token issuance** securely. + - Allows users to perform authorized actions seamlessly via the Cloud user interface. +- **Use Case**: Ideal for users accessing nodes through the Cloud UI for day-to-day operations and HTTPS API requests. +- **Benefits**: + - Centralized identity management. + - Automated token handling for improved user experience. + - Secure interaction with Cloud nodes. + +**2. mTLS Authorization** + +**mTLS Authorization** (Mutual TLS) is tailored for developers and advanced users who need to interact with nodes directly, such as through custom applications or third-party clients. + +- **How it Works**: + - Both the client and server authenticate each other using **TLS certificates**. + - Clients must present a **valid certificate** issued by a trusted Certificate Authority (CA). + - Enforced via **AWS API Gateway** to ensure secure communications. +- **Key Features**: + - **Mutual Authentication**: Verifies the identity of both parties in the communication. + - **Certificate Management**: Requires proper configuration of client certificates for secure API access. + - Supports direct, high-security API interactions. +- **Use Case**: Ideal for developers and applications requiring secure, direct communication with nodes outside of the Cloud UI. +- **Benefits**: + - Maximum security for API interactions. + - Flexibility for integrating Cloud with custom-built solutions. + - Trust-based access via Certificate Authority validation. \ No newline at end of file diff --git a/swap/getting-started-btc.mdx b/swap/getting-started-btc.mdx deleted file mode 100644 index 7081847..0000000 --- a/swap/getting-started-btc.mdx +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: "Getting Started Btc" ---- - -# Getting Started - -## How BTC → RGB Transfers Work - -When transferring BTC from the Bitcoin network to RGB, you send BTC to a Utexo-generated deposit address and receive an equivalent BTC-backed asset on RGB. You approve the BTC send in your Bitcoin wallet, and you use an RGB invoice to specify the recipient on the RGB side. - -### Requirements before you start - -- Tribe Wallet (mobile app) - -### Step 1: Enter the transfer details - -In **You send**, enter the amount of RGB tokens to receive. Click **Swap**. - -In Tribe Wallet: - -- Open **Other assets** (Step 3). -- Tap the **\+** icon (Step 4). -- Tap **Receive Asset** (Step 5). -- Generate an invoice (Step 6). -- Select a blinded invoice, then copy it. -- Paste the invoice into the RGB invoice field in Utexo (Step 8). -- Copy the BTC payment address (Step 9). - -### Step 2: Pay BTC to receive RGB - -In your BTC wallet, scan the QR code or paste the recipient address. If you scan the QR code, the amount is filled in automatically. Paste the payment address (Step 10), then **Swipe to broadcast** (Step 11). - -### Step 3: Check transaction status in Tribe Wallet - -After you send BTC, the transaction appears as **In progress**. Refresh to see status updates until it completes. - -## How RGB → BTC Transfers Work - -When transferring RGB tokens to BTC, set **You send** to the RGB token (for example, SatoshiRamen) and **You receive** to Bitcoin. Enter the amount, click Swap, then copy a BTC address from your wallet and paste it into Utexo. - -### Step 1: Enter the transfer details - -Set **You send** to the RGB token. Set **You receive** to Bitcoin. Enter the amount of RGB tokens to send and click **Swap**. Copy a BTC address from your wallet, then paste it into Utexo. Review the preview details including the estimated BTC amount after fees. Click **Confirm**. - -### Step 2: Pay the RGB invoice - -When Utexo shows the RGB invoice (QR code popup), open Tribe Wallet. Select the token you are sending (for example, SatoshiRamen). Tap **Send**, then scan the QR code from the Utexo popup. Confirm the pre-filled amount and invoice details. **Swipe to send**. - -### Step 3: Check transaction status in Tribe Wallet - -After you send, the transaction appears with a status label. Refresh to see updates. \ No newline at end of file diff --git a/swap/swap-btc-to-rgb.mdx b/swap/swap-btc-to-rgb.mdx new file mode 100644 index 0000000..3282e5f --- /dev/null +++ b/swap/swap-btc-to-rgb.mdx @@ -0,0 +1,81 @@ +--- +title: 'Swap BTC to RGB' +description: 'Transfer BTC from the Bitcoin network to the RGB protocol using Utexo Swap.' +--- + +## Overview + +This guide walks you through transferring native BTC from the Bitcoin network to a BTC-backed asset on the RGB protocol using Utexo Swap. The process is trustless and non-custodial — you retain full control of your keys throughout. + + + This flow moves BTC **into** the RGB layer. To move RGB assets back to Bitcoin, see [Swap RGB to BTC](/swap/swap-rgb-to-btc). + + +## How it works + +When you initiate a BTC → RGB swap: + +1. Utexo generates a deposit address on the Bitcoin network. +2. You send BTC to that address from your Bitcoin wallet. +3. An equivalent BTC-backed asset is issued on RGB and delivered to your specified RGB invoice address. + +The RGB invoice is generated inside Tribe Wallet and acts as the recipient identifier for the RGB-side delivery. + +## Requirements + +Before you start, make sure you have: + +- **Tribe Wallet** (mobile app) — installed and set up with an RGB-compatible wallet +- **BTC in a Bitcoin wallet** — any standard Bitcoin wallet that can send to an external address + +## Step 1: Generate an RGB invoice in Tribe Wallet + +The RGB invoice tells Utexo where to deliver the BTC-backed RGB asset. + +1. Open Tribe Wallet. +2. Tap **Other assets**. +3. Tap the **+** icon. +4. Select **Receive Asset**. +5. Choose **Blinded invoice**. +6. Copy the generated invoice. + + + RGB invoices are single-use. Generate a new invoice for each swap. + + +## Step 2: Initiate the swap in Utexo + +1. Go to [Utexo Swap](https://utexo.io/swap). +2. In the **You send** field, enter the amount of BTC you want to transfer. +3. Click **Swap**. +4. Paste the RGB invoice you copied from Tribe Wallet into the **RGB invoice** field. +5. A Bitcoin deposit address is displayed. Copy it. + +## Step 3: Send BTC from your Bitcoin wallet + +1. Open your Bitcoin wallet. +2. Initiate a send to the deposit address provided by Utexo. +3. Confirm and broadcast the transaction. + + + Transaction confirmation times depend on Bitcoin network congestion and the fee rate you set. Utexo credits the RGB asset after the required number of confirmations. + + +## Step 4: Verify receipt in Tribe Wallet + +1. Return to Tribe Wallet. +2. Open **Other assets** to confirm the BTC-backed RGB asset has been received. + +## Troubleshooting + + + + Check the confirmation count for your Bitcoin transaction. The asset is credited only after the required confirmations. If the transaction has confirmed and the asset hasn't appeared after 30 minutes, contact Utexo support. + + + Ensure you are using a blinded invoice from Tribe Wallet, not a standard Bitcoin address. RGB invoices are protocol-specific and are not interchangeable with Bitcoin addresses. + + + Deposit addresses are time-limited. If your address has expired, start a new swap to generate a fresh address. + + \ No newline at end of file diff --git a/swap/swap-rgb-to-btc.mdx b/swap/swap-rgb-to-btc.mdx new file mode 100644 index 0000000..6bd2540 --- /dev/null +++ b/swap/swap-rgb-to-btc.mdx @@ -0,0 +1,72 @@ +--- +title: 'Swap RGB to BTC' +description: 'Transfer a BTC-backed RGB asset back to native BTC on the Bitcoin network using Utexo Swap.' +--- + +## Overview + +This guide explains how to redeem a BTC-backed RGB asset and receive native BTC on the Bitcoin network. The process is trustless and non-custodial — you send the RGB asset from Tribe Wallet and receive BTC directly to your Bitcoin address. + + + This flow moves assets **out of** the RGB layer back to Bitcoin. To move BTC into RGB, see [Swap BTC to RGB](/swap/swap-btc-to-rgb). + + +## How it works + +When you initiate an RGB → BTC swap: + +1. Utexo generates an RGB invoice for you to pay from Tribe Wallet. +2. You send the BTC-backed RGB asset to that invoice. +3. Utexo releases an equivalent amount of native BTC to your specified Bitcoin address. + +The Bitcoin address is provided by you and is where the released BTC will be sent. + +## Requirements + +Before you start, make sure you have: + +- **Tribe Wallet** (mobile app) — with a BTC-backed RGB asset balance +- **A Bitcoin receive address** — any standard Bitcoin wallet address where you want to receive the BTC + +## Step 1: Initiate the swap in Utexo + +1. Go to [Utexo Swap](https://utexo.io/swap). +2. In the **You receive** field, select BTC and enter the amount. +3. Enter your **Bitcoin receive address** in the destination field. +4. Click **Swap**. +5. Utexo displays an RGB invoice. Copy it. + +## Step 2: Send the RGB asset from Tribe Wallet + +1. Open Tribe Wallet. +2. Navigate to **Other assets** and select the BTC-backed RGB asset. +3. Tap **Send**. +4. Paste the RGB invoice copied from Utexo into the recipient field. +5. Confirm the amount and tap **Send**. + + + Double-check the RGB invoice before sending. RGB transactions are irreversible once broadcast. + + +## Step 3: Verify BTC receipt + +1. Check your Bitcoin wallet for the incoming transaction. +2. BTC will appear after the required network confirmations. + + + Settlement time depends on Bitcoin network congestion and your Utexo swap processing time. If BTC has not arrived after 60 minutes, contact Utexo support. + + +## Troubleshooting + + + + Verify the transaction is confirmed in Tribe Wallet. If confirmed, check your Bitcoin wallet for a pending incoming transaction. Processing may take additional time depending on network conditions. Contact Utexo support if BTC has not arrived after 60 minutes. + + + Ensure the RGB invoice is still valid (invoices expire after a set time). If expired, return to Utexo Swap and generate a new swap to get a fresh RGB invoice. + + + Network fees are deducted from the swap amount. Review the fee breakdown shown in Utexo Swap before confirming. + + \ No newline at end of file