Skip to content

Commit 1e9cba0

Browse files
glasgowm148glasgowm148
committed
babel fixes
1 parent 31ceec6 commit 1e9cba0

File tree

2 files changed

+116
-88
lines changed

2 files changed

+116
-88
lines changed

‎docs/dev/protocol/tx/babel-fleet.md

+115-87
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,64 @@
11
# Babel Fees Plugin Documentation
22

3-
The **Babel Fees Plugin** is a Fleet SDK extension that lets users pay transaction fees with tokens instead of ERG. This approach proves useful for users who start with empty wallets. It facilitates token-to-ERG swaps for fee payments. The plugin includes functions that create Babel Fee contracts, validate Babel Boxes, and manage contract states. It plugs into Fleet SDK's transaction framework, which makes it possible to build complex transactions that do not require a native ERG balance for fee payment.
3+
The Babel Fees Plugin is a specialized extension for the Fleet SDK designed to simplify the process of using Babel Fees within Ergo transactions. Babel Fees is a mechanism that allows users to pay transaction fees with tokens instead of ERG, particularly beneficial for those with limited or no ERG balances. The plugin automates the complex process of token-to-ERG conversion necessary for utilizing Babel Fees. It integrates seamlessly into the Fleet SDK’s transaction framework, enabling developers to build sophisticated transactions that don't require users to have a native ERG balance for transaction fee payments.
4+
5+
## What are Babel Fees?
6+
7+
At its core, [Babel Fees](babel-fees.md) is an Ergo protocol feature that enables users to pay transaction fees using a variety of tokens, rather than being restricted to using ERG. This is done by leveraging smart contracts which act as liquidity sources (called “Babel Boxes”) for token-to-ERG swaps. These contracts are set up by others who wish to provide this liquidity to users.
8+
9+
Babel Fees offer key benefits:
10+
11+
- **Accessibility**: Allows users with limited or no ERG to interact with the Ergo network.
12+
- **Flexibility**: Users can choose which tokens they want to use for paying fees.
13+
- **Onboarding**: Makes it easier for new users to join the ecosystem.
414

515
---
616

7-
### Key Features
17+
## Key Features
818

9-
1. **Token-Based Fee Payment**:
1019

11-
- Enables users to pay fees with tokens.
12-
- Automates token-to-ERG swaps.
1320

14-
2. **Validation Utilities**:
21+
- Transaction Extension:
1522

16-
- Validate Babel Boxes and their associated contracts.
17-
- Check contract parameters and fields to ensure correct configurations.
23+
- Provides a BabelSwapPlugin that seamlessly integrates with Fleet SDK's TransactionBuilder.
24+
- Modifies transaction inputs and outputs to incorporate Babel Fee logic.
1825

19-
3. **Customizable Contracts**:
26+
- Babel Box Validation:
2027

21-
- Developers define token prices and liquidity for Babel Boxes.
22-
- Contracts adjust their parameters based on a specific token ID.
28+
- Offers utilities to validate the structure and parameters of Babel Boxes.
29+
- Ensures compliance with the Babel Fees protocol.
2330

24-
4. **Optimized for Modern Development**:
31+
- Contract Script Generation:
2532

26-
- Supports both ESM and CommonJS modules.
27-
- Offers tree-shaking for reduced bundle size.
33+
- Includes functions for building and verifying Babel Fee contract scripts (ErgoTree).
2834

35+
- Developer-Friendly:
36+
37+
- Supports ESM and CommonJS modules.
38+
- Tree-shakeable design for smaller bundle sizes.
2939
---
3040

31-
### Installation
41+
## Installation
3242

33-
Install the Babel Fees Plugin with npm:
43+
To install the plugin, use the following commands in your project:
3444

3545
```bash
3646
npm install @fleet-sdk/babel-fees-plugin
3747
```
3848

39-
The Babel Fees Plugin requires Fleet SDK Core:
40-
49+
The core Fleet SDK is also required:
4150
```bash
4251
npm install @fleet-sdk/core
4352
```
4453

45-
This plugin requires Node.js 18 or newer.
54+
**System Requirements**: Node.js version 18 or newer.
4655

4756
---
4857

49-
### Usage Example
58+
## Usage Example: Add Babel Fees to a Transaction
5059

51-
#### Add Babel Fees to a Transaction
60+
This example demonstrates how to pay for transaction fees using tokens with BabelSwapPlugin.
5261

53-
The code below constructs a transaction that pays its fees with tokens instead of ERG. It sets the current blockchain height, adds inputs, integrates Babel fee logic, requests minimum fees, assigns a change address, and builds the final transaction object. After the build step completes, the transaction object includes instructions that convert a defined amount of tokens into the necessary ERG fees.
5462

5563
```typescript
5664
import { TransactionBuilder } from '@fleet-sdk/core';
@@ -71,67 +79,87 @@ const tx = new TransactionBuilder(1000000) // Replace with current block height
7179
console.log(tx);
7280
```
7381

74-
This snippet demonstrates a transaction builder in action. The `BabelSwapPlugin` function takes a Babel Box and configuration parameters for token-to-ERG conversion. The plugin then attaches fee-paying logic to the transaction. When the transaction finalizes, the included Babel Box and token parameters ensure that any required ERG fees are sourced from the specified tokens.
75-
76-
---
77-
78-
### API Reference
79-
80-
#### Plugins
81-
82-
1. **`BabelSwapPlugin`**
83-
84-
- **Description**: Integrates Babel fee functionality into a transaction, converting tokens into ERG to meet fee requirements.
85-
- **Parameters**:
86-
87-
- `babelBox`: A valid Babel Fee box. A Babel Box contains tokens and ERG that a contract uses to set a token price.
88-
- `token`: An object that specifies the token ID and the token amount used to generate the necessary ERG fees.
89-
90-
- **Usage**:
82+
Explanation:
9183

92-
```typescript
93-
BabelSwapPlugin(babelBox, {
94-
tokenId: "03faf2cb329f2e90d6d23b58d91bbb6c046aa143261cc21f52fbe2824bfcbf04",
95-
amount: "50"
96-
});
97-
```
84+
- The code initializes a `TransactionBuilder` with the current block height.
85+
- `from(inputs)` includes input boxes for the transaction.
86+
- `extend(BabelSwapPlugin(...))` adds the BabelSwapPlugin to the transaction. The plugin takes a Babel Box, token ID, and the token amount to convert for ERG fees.
87+
- `payMinFee()` ensures the inclusion of minimum required network fees.
88+
- `sendChangeTo(...)` defines the address for remaining funds after fee conversion.
89+
- `build()` finalizes the transaction object.
9890

99-
This plugin modifies a transaction so that the transaction no longer requires a direct ERG payment for fees. It uses the Babel Box as a liquidity source to convert specified tokens into enough ERG to cover the fee.
91+
This example showcases how to use Babel Fees with the plugin without any direct ERG input from the user for transaction fees.
10092

101-
#### Utility Functions
102-
103-
1. **`getTokenPrice(babelBox: Box<Amount>): bigint`**
104-
105-
Returns the price of a single token unit in nanoERG. Developers use this function to understand how many nanoERG one token unit represents.
106-
107-
**Example**:
108-
109-
```typescript
110-
const price = getTokenPrice(babelBox);
111-
console.log(`Price per token: ${price}`);
112-
```
113-
114-
This code retrieves the token price from the Babel Box and logs it. Developers then know the rate at which tokens convert into ERG.
115-
116-
2. **`buildBabelContract(tokenId: string): string`**
117-
118-
Returns a Babel Fee ErgoTree for a given token ID. This function constructs the contract script that defines how tokens and ERG interact inside a Babel Box. Developers use this when they want to generate a Babel Box contract for a specific token.
119-
120-
3. **`isValidBabelBox(box: Box<Amount>): boolean`**
121-
122-
Returns a boolean that indicates whether a given box qualifies as a Babel Fee box. Developers use this to confirm that a discovered box meets all criteria for acting as a Babel Box.
123-
124-
4. **`extractTokenIdFromBabelContract(ergoTree: string): string`**
125-
126-
Extracts the token ID from a Babel Fee contract. Developers use this to confirm which token the Babel Box manages.
127-
128-
5. **`isBabelContractForTokenId(ergoTree: string, tokenId: string): boolean`**
129-
130-
Checks whether a Babel Fee contract matches a given token ID. This helps validate that the contract in use corresponds to the intended token.
93+
---
13194

95+
## **API Reference**
96+
97+
**Plugins**
98+
99+
1. **`BabelSwapPlugin(babelBox: Box<Amount>, token: { tokenId: string, amount: string }): TransactionExtension`**
100+
101+
* **Description**: Extends the transaction to incorporate Babel Fees by converting the provided token into ERG needed for fees.
102+
* **Parameters**:
103+
* `babelBox`: A valid Babel Box containing tokens and ERG for conversion.
104+
* `token`: An object containing:
105+
* `tokenId`: The ID of the token to be used for fee conversion.
106+
* `amount`: The amount of tokens to use for the fee payment.
107+
* **Usage**:
108+
```typescript
109+
BabelSwapPlugin(babelBox, {
110+
tokenId: "03faf2cb329f2e90d6d23b58d91bbb6c046aa143261cc21f52fbe2824bfcbf04",
111+
amount: "50"
112+
});
113+
```
114+
115+
## **Utility Functions**
116+
117+
1. **`getTokenPrice(babelBox: Box<Amount>): bigint`**
118+
119+
* **Description**: Calculates and returns the price of a single token unit in nanoERG based on a specific Babel Box.
120+
* **Example**:
121+
```typescript
122+
const price = getTokenPrice(babelBox);
123+
console.log(`Price per token: ${price}`);
124+
```
125+
126+
2. **`buildBabelContract(tokenId: string): string`**
127+
128+
* **Description**: Generates the ErgoTree (contract script) for a Babel Box using a specified token ID.
129+
* **Usage**:
130+
```typescript
131+
const contract = buildBabelContract(tokenId);
132+
```
133+
134+
3. **`isValidBabelBox(box: Box<Amount>): boolean`**
135+
136+
* **Description**: Determines if a given box is a valid Babel Box.
137+
* **Usage**:
138+
```typescript
139+
const isValid = isValidBabelBox(myBox);
140+
if (isValid) {
141+
console.log('This is a valid babel box');
142+
}
143+
```
144+
145+
4. **`extractTokenIdFromBabelContract(ergoTree: string): string`**
146+
147+
* **Description**: Extracts the token ID from a Babel Fee contract script (ErgoTree).
148+
* **Usage**:
149+
```typescript
150+
const tokenId = extractTokenIdFromBabelContract(ergoTree);
151+
```
152+
153+
5. **`isBabelContractForTokenId(ergoTree: string, tokenId: string): boolean`**
154+
155+
* **Description**: Validates if an ErgoTree matches the Babel Fee contract for a specific token ID.
156+
* **Usage**:
157+
```typescript
158+
const isForToken = isBabelContractForTokenId(ergoTree, tokenId);
159+
```
132160
---
133161

134-
### Box Discovery and Identification
162+
## Box Discovery and Identification
135163

136164
A Babel Box is a container that holds a specified token and associated ERG. This combination allows the plugin to determine the conversion rate between tokens and ERG. The plugin references the Babel Box when it performs token-to-ERG conversions.
137165

@@ -144,7 +172,7 @@ Replace `{tokenId}` with the target token ID. Use the resulting ErgoTree to disc
144172
145173
`https://api.ergoplatform.com/api/v1/boxes/unspent/byErgoTree/{ErgoTree}`
146174
147-
**Example Box Fetching:**
175+
**Example of Fetching a Babel Box:**
148176
149177
```typescript
150178
const fetchBabelBox = async (ergoTree: string) => {
@@ -163,15 +191,15 @@ This snippet uses the Ergo API to locate and return a Babel Box. Developers supp
163191

164192
---
165193

166-
### Step-by-Step
194+
## Step-by-Step
167195

168-
Read [this guide](http://147.182.244.219/ergobabelfees.html) for details on minting a token, creating a Babel Box, and using a web application to self-sign transactions with Babel Fees involved. The guide walks through each stage, which includes preparing a token, generating a Babel Box contract, and integrating the BabelSwapPlugin within a Fleet SDK transaction.
169196

197+
For a detailed guide on how to mint a token, set up a Babel Box, and utilize the plugin within a web application, refer to [this guide](http://147.182.244.219/ergobabelfees.html).
170198
---
171199

172-
### Development Insights
200+
## Development Insights
173201

174-
#### Key Updates from `CHANGELOG.md`
202+
### Key Updates from `CHANGELOG.md`
175203

176204
- **Validation Enhancements**:
177205

@@ -181,7 +209,7 @@ Read [this guide](http://147.182.244.219/ergobabelfees.html) for details on mint
181209

182210
- Adjusted the ESM and CommonJS exports in version `0.1.10` to prevent issues with package imports.
183211

184-
#### Package Metadata
212+
### Package Metadata
185213

186214
- **Version**: `0.1.18`
187215
- **Dependencies**:
@@ -196,9 +224,9 @@ Read [this guide](http://147.182.244.219/ergobabelfees.html) for details on mint
196224

197225
---
198226

199-
### Testing and Validation
227+
## Testing and Validation
200228

201-
#### Unit Testing Example
229+
### Unit Testing Example
202230

203231
The unit test below verifies that the `BabelSwapPlugin` integrates Babel fee logic into a transaction. It sets a mock Babel Box, builds a transaction that uses the plugin, and checks whether the resulting transaction includes the Babel Box as a source of fee liquidity.
204232

@@ -223,14 +251,14 @@ This test confirms the presence of the Babel Box in the transaction inputs. If i
223251

224252
---
225253

226-
### Reference Implementations
254+
## Reference Implementations
227255

228256
* [Implementing Ergo Babel Fees with Fleet-SDK - May 17, 2024](http://147.182.244.219/ergobabelfees.html)
229257
* [Nautilus Wallet implementation](https://github.com/capt-nemo429/nautilus-wallet/pull/82)
230258
* [AppKit implementation](https://github.com/ergoplatform/ergo-appkit/pull/204)
231259
* [Fleet SDK Babel fees plugin](https://fleet-sdk.github.io/docs/plugins/babel-fees)
232260

233-
### Additional Resources
261+
## Additional Resources
234262

235263
- **Fleet SDK Documentation**: [Fleet SDK Babel Fees Plugin](https://fleet-sdk.github.io/docs/plugins/babel-fees)
236264
- **Ergo Platform API**: [Ergo API Documentation](https://api.ergoplatform.com/api/v1/docs/)

‎docs/mining/setup/join.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ This guide will walk you through the process of starting to mine Ergo using [Aut
77
Before you start mining, make sure you have the following:
88

99
- Familiarity with Ergo. If you're new, start with [What is Ergo?](why.md)
10-
- A computer with at least one GPU that has more than 4GB of memory. Check the [Autolykos v2 hashrates spreadsheet](https://docs.google.com/spreadsheets/d/1NsuoDB27EwCo_BlSjCP3GMLfTSJRPIWIBsL-wPTllUg) for potential hashrates.
10+
- A computer with at least one GPU that has more than 6GB of memory. Check the [Autolykos v2 hashrates spreadsheet](https://docs.google.com/spreadsheets/d/1NsuoDB27EwCo_BlSjCP3GMLfTSJRPIWIBsL-wPTllUg) for potential hashrates.
1111
- If you're considering building a dedicated rig, refer to our guide on [Building a rig](rig.md).
1212

1313
## Steps to Start Mining

0 commit comments

Comments
 (0)