@mycelium-sdk/core 0.1.0 → 1.0.0-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/LICENSE +55 -0
  2. package/README.md +191 -50
  3. package/dist/index.cjs +704 -368
  4. package/dist/index.cjs.map +1 -1
  5. package/dist/index.d.cts +398 -303
  6. package/dist/index.d.ts +398 -303
  7. package/dist/index.js +704 -374
  8. package/dist/index.js.map +1 -1
  9. package/package.json +12 -12
package/LICENSE ADDED
@@ -0,0 +1,55 @@
1
+ # Mycelium SDK license
2
+
3
+ ## Overview
4
+
5
+ This project is dual-licensed under the **Apache License 2.0 (Non-Commercial use only)** and a separate **Commercial License**
6
+
7
+ - The **Apache License 2.0 (Non-Commercial)** applies to all **non-commercial** use
8
+ - A **Commercial License** is required for any **for-profit**, **enterprise**, or **SaaS** use
9
+
10
+ ## 1. Apache License 2.0 (Non-Commercial)
11
+
12
+ Copyright © 2025 MyceliumSDK
13
+ All rights reserved
14
+
15
+ Licensed under the Apache License, Version 2.0 (the "License");
16
+ you may not use this file except in compliance with the License and the **Non-Commercial Use Restriction** below
17
+
18
+ You may obtain a copy of the License at:
19
+
20
+ > https://www.apache.org/licenses/LICENSE-2.0
21
+
22
+ ### Additional non-commercial use restriction
23
+
24
+ Notwithstanding the terms of the Apache License 2.0,
25
+ **you may use, copy, modify, and distribute this software only for non-commercial purposes**
26
+
27
+ “Non-commercial” means use that:
28
+
29
+ - Does **not** generate revenue or commercial advantage (directly or indirectly)
30
+ - Is **not** used in a product or service offered for sale, rent, or subscription
31
+ - Is **not** used in a business or enterprise setting, except for internal research or testing
32
+
33
+ If you wish to use this software commercially, you must obtain a separate **Commercial License**
34
+
35
+ ## 2. Commercial License
36
+
37
+ For commercial use of Mycelium SDK, including but not limited to:
38
+
39
+ - Use in a commercial or for-profit product or service
40
+ - Integration into closed-source or proprietary software
41
+ - SaaS or hosted offerings built upon Mycelium SDK
42
+ - Use by a company, organization, or enterprise for business purposes
43
+
44
+ you must obtain a valid **Commercial License** from the copyright holder.
45
+
46
+ To inquire about a commercial license, please contact:
47
+
48
+ Email: license@mycelium.sh
49
+ Website: [https://mycelium.sh](https://mycelium.sh)
50
+
51
+ ## 3. No Warranty
52
+
53
+ This software is provided "as is", without warranty of any kind, express or implied, including but not limited to warranties of merchantability, fitness for a particular purpose, or noninfringement
54
+
55
+ In no event shall the authors or copyright holders be liable for any claim, damages, or other liability arising from, out of, or in connection with the software or its use
package/README.md CHANGED
@@ -2,48 +2,112 @@
2
2
 
3
3
  > Check documentation: https://docs.mycelium.sh
4
4
 
5
- A TypeScript-based SDK that implements access to yield opportunities in web3 using a Mycelium SDK. The SDK allows integrators to easily onboard users, manage wallets, and interact with DeFi protocols via a unified interface basic knowledge of web3
5
+ A TypeScript-based SDK that implements wallet management via ERC-4337 smart account and access to crypto yield opportunities though integrated protocols under the hood. The SDK allows integrators to easily onboard users, manage wallets, and interact with DeFi protocols
6
6
 
7
- ## Core features
7
+ # Core features
8
8
 
9
- The Mycelium SDK simplifies on-chain interactions by creating and managing embedded wallets based on user information (e.g., email). Each wallet is used as a smart account to sign blockchain transactions and perform operations across supported protocols.
9
+ The Mycelium SDK simplifies on-chain interactions by creating and managing a smart wallet with an embedded wallet as a signer for blockchain related operations. Smart wallet as well as embedded wallet signer are non-custodial and only a user has a direct access to it. The embedded wallet management is delegated to [the Privy platform](https://www.privy.io/)
10
10
 
11
- The SDK includes a Router Protocol, which selects the optimal farming protocol and vault based on parameters provided by the integrator (e.g., risk level, preferences, etc.). Once selected, the protocol is used internally by the SDK for subsequent user operations.
11
+ SDK has the following core features:
12
12
 
13
- ### Key capabilities
13
+ 1. Create a smart wallet with embedded OR external wallet as a signer
14
+ 2. Smart wallet core features: send/receive funds, sign transaction/message
15
+ 3. Fetch crypto yield opportunities
16
+ 4. Deposit or withdraw funds to/from a particular yield opportunity
17
+ 5. Fetch information about yield and balance for a specific opportunity where funds are
18
+ 6. Fund wallet via Coinbase: Generates a top-up link for the user to deposit funds
14
19
 
15
- - **Create wallet** — Initializes an embedded wallet tied to user data (like email)
16
- - **Fund wallet via Coinbase (soon)** — Generates a top-up link for the user to deposit funds
17
- - **Earn command** — Allocates deposited assets into a protocol or vault recommended by the SDK
18
- - **Withdraw** — Allows withdrawing part or all of the user's funds from the protocol
19
- - **Get balance** — Retrieves the balance and performance of assets held within protocols
20
- - **Router protocol** — Determines the best protocol and vault to use based on the integrator's strategy and risk preferences
20
+ An integrator can define basic settings for yield opportunities that will be recommended to a end user through SDK. More about this you can find on the `Protocol security config` section
21
21
 
22
- ## Requirements & installation
22
+ # Versions
23
23
 
24
- ### Prerequisites
24
+ Mycelium SDK is an open-source and publicly available to anyone for the usage. Despite this, there are 2 versions of Mycelium SDK that can be used by an integrator:
25
+
26
+ 1. **Self-hosted**
27
+ Clone the underlying repository, provide all necessary settings for providers that are used under the hood (Privy, Coinbase, etc). Right after this, you can use an integrated to a self hosted SDK version protocol - Spark. For more protocols, you need to switch to the cloud version
28
+ 2. **Cloud**
29
+ This version covers everything for an integrator. You just use the API key that will be provided to you and that's all. All settings and expenses for 3d party providers Mycelium SDK will take on it. For more information, check the `Cloud version` section
30
+
31
+ ## Self-hosted version
32
+
33
+ Self hosted version is available out of this repo and can be used by anyone by cloning the repo and settings up all necessary and required SDK parameters. Self hosted version has only one integrated protocol that can be used for yield opportunities recommendations - Spark. To start working with a self hosted SDK version, please refer to the `Get started` section
34
+
35
+ ## Cloud version
36
+
37
+ Cloud version is a paid (current free) version of the SDK, when everything is handled under the hood for an integrator. The only thing that you need to pass to the SDK during the initialization is an API key. All further 3d party platforms integrations will be handled under the hood by Mycelium. To start working with a self hosted SDK version, please refer to the `Get started` section
38
+
39
+ # Get started
40
+
41
+ Both cloud and self hosted version are required the following prerequisites:
25
42
 
26
43
  1. pnpm >= 10.9.0
27
44
  2. node >= 22.11.0
28
45
  3. TypeScript >= 5.0.0
29
46
 
47
+ ## Environment variables
48
+
49
+ Both self hosted and cloud version are required some variables to be provided during the initialization of an SDK. The list of envs for cloud version is significant, than for a self hosted one. Here is the full list of variables:
50
+
51
+ | Variable Name | Description | Version | Mandatory |
52
+ | ----------------------------- | -------------------------------------------------------------------------------------------------- | ------------------- | --------- |
53
+ | `PRIVY_APP_ID` | Privy wallet app id for embedded wallets | Self-hosted | Yes |
54
+ | `PRIVY_APP_SECRET` | Privy wallet app secret for embedded wallets | Self-hosted | Yes |
55
+ | `RPC_URL` | A RPC URL for a chain | Self-hosted | Yes |
56
+ | `BUNDLER_URL` | A bundler URL to process User Operations | Self-hosted | Yes |
57
+ | `COINBASE_CDP_API_KEY_ID` | Coinbase CDP Api Key ID for on/off ramp functionality | Self-hosted | No |
58
+ | `COINBASE_CDP_API_KEY_SECRET` | Coinbase CDP Api secret for on/off ramp functionality | Self-hosted | No |
59
+ | `INTEGRATOR_ID` | Unique integrator ID to track SDK usage and enable 3rd party services (e.g., Coinbase off/on-ramp) | Self-hosted | Yes |
60
+ | `API_KEY` | API key to run SDK with managed settings | Cloud | Yes |
61
+ | `PROTOCOL_RISK_LEVEL` | Risk level of protocol that will be used by an SDK in the configuration | Cloud & self-hosted | Yes |
62
+ | `CHAIN_ID` | Chain ID to work with | Cloud & self-hosted | Yes |
63
+
64
+ ## Self hosted
65
+
30
66
  ### Installation
31
67
 
32
- Install dependencies:
68
+ 1. Clone the repo:
33
69
 
34
70
  ```bash
35
- pnpm install
71
+ git clone https://github.com/MyceliumSDK/mycelium-sdk.git
72
+ ```
73
+
74
+ 2. Go to `package/sdk` and install dependencies:
75
+
76
+ ```bash
77
+ cd package/sdk && pnpm install
36
78
  ```
37
79
 
38
- Build the SDK:
80
+ 3. Build the SDK:
39
81
 
40
82
  ```bash
41
83
  pnpm run build
42
84
  ```
43
85
 
44
- The built SDK can then be used in your application or imported as a local library
86
+ > The built SDK can then be used in your application or imported as a local library
87
+
88
+ ### Testing
89
+
90
+ To test the SDK you can use the build in CLI from the same repository:
91
+
92
+ 1. Go to `packages/cli` and install dependencies
93
+
94
+ ```bash
95
+ cd packages/cli && pnpm install
96
+ ```
97
+
98
+ 2. Setup the CLI settings based on the README.md file
45
99
 
46
- ## Initialization Example
100
+ 3. Start the CLI
101
+
102
+ ```bash
103
+ pnpm run start
104
+ ```
105
+
106
+ > In case if you want to test the SDK with a fork, you need to use `anvil` and `packages/blockchain` service. Please refer to `packages/blockchain/README.md` for more details
107
+
108
+ ### SDK initialization
109
+
110
+ In case of a self hosted version, you need to define all your env variables. For more details, please refer the `Environment variables` section above. Right after you define all env variables, you can initiate the SDK:
47
111
 
48
112
  ```typescript
49
113
  this.sdk = new MyceliumSDK({
@@ -52,8 +116,8 @@ this.sdk = new MyceliumSDK({
52
116
  provider: {
53
117
  type: 'privy',
54
118
  providerConfig: {
55
- appId: process.env.NEXT_PUBLIC_PRIVY_APP_ID!,
56
- appSecret: process.env.NEXT_PUBLIC_PRIVY_APP_SECRET!,
119
+ appId: '...',
120
+ appSecret: '...',
57
121
  },
58
122
  },
59
123
  },
@@ -64,19 +128,116 @@ this.sdk = new MyceliumSDK({
64
128
  },
65
129
  },
66
130
  chain: {
67
- chainId: parseInt(process.env.NEXT_PUBLIC_CHAIN_ID!) as any,
68
- rpcUrl: process.env.NEXT_PUBLIC_RPC_URL!,
69
- bundlerUrl: process.env.NEXT_PUBLIC_BUNDLER_URL!,
131
+ chainId: '...',
132
+ rpcUrl: '...',
133
+ bundlerUrl: '...',
70
134
  },
71
135
  protocolsRouterConfig: {
72
- riskLevel: 'medium',
136
+ riskLevel: '...',
73
137
  },
138
+ coinbaseCDPConfig: {
139
+ apiKeyId: '...',
140
+ apiKeySecret: '...',
141
+ },
142
+ integratorId: '...',
74
143
  });
75
144
  ```
76
145
 
77
- > To get more information about what protocols and chains are available for SDK, refer to the `Protocol router` section below
146
+ ## Cloud version
147
+
148
+ If you decided to use a ready to use library, you need to receive an API key first. For this purpose, you can contact [Mike Krupin on Telegram](https://t.me/maikyman) or you can [send an email](emailto:myceliumsdk@gmail.com) to the Mycelium mailbox
149
+
150
+ Right after you would get an API key, you can start working with an SDK
151
+
152
+ ### Installation
153
+
154
+ 1. Install the library:
155
+
156
+ ```bash
157
+ pnpm install @mycelium-sdk/core
158
+ ```
159
+
160
+ 2. You're ready to use and SDK!
161
+
162
+ ### Testing
163
+
164
+ To test the SDK you can use the build in CLI from the repository:
78
165
 
79
- ## Local development
166
+ 1. Clone the repo:
167
+
168
+ ```bash
169
+ git clone https://github.com/MyceliumSDK/mycelium-sdk.git
170
+ ```
171
+
172
+ 2. Go to `packages/cli` and install dependencies
173
+
174
+ ```bash
175
+ cd packages/cli && pnpm install
176
+ ```
177
+
178
+ 3. Setup the CLI settings based on the README.md file
179
+
180
+ 4. Instal the latest SDK version:
181
+
182
+ ```bash
183
+ pnpm install @mycelium-sdk/core
184
+ ```
185
+
186
+ 5. Start the CLI
187
+
188
+ ```bash
189
+ pnpm run start
190
+ ```
191
+
192
+ > In case if you want to test the SDK with a fork, you need to use `anvil` and `packages/blockchain` service. Please refer to `packages/blockchain/README.md` for more details
193
+
194
+ ### SDK initialization
195
+
196
+ ```javascript
197
+ this.sdk = await MyceliumSDK.init({
198
+ apiKey,
199
+ chainId: '8453',
200
+ protocolsSecurityConfig: {
201
+ riskLevel: 'low',
202
+ },
203
+ });
204
+ ```
205
+
206
+ > To get more information about `protocolSecurityConfig` settings, please refer to the `Protocol security config` section below
207
+
208
+ # Protocol security config
209
+
210
+ Current config of settings used by `Protocol router` to define:
211
+
212
+ 1. What protocols will be used by SDK
213
+ 2. What savings vaults will be recommended by SDK
214
+
215
+ Currently, the following settings for the config are available:
216
+
217
+ - `riskLevel` define the risk level of a protocol that will be used by an integrator to recommend saving vaults
218
+ Risk level is determined by the general popularity and reputation of the protocol within the crypto industry. No independent risk assessment is performed by the SDK to determine the risk level
219
+
220
+ # Integrated protocols
221
+
222
+ Currently, the following list of protocols is integrated into SDK and can be used by user in self-hosted and cloud versions:
223
+
224
+ | Protocol | Chain | ChainId | Protocol risk level | Available on |
225
+ | --------------------------- | ----- | ------- | ------------------- | ------------------------ |
226
+ | [Spark](https://spark.fi/) | Base | 8453 | low | Self hosted version only |
227
+ | [Beefy](https://beefy.com/) | Base | 8453 | low | Cloud version only |
228
+
229
+ The protocol router mechanism of SDK select the best protocol based on your `protocolSecurityConfig` settings as well as on other provided settings. The only requirement from an integrator is to define a high-level settings for protocols, e.g. min APY, protocol risk level, etc
230
+
231
+ The SDK will use settings and find the best protocol and vault under the hood. No one, including integrator, will need to care about this part
232
+
233
+ More protocol and chains will be added soon
234
+
235
+ # Chain management
236
+
237
+ The chain configuration provided during SDK initialization defines where on-chain activities will take place. Currently, only one chain is supported for the `earn` functionality, with multi-chain support coming soon
238
+ The example configuration above uses Base chain (chain ID: 8453), meaning all protocol operations and vault deposits will occur on the Base network
239
+
240
+ # Local development
80
241
 
81
242
  Install dependencies:
82
243
 
@@ -102,7 +263,7 @@ Run tests in watch mode:
102
263
  pnpm run test:watch
103
264
  ```
104
265
 
105
- ## Documentation
266
+ # Documentation
106
267
 
107
268
  The SDK should be documented and described with [TypeDoc rules](https://typedoc.org/). To get more context, check [CONTRIBUTION.md](https://github.com/0xdeval/mycelium-sdk/blob/main/CONTRIBUTION.md)
108
269
 
@@ -116,30 +277,10 @@ pnpm run docs:public
116
277
  pnpm run docs:dev
117
278
  ```
118
279
 
119
- ## Chain management
120
-
121
- The chain configuration provided during SDK initialization defines where on-chain activities will take place. Currently, only one chain is supported for the `earn` functionality, with multi-chain support coming soon
122
- The example configuration above uses Base chain (chain ID: 8453), meaning all protocol operations and vault deposits will occur on the Base network
123
-
124
- ## Protocol router
125
-
126
- Protocol router is the key component of the SDK that helps an integrator (app/web2 product) to select the best protocol and vault to deposit user's funds.
127
- The only requirement from an integrator is to define a high-level settings for protocols, e.g. min APY, protocol risk level, etc
128
-
129
- The SDK will use settings and find the best protocol and vault under the hood. No one, including integrator, will need to care about this part
130
-
131
- The full list of protocol and chains along with they can be used is the following:
132
-
133
- | Protocol | Chain | ChainId |
134
- | -------------------------- | ----- | ------- |
135
- | [Spark](https://spark.fi/) | Base | 8453 |
136
-
137
- More protocol and chains will be added soon
138
-
139
- ## Contribution
280
+ # Contribution
140
281
 
141
282
  Check the [CONTRIBUTION.md](https://github.com/0xdeval/mycelium-sdk/blob/main/CONTRIBUTION.md)
142
283
 
143
- ## License
284
+ # License
144
285
 
145
- This project is licensed under the dual license - Apache 2.0 + Commercial - see the [LICENSE](https://github.com/0xdeval/mycelium-sdk/blob/main/LICENSE.md)
286
+ This project is licensed under the dual license - Apache 2.0 + Commercial - see the [LICENSE](https://github.com/0xdeval/mycelium-sdk/blob/main/LICENSE)