droplinked-web3-kit 0.0.2 → 0.0.3

package/README.md

@@ -1,400 +1,173 @@
-# Project Onboarding Guide
+# Web3 Package use cases via examples
 
-Welcome to the DropLinked Web3 integration library! This document is designed to bring new developers up to speed on how the system is structured, how its core components interact, and how to extend or maintain functionality. It covers architecture, key abstractions, concrete implementations (with a focus on EVM-compatible chains), error handling, configuration, and end-to-end usage examples.
+## How to use Login Via Wallet
 
----
+### Normal Login
 
-## 0. Project Structure
+```js
+// Create web3 object
+const web3 = new DropWeb3(Network.TESTNET, accessToken);
 
-```
-│   index.ts
-│   
-└───lib
-    │   web3.ts
-    │   
-    ├───chains
-    │   │   chain-provider.ts
-    │   │   README.md
-    │   │   
-    │   ├───dto
-    │   │   │   chains.ts
-    │   │   │   
-    │   │   ├───configs
-    │   │   │       chain.config.ts
-    │   │   │       chainlink-addresses.ts
-    │   │   │       README.md
-    │   │   │       web3-config.ts
-    │   │   │
-    │   │   ├───constants
-    │   │   │       airdrop-abi.ts
-    │   │   │       chain-abis.ts
-    │   │   │       chain-constants.ts
-    │   │   │       chain-structs.ts
-    │   │   │       README.md
-    │   │   │
-    │   │   ├───errors
-    │   │   │       chain-errors.ts
-    │   │   │
-    │   │   └───interfaces
-    │   │           airdrop-token.interface.ts
-    │   │           chain-payment.interface.ts
-    │   │           chain-provider.interface.ts
-    │   │           claim-nft-inputs.ts
-    │   │           deploy-shop.interface.ts
-    │   │           login-result.interface.ts
-    │   │           modal-interface.interface.ts
-    │   │           payment-interface.ts
-    │   │           record-web3-product.interface.ts
-    │   │           web3-context.interface.ts
-    │   │
-    │   └───providers
-    │       ├───evm
-    │       │       evm-affiliate.ts
-    │       │       evm-airdrop.ts
-    │       │       evm-claim-nfts.ts
-    │       │       evm-constants.ts
-    │       │       evm-deploy-shop.ts
-    │       │       evm-login.ts
-    │       │       evm-payments.ts
-    │       │       evm-provider.ts
-    │       │       evm-publish.ts
-    │       │       evm-record.ts
-    │       │       evm.helpers.ts
-    │       │       README.md
-    │       │
-    │       ├───solana
-    │       │       README.md
-    │       │       solana-provider.ts
-    │       │
-    │       └───unstoppable
-    │               unstoppable-provider.ts
-    │
-    └───wallet-providers
-            appkit.ts
-```
-
-
----
-
-## 1. High-Level Architecture
-
-At the heart of this library is a **factory** class called `DropWeb3`, which, given a chosen network (Testnet, Mainnet, etc.), exposes a **single entry point** (`web3Instance`) to obtain a configured provider that implements the `IChainProvider` interface. Each provider (e.g., `EVMProvider`, `SolanaProvider`, `UnstoppableProvider`) encapsulates all chain-specific logic, from wallet connection through contract interaction and transaction management.
-
-The design follows the **Strategy pattern**: calling code never directly references blockchain-specific classes; it only relies on the uniform methods defined by `IChainProvider`. This ensures that adding support for new chains or networks requires zero changes to application-level logic.
-
----
-
-## 2. Core Interfaces and Types
-
-### 2.1 IChainProvider Interface
-
-Defines the contract every chain provider must fulfill. Key methods:
-
-- **`setAxiosInstance(axiosInstance: KyInstance)`**: Inject a custom HTTP client for backend calls (e.g., metadata upload, address lookup).
-- **`walletLogin()`**: Trigger user login via wallet, returning `{ address, signature, nonce, timestamp }`.
-- **`deployShop(shopDetails: IDeployShop)`**: Deploy a shop smart contract, returning addresses and constructor args.
-- **`recordProduct(productData: IProductDetails, skuData: ISKUDetails[])`**: Mint NFTs and register product metadata with your shop contract.
-- **`publishRequest(productId: Uint256, shopAddress: EthAddress)`**: Request affiliate permission to publish a product.
-- **`approveRequest(requestId: Uint256, shopAddress: EthAddress)`** / **`disapproveRequest(...)`**: Approve or disapprove affiliate requests.
-- **`payment(data: IPaymentInputs)`**: Execute a payment, handling token approvals and transfers.
-- **`customPayment(data: IChainPayment)`**: Low-level payment via proxy contracts.
-- **`paymentWithToken(receiver: string, amount: number, tokenAddress: string)`**: Direct token transfer.
-- **`claimNFTs(data: ClaimNFTInputs)`**: Process NFT claim transactions.
-- **`executeAirdrop(airdropId: string)`**: Run batch airdrops of NFTs or tokens.
-- **Chaining setters**: `setAddress`, `setWallet`, `setModal`, `setNFTContractAddress`, `setShopContractAddress`, `setWalletModal` – provide a *fluent API* to configure context before invoking actions.
-- **`disconnect()`**: Cleanly disconnect from the wallet or provider.
-
-All methods return Promises, and setter methods return `this` for easy chaining.
-
-### 2.2 Web3ChainConfig & Web3Actions
-
-Controls how `DropWeb3.web3Instance()` configures your provider:
-
-- **`method: Web3Actions`**: One of `LOGIN`, `DEPLOY`, `RECORD_AFFILIATE`, `PAYMENT`, `CLAIM`, `AIRDROP`.
-- **`chain: Chain`** and **`network: Network`**: Specify which blockchain and sub-network to target.
-- **`preferredWallet: ChainWallet | ChainWallet[]`**: Wallet(s) to prompt (e.g., MetaMask, Phantom, Unstoppable Domains).
-- **`userAddress`, `nftContractAddress`, `shopContractAddress`**: Provide runtime data required by certain actions.
-- **`modalInterface`**: Inject a UI layer for status, confirmations, or error dialogues.
-
-The factory interprets these configs to instantiate and configure the correct provider.
-
-### 2.3 DroplinkedChainConfig
-
-A lightweight internal structure used by helper functions. Contains:
-
-- **`provider: ethers.BrowserProvider`** – low-level RPC connection.
-- **`chain: Chain`, `network: Network`, `userAddress: EthAddress`** – routing details.
-- **`axiosInstance: KyInstance`** – API client.
-- **`modalInterface: ModalInterface`** – user feedback hook.
-- **`gasPredictable: boolean`** – hint for gas estimation strategies.
-
----
-
-## 3. The DropWeb3 Factory
-
-Implemented in `chain-provider.ts`, the `DropWeb3` class:
+// create the chain provider
+const chainProvider = await web3.web3Instance({
+    method: Web3Actions.LOGIN,
+    preferredWallet: ChainWallet.Metamask,
+});
 
-1. **Constructor**: Accepts a `Network` enum; initializes a `ky` client pointing to dev or prod API endpoints.
-2. **chainMapping**: A nested dictionary mapping each `Chain` and `Network` combination to a specific provider instance.
-3. **`web3Instance(config: Web3ChainConfig)`**:
-   - Validates that an implementation exists for the requested chain/network.
-   - Retrieves or constructs a modal via `AppKitProvider`.
-   - Calls chaining setters on the provider instance: `.setAddress()`, `.setWallet()`, `.setModal()`, `.setAxiosInstance()`.
-   - Returns the configured `IChainProvider`.
+// Login via wallet
+const loginData = await chainProvider.walletLogin();
 
-**Usage Example**:
-```ts
-const factory = new DropWeb3(Network.TESTNET);
-const provider = factory.web3Instance({
-  method: Web3Actions.DEPLOY,
-  chain: Chain.ETH,
-  userAddress: '0xabc...'
+// Log the results
+console.log({
+    address: loginData.address,
+    date: loginData.date,
+    none: loginData.nonce,
+    signature: loginData.signature,
 });
 ```
 
----
-
-## 4. Implementation: EVMProvider
-
-Located at `lib/chains/providers/evm/evm-provider.ts`, `EVMProvider`:
-
-### 4.1 Construction & Configuration
-
-- **Constructor**
-  ```ts
-  constructor(chain: Chain, network: Network, gasPredictable: boolean) { … }
-  ```
-  - Initializes `chain`, `network`, `gasPredictable`.
-  - Sets default `axiosInstance`, `modalInterface`, and `address = ZERO_ADDRESS`.
-
-- **Chaining Setters**: `setAxiosInstance()`, `setWalletModal()`, `setNFTContractAddress()`, `setShopContractAddress()`, `setWallet()`, `setModal()`, `setAddress()`.
-
-### 4.2 Connection Management
-
-- **`getEthersProvider()`**:
-  1. Checks `modal.getProvider('eip155')`.
-  2. Uses `modal.connect('eip155')` if needed.
-  3. Returns `ethers.BrowserProvider`.
-
-- **`disconnect()`**: Calls `modal.disconnect('eip155')` until none remain.
-
-### 4.3 Core Feature Methods
-
-#### 4.3.1 Wallet Login
-1. `getEthersProvider()`
-2. Request accounts.
-3. Switch or add chain as needed.
-4. Request SKALE fuel if applicable.
-5. Fetch nonce, sign message.
-6. Return `{ address, signature, nonce, timestamp }`.
-
-#### 4.3.2 Shop Deployment
-Delegates to `deployEVMShop()`:
-1. Build constructor args.
-2. Fetch bytecode via `getShopByteCode()`.
-3. Estimate gas and deploy via Ethers.js.
-4. Wait for `ShopDeployed` event.
-5. Return `{ shopAddress, metadataURI }`.
-
-#### 4.3.3 Product Recording (NFT Minting)
-Calls `recordProduct()`:
-1. Upload metadata for each SKU.
-2. Prepare data: `{ tokenURI, quantity, price }`.
-3. Batch mint NFTs.
-4. Return `{ transactionHash, mintedIds }`.
+### Unstoppable Login
 
-#### 4.3.4 Affiliate Publishing Workflows
-- **publishRequest()**: Sends `requestAffiliate()` transaction; waits for `AffiliateRequested` event.
-- **approveRequest()/disapproveRequest()**: Executes `approve(requestId)` or `disapprove(requestId)` and handles common errors.
+```js
+const web3 = new DropWeb3(Network.TESTNET, accessToken);
 
-#### 4.3.5 Payments Processing
-- **`payment()`**: Validates inputs, builds `DroplinkedChainConfig` and context, calls `droplinked_payment()`, simulates via static call, estimates gas (+5%), sends transaction.
-- **`customPayment()`**: Direct proxy contract call.
-- **`paymentWithToken()`**: Direct ERC20 transfer.
-
-#### 4.3.6 NFT Claiming
-`claimNFTs()` calls bulk `claimPurchase()` on shop contract; returns transaction hash.
-
-#### 4.3.7 Airdrops
-`executeAirdrop()`:
-1. Fetch recipients and token lists.
-2. Batch-call `airdropTokens()`.
-3. Return list of transaction hashes.
-
----
-
-## 5. Supporting Modules & Utilities
-
-### 5.1 Constants & Structs
-- **`chain-constants.ts`**: ZERO_ADDRESS, network IDs.
-- **`chain-structs.ts`**: Types (`EthAddress`, `Uint256`, etc.)
-
-### 5.2 ABI Definitions
-- Stored in `chain-abis/`.
-- Helper getters like `getERC20TokenTransferABI()`.
-
-### 5.3 Chain Config Fetchers
-In `chain.config.ts`:
-- `getDeployerAddress()`, `getProxyAddress()`, `getFundsProxy()`, `getAirdropAddress()`.
+const chainProvider = await web3.web3Instance({
+    method: Web3Actions.LOGIN,
+    preferredWallet: ChainWallet.UnstoppableDomains,
+});
 
-### 5.4 Error Classes
-From `chain-errors.ts`:
-- Wallet errors: `MetaMaskNotFoundException`, etc.
-- Chain errors: `ChainNotImplementedException`, etc.
-- Payment errors: `InsufficientBalanceException`, etc.
+const loginData = await chainProvider.unstoppableLogin(
+    'de81c772-62be-45ed-8d0b-103abfec2ab8', // <-- UDKey
+    window.location.origin
+);
 
----
+console.log({ loginData });
+```
 
-## 6. Error Handling Patterns
+## Record Procedure
 
-1. Wrap external calls in `try/catch`.
-2. Map errors to domain-specific exceptions.
-3. Use `modalInterface.showError()` for UI feedback.
-4. Retry transient failures (up to 2 attempts, exponential backoff).
-5. Validate event logs; throw `UnexpectedContractResponse` if missing.
+```typescript
+const blockchain = "POLYGON"; // The blockchain where the product will be recorded
+const productId = "your-product-id"; // The ID of the product to be recorded
+const accountAddress = "user-wallet-address"; // The user's wallet address, can be empty string to prompt connection
+const shopId = "your-shop-id"; // The ID of the shop where the product will be recorded
 
----
+const  web3 = new  DropWeb3(
+ appDevelopment ? Network.TESTNET : Network.MAINNET,
+ shopId
+);
 
-## 7. Setup, Configuration & Usage Examples
+const  provider = await web3.web3Instance({
+ method: Web3Actions.RECORD,
+ chain: Chain[blockchain],
+ preferredWallet: ChainWallet.Metamask,
+ userAddress: accountAddress, // If the userAddress field is empty, it will prompt the user to connect their wallet first
+});
 
-**Initialize factory**:
-```ts
-import { DropWeb3 } from './lib/chains/chain-provider';
-import { Network, Web3Actions, Chain, ChainWallet } from './lib/chains/dto/configs/web3-config';
+let  record: RecordResponse;
+record = await  provider.recordProduct(productId);
 
-const web3Factory = new DropWeb3(Network.TESTNET);
+return  record;
 ```
 
-**Login**:
-```ts
-const loginProvider = web3Factory.web3Instance({
-  method: Web3Actions.LOGIN,
-  preferredWallet: ChainWallet.Metamask
+### Custom errors
+
+- `ChainNotImplementedException`: when trying to record on a chain which is not implemented yet.
+- `Unauthorized`: The user is not the owner of the shop contract to record products on it.
+- `FieldNotFound`: the `nftContractAddress` or `shopContractAddress` fields are not set for the recording shop.
+- `Web3CallbackFailed`: The callback to web3 services after recording failed.
+- `MetadataUploadFailedException`: The upload of metadata of SKUs failed.
+- `WalletNotFoundException`: The preferred wallet does not exist (must redirect user to wallet installation page).
+- `AccountAccessDeniedException`: The user did not grant access to their wallet when connecting.
+- `NoAccountsFoundException`: The user did not grant access to any of their accounts when connecting.
+- `SignatureRequestDeniedException`: The user denied a signature request.
+- `ChainSwitchException`: Can not switch to the correct chain in the user's wallet.
+- `UserDeniedException`: User denied a sign transaction request.
+
+You can import these errors and check if any of them happens during a record process.
+
+## Payment Procedure
+
+```js
+import {
+Chain,
+ChainWallet,
+DropWeb3,
+Network,
+PaymentTokens,
+Web3Actions,
+} from 'droplinked-web3-kit';
+
+const shopId = '66d47d965744cb21dac659ab';
+const orderId = '5a4fc3e56134cb23cba014dc';
+const paymentMethod = 'USDC';
+const paymentType = 'BINANCE';
+
+// Create Web3 Object
+const web3 = new DropWeb3(Network.TESTNET, shopId);
+
+// Get a provider instance
+const instance = await web3.web3Instance({
+    method: Web3Actions.PAYMENT,
+    chain: Chain[paymentType],
+    preferredWallet: ChainWallet.Metamask,
+    userAddress: '0xYourWalletAddressHere', // <-- This can be fetched by using the login method, also you can pass empty string and the package will ask the user to connect their wallet
 });
-const { address, signature } = await loginProvider.walletLogin();
-```
 
-**Deploy Shop**:
-```ts
-const web3 = new DropWeb3(appDevelopment ? Network.TESTNET : Network.MAINNET);
-const chainInstance = web3.web3Instance({
-  method: Web3Actions.DEPLOY,
-  preferredWallet: preferredWallets,
-  chain: Chain.BASE,
-  userAddress: "0x...",
+// Call the payment method
+const result = await instance.payment({
+    orderID: orderId,
+    paymentToken: PaymentTokens[paymentMethod],
+    paymentType: Chain[paymentType],
 });
-const shop = chainInstance.deployShop({
-  shopAddress: "...",
-  shopDescription: "...",
-  shopLogo: "...",
-  shopName: "..."
-})
-console.log(shop.deployedNFTAddress, shop.deployedShopAddress, shop.transactionHash);
-```
-
-
----
-
-## 8. Extending to New Chains
-
-1. Create `NewChainProvider implements IChainProvider` under `lib/chains/providers/newchain/`.
-2. Implement all interface methods using the chain's SDK.
-3. Add to `chainMapping` in `chain-provider.ts`.
-4. Include any new ABI or config files.
-5. Write integration tests covering all methods.
-
----
-
-## 9. Best Practices & Recommendations
 
-- **Fluent Configuration**: Always chain `.setWallet()`, `.setModal()`, `.setAxiosInstance()` before actions.
-- **Await Confirmations**: Use `tx.wait()` to ensure on-chain finality.
-- **Error Granularity**: Handle domain-specific exceptions for better UX.
-- **Avoid Hardcoding**: Use config fetchers; do not embed addresses in code.
-- **Testing**: Cover actions on both Testnet and Mainnet.
-- **Security**: Always verify signatures server-side.
-
----
-
-*Welcome aboard! Use this guide as your roadmap to explore, debug, and extend the DropLinked integration library.*
-
-
-## 10. Project Entry Points
-
-### 10.1 `index.ts`
-
-The entry point of the library re-exports core modules to simplify imports:
-
-```ts
-// index.ts
-export * from './lib/web3';
-```
-
-This allows consumers to import everything via:
-
-```ts
-import { DropWeb3, Web3Actions, Chain, Network } from 'droplinked-sdk';
+// Log the results
+console.log({
+    orderID: result.orderID,
+    cryptoAmount: result.cryptoAmount,
+    transactionHash: result.transactionHash,
+    transactionId: result.transactionId,
+});
 ```
 
-### 10.2 `web3.ts`
-
-The `web3.ts` file consolidates and re-exports all sub-modules:
-
-```ts
-import { ZERO_ADDRESS } from './chains/dto/constants/chain-constants';
-
-export * from './chains/chain-provider';
-export * from './chains/providers/evm/evm-login';
-export * from './chains/dto/errors/chain-errors';
-export * from './chains/dto/constants/chain-structs';
-export * from './chains/dto/chains';
-export * from './chains/dto/interfaces/modal-interface.interface';
-export * from './chains/dto/configs/chain.config';
-export * from './chains/dto/configs/web3-config';
-export * from './chains/dto/interfaces/chain-provider.interface';
-export * from './chains/dto/interfaces/airdrop-token.interface';
-export * from './chains/dto/interfaces/claim-nft-inputs';
-export * from './chains/dto/interfaces/deploy-shop.interface';
-export * from './chains/dto/interfaces/record-web3-product.interface';
-export * from './chains/dto/interfaces/web3-context.interface';
-export { ZERO_ADDRESS };
+List of Chains and Payment Tokens supported can be found here:
+
+Payment Tokens:
+
+```js
+export declare enum PaymentTokens {
+    ETH = "ETH",
+    RBNT = "RBNT",
+    SOL = "SOL",
+    USDC = "USDC",
+    USDT = "USDT",
+    MEW = "MEW",
+    BNB = "BNB",
+    MATIC = "MATIC",
+    CSPR = "CSPR",
+    PARAM = "PARAM",
+    BDC = "BDC",
+    BTC = "BTC"
+}
 ```
 
-This centralized export ensures that all types, interfaces, and implementations are available through a single import path.
-
-## 11. DTO Layer & File Structure
-
-Under `lib/chains/dto`, the Data Transfer Objects (DTOs) and configuration files define the structural contracts:
-
+Chains:
+
+```js
+export declare enum Chain {
+    CASPER = "CASPER",
+    POLYGON = "POLYGON",
+    BINANCE = "BINANCE",
+    STACKS = "STACKS",
+    XRPLSIDECHAIN = "XRPLSIDECHAIN",
+    NEAR = "NEAR",
+    SKALE = "SKALE",
+    BASE = "BASE",
+    LINEA = "LINEA",
+    ETH = "ETH",
+    SOLANA = "SOLANA",
+    REDBELLY = "REDBELLY",
+    UNSTOPPABLE = "UNSTOPPABLE",
+    BITLAYER = "BITLAYER"
+}
 ```
-lib/chains/dto
-├── chains.ts
-├── configs
-│   ├── chain.config.ts
-│   └── web3-config.ts
-├── constants
-│   ├── chain-constants.ts
-│   └── chain-structs.ts
-├── errors
-│   └── chain-errors.ts
-└── interfaces
-    ├── airdrop-token.interface.ts
-    ├── chain-provider.interface.ts
-    ├── chain-payment.interface.ts
-    ├── claim-nft-inputs.ts
-    ├── deploy-shop.interface.ts
-    ├── modal-interface.interface.ts
-    ├── record-web3-product.interface.ts
-    └── web3-context.interface.ts
-```
-
-- **`chains.ts`**: Defines the `Chain` enum (e.g., ETH, POLYGON) and related types.
-- **`chain.config.ts`**: Provides `getDeployerAddress`, `getProxyAddress`, and other address-fetching utilities.
-- **`web3-config.ts`**: Exports `Web3Actions` enum and `Web3ChainConfig` interface used by the `DropWeb3` factory.
-- **`chain-constants.ts`**: Common constants like `ZERO_ADDRESS` and retry settings.
-- **`chain-structs.ts`**: Strong-type wrappers for on-chain data (e.g., `EthAddress`, `Uint256`).
-- **`chain-errors.ts`**: Domain-specific error classes covering wallet, RPC, and contract errors.
-- **Interfaces**: Define method signatures and data shapes for all features (login, deployment, recording, payments, airdrops, modal interactions).
-
-By understanding this DTO layer, developers can see how configuration and data shapes flow through the factory into each provider.
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "droplinked-web3-kit",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "dependencies": {
     "ethers": "^5.7.2",
     "ky": "^1.7.2",