@eth-optimism/actions-sdk 0.0.0-main-20251009211102

package/LICENSE

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright 2020-2024 Optimism
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# actions-sdk
+
+Actions is an SDK of abstractions and adapters for building applications on the OP stack
+
+## Installation
+
+```bash
+npm install @eth-optimism/actions-sdk
+```
+
+## Quick Start
+
+Initialize the SDK with your wallet provider configuration:
+
+```typescript
+import { initActions } from '@eth-optimism/actions-sdk'
+
+const actions = initActions({
+  // MORE COMING SOON
+})
+```
+
+## Usage
+
+### Creating a Wallet
+
+```typescript
+// Create a new wallet for a user
+const wallet = await actions.createWallet('user123')
+
+console.log(`Wallet created: ${wallet.address}`)
+console.log(`Wallet ID: ${wallet.id}`)
+
+// Get wallet balance
+const balance = await wallet.getBalance()
+console.log(`Balance: ${balance} wei`)
+```
+
+### Retrieving a Wallet
+
+```typescript
+// Get existing wallet by user ID
+const wallet = await actions.getWallet('user123')
+
+if (wallet) {
+  console.log(`Found wallet: ${wallet.address}`)
+} else {
+  console.log('Wallet not found')
+}
+```
+
+## Development
+
+### Prerequisites
+
+For running supersim integration tests, you'll need:
+
+1. **Supersim** - Local multi-chain development environment ([GitHub](https://github.com/ethereum-optimism/supersim))
+
+   ```bash
+   # macOS/Linux
+   brew install ethereum-optimism/tap/supersim
+
+   # Or download from releases
+   # https://github.com/ethereum-optimism/supersim/releases
+   ```
+
+2. **Foundry** - Required by supersim
+   ```bash
+   curl -L https://foundry.paradigm.xyz | bash
+   foundryup
+   ```
+
+### Testing
+
+Run unit tests:
+
+```bash
+pnpm test
+```
+
+Run tests including external tests (those that make real network requests):
+
+```bash
+EXTERNAL_TEST=true pnpm test
+```
+
+Run tests including supersim integration tests:
+
+```bash
+SUPERSIM_TEST=true pnpm test
+```
+
+External tests are used for integration testing with live APIs and services. Supersim tests require supersim to be installed and create local forked networks. Both are disabled by default.
+
+#### Supersim Integration Tests
+
+Some tests use supersim for local forked network testing. They automatically start/stop supersim, fund test wallets, and test transaction execution.
+
+## Documentation
+
+Generate API documentation:
+
+```bash
+npm run docs
+```

package/dist/actions.d.ts

@@ -0,0 +1,58 @@
+import { ActionsLendNamespace } from './lend/namespaces/ActionsLendNamespace.js';
+import type { ActionsConfig } from './types/actions.js';
+import type { LendConfig, LendProvider } from './types/lend/index.js';
+import { WalletNamespace } from './wallet/core/namespace/WalletNamespace.js';
+import type { HostedWalletProvider } from './wallet/core/providers/hosted/abstract/HostedWalletProvider.js';
+import type { HostedWalletProviderRegistry } from './wallet/core/providers/hosted/registry/HostedWalletProviderRegistry.js';
+import type { HostedWalletProvidersSchema } from './wallet/core/providers/hosted/types/index.js';
+import type { SmartWalletProvider } from './wallet/core/providers/smart/abstract/SmartWalletProvider.js';
+/**
+ * Main Actions SDK class
+ * @description Core implementation of the Actions SDK
+ */
+export declare class Actions<THostedWalletProviderConfigKeys extends string, THostedWalletProvidersSchema extends HostedWalletProvidersSchema<THostedWalletProviderConfigKeys, {
+    [K in THostedWalletProviderConfigKeys]: HostedWalletProvider<K, {
+        [K in THostedWalletProviderConfigKeys]: unknown;
+    }>;
+}, {
+    [K in THostedWalletProviderConfigKeys]: unknown;
+}, {
+    [K in THostedWalletProviderConfigKeys]: unknown;
+}>, THostedWalletProviderType extends THostedWalletProviderConfigKeys> {
+    readonly wallet: WalletNamespace<THostedWalletProviderType, THostedWalletProvidersSchema['providerToActionsOptions'], THostedWalletProvidersSchema['providerInstances'][THostedWalletProviderType], SmartWalletProvider>;
+    private chainManager;
+    private _lend?;
+    private _lendProvider?;
+    private hostedWalletProvider;
+    private smartWalletProvider;
+    private hostedWalletProviderRegistry;
+    constructor(config: ActionsConfig<THostedWalletProviderType, THostedWalletProvidersSchema['providerConfigs']>, deps: {
+        hostedWalletProviderRegistry: HostedWalletProviderRegistry<THostedWalletProvidersSchema['providerInstances'], THostedWalletProvidersSchema['providerConfigs'], THostedWalletProvidersSchema['providerTypes']>;
+    });
+    /**
+     * Get lend operations interface
+     * @description Access to lending operations like markets and vault information.
+     * Throws an error if no lend provider is configured in ActionsConfig.
+     * @returns ActionsLendNamespace for lending operations
+     * @throws Error if lend provider not configured
+     */
+    get lend(): ActionsLendNamespace<LendConfig>;
+    /**
+     * Get the lend provider instance
+     * @returns LendProvider instance if configured, undefined otherwise
+     */
+    get lendProvider(): LendProvider<LendConfig> | undefined;
+    /**
+     * Create the wallet provider instance
+     * @param config - Wallet configuration
+     * @returns WalletProvider instance
+     */
+    private createWalletProvider;
+    /**
+     * Create the wallet namespace instance
+     * @param config - Wallet configuration
+     * @returns WalletNamespace instance
+     */
+    private createWalletNamespace;
+}
+//# sourceMappingURL=actions.d.ts.map

package/dist/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAA;AAEhF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAA;AAC5E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iEAAiE,CAAA;AAC3G,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,yEAAyE,CAAA;AAC3H,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,+CAA+C,CAAA;AAChG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+DAA+D,CAAA;AAIxG;;;GAGG;AACH,qBAAa,OAAO,CAClB,+BAA+B,SAAS,MAAM,EAC9C,4BAA4B,SAAS,2BAA2B,CAC9D,+BAA+B,EAC/B;KACG,CAAC,IAAI,+BAA+B,GAAG,oBAAoB,CAC1D,CAAC,EACD;SAAG,CAAC,IAAI,+BAA+B,GAAG,OAAO;KAAE,CACpD;CACF,EACD;KAAG,CAAC,IAAI,+BAA+B,GAAG,OAAO;CAAE,EACnD;KAAG,CAAC,IAAI,+BAA+B,GAAG,OAAO;CAAE,CACpD,EACD,yBAAyB,SAAS,+BAA+B;IAEjE,SAAgB,MAAM,EAAE,eAAe,CACrC,yBAAyB,EACzB,4BAA4B,CAAC,0BAA0B,CAAC,EACxD,4BAA4B,CAAC,mBAAmB,CAAC,CAAC,yBAAyB,CAAC,EAC5E,mBAAmB,CACpB,CAAA;IACD,OAAO,CAAC,YAAY,CAAc;IAClC,OAAO,CAAC,KAAK,CAAC,CAAkC;IAChD,OAAO,CAAC,aAAa,CAAC,CAA0B;IAChD,OAAO,CAAC,oBAAoB,CAA+E;IAC3G,OAAO,CAAC,mBAAmB,CAAsB;IACjD,OAAO,CAAC,4BAA4B,CAInC;gBAEC,MAAM,EAAE,aAAa,CACnB,yBAAyB,EACzB,4BAA4B,CAAC,iBAAiB,CAAC,CAChD,EACD,IAAI,EAAE;QACJ,4BAA4B,EAAE,4BAA4B,CACxD,4BAA4B,CAAC,mBAAmB,CAAC,EACjD,4BAA4B,CAAC,iBAAiB,CAAC,EAC/C,4BAA4B,CAAC,eAAe,CAAC,CAC9C,CAAA;KACF;IA4BH;;;;;;OAMG;IACH,IAAI,IAAI,IAAI,oBAAoB,CAAC,UAAU,CAAC,CAO3C;IAED;;;OAGG;IACH,IAAI,YAAY,IAAI,YAAY,CAAC,UAAU,CAAC,GAAG,SAAS,CAEvD;IAED;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAqD5B;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;CAc9B"}

package/dist/actions.js

@@ -0,0 +1,88 @@
+import { DEFAULT_ACTIONS_CONFIG } from './constants/config.js';
+import { MorphoLendProvider } from './lend/index.js';
+import { ActionsLendNamespace } from './lend/namespaces/ActionsLendNamespace.js';
+import { ChainManager } from './services/ChainManager.js';
+import { WalletNamespace } from './wallet/core/namespace/WalletNamespace.js';
+import { DefaultSmartWalletProvider } from './wallet/core/providers/smart/default/DefaultSmartWalletProvider.js';
+import { WalletProvider } from './wallet/core/providers/WalletProvider.js';
+/**
+ * Main Actions SDK class
+ * @description Core implementation of the Actions SDK
+ */
+export class Actions {
+    constructor(config, deps) {
+        this.chainManager = new ChainManager(config.chains);
+        this.hostedWalletProviderRegistry = deps.hostedWalletProviderRegistry;
+        // Create lending provider if configured
+        if (config.lend) {
+            if (config.lend.provider === 'morpho') {
+                this._lendProvider = new MorphoLendProvider({
+                    ...config.lend,
+                    defaultSlippage: config.lend.defaultSlippage ??
+                        DEFAULT_ACTIONS_CONFIG.lend.defaultSlippage,
+                }, this.chainManager);
+                // Create read-only lend namespace
+                this._lend = new ActionsLendNamespace(this._lendProvider);
+            }
+            else {
+                throw new Error(`Unsupported lending provider: ${config.lend.provider}`);
+            }
+        }
+        this.wallet = this.createWalletNamespace(config.wallet);
+    }
+    /**
+     * Get lend operations interface
+     * @description Access to lending operations like markets and vault information.
+     * Throws an error if no lend provider is configured in ActionsConfig.
+     * @returns ActionsLendNamespace for lending operations
+     * @throws Error if lend provider not configured
+     */
+    get lend() {
+        if (!this._lend) {
+            throw new Error('Lend provider not configured. Please add lend configuration to ActionsConfig.');
+        }
+        return this._lend;
+    }
+    /**
+     * Get the lend provider instance
+     * @returns LendProvider instance if configured, undefined otherwise
+     */
+    get lendProvider() {
+        return this._lendProvider;
+    }
+    /**
+     * Create the wallet provider instance
+     * @param config - Wallet configuration
+     * @returns WalletProvider instance
+     */
+    createWalletProvider(config) {
+        const hostedWalletProviderConfig = config.hostedWalletConfig.provider;
+        const factory = this.hostedWalletProviderRegistry.getFactory(hostedWalletProviderConfig.type);
+        const options = ('config' in hostedWalletProviderConfig
+            ? hostedWalletProviderConfig.config
+            : undefined);
+        if (!factory.validateOptions(options)) {
+            throw new Error(`Invalid options for hosted wallet provider: ${hostedWalletProviderConfig.type}`);
+        }
+        this.hostedWalletProvider = factory.create({ chainManager: this.chainManager, lendProvider: this.lendProvider }, options);
+        if (!config.smartWalletConfig ||
+            config.smartWalletConfig.provider.type === 'default') {
+            this.smartWalletProvider = new DefaultSmartWalletProvider(this.chainManager, this.lendProvider, config.smartWalletConfig.provider.attributionSuffix);
+        }
+        else {
+            throw new Error(`Unsupported smart wallet provider: ${config.smartWalletConfig.provider.type}`);
+        }
+        const walletProvider = new WalletProvider(this.hostedWalletProvider, this.smartWalletProvider);
+        return walletProvider;
+    }
+    /**
+     * Create the wallet namespace instance
+     * @param config - Wallet configuration
+     * @returns WalletNamespace instance
+     */
+    createWalletNamespace(config) {
+        const walletProvider = this.createWalletProvider(config);
+        return new WalletNamespace(walletProvider);
+    }
+}
+//# sourceMappingURL=actions.js.map

package/dist/actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"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"}

package/dist/actions.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=actions.test.d.ts.map

package/dist/actions.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.test.d.ts","sourceRoot":"","sources":["../src/actions.test.ts"],"names":[],"mappings":""}