@bamzzstudio/loka-sdk 0.1.0

package/README.md

@@ -0,0 +1,29 @@
+# Loka SDK
+
+Reusable SDK, ABIs, and deterministic invoice-agent helpers for Loka, a MiniPay-first merchant payment app on Celo.
+
+## Packages
+
+- `@bamzzstudio/loka-sdk`: Umbrella SDK.
+- `@bamzzstudio/loka-core`: Invoice IDs, amount parsing, Celo constants.
+- `@bamzzstudio/loka-contracts`: Ledger ABI and viem payment helpers.
+- `@bamzzstudio/loka-agent`: Deterministic payment request agent.
+
+## Install
+
+```bash
+npm install @bamzzstudio/loka-sdk
+```
+
+## Example
+
+```ts
+import { preparePaymentRequest } from "@bamzzstudio/loka-sdk";
+
+const result = preparePaymentRequest({
+  amount: "2.50",
+  tokenSymbol: "USDm",
+  note: "Lunch order",
+  customer: "Amina",
+});
+```

package/contracts/LokaPayLedger.sol

@@ -0,0 +1,182 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import "@openzeppelin/contracts/access/Ownable.sol";
+import "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+
+/// @title LokaPayLedger
+/// @notice Merchant payment ledger for Celo native and ERC-20 stablecoin payments.
+contract LokaPayLedger is Ownable {
+    using SafeERC20 for IERC20;
+
+    uint256 public constant BPS_DENOMINATOR = 10_000;
+    uint256 public constant MAX_FEE_BPS = 500;
+
+    address payable public treasury;
+    uint256 public feeBps;
+    uint256 public totalPayments;
+
+    struct Receipt {
+        bytes32 invoiceId;
+        address payer;
+        address merchant;
+        address token;
+        uint256 amount;
+        uint256 fee;
+        bytes32 memoHash;
+        uint64 paidAt;
+    }
+
+    mapping(uint256 receiptId => Receipt receipt) public receipts;
+    mapping(bytes32 invoiceId => uint256 count) public invoicePaymentCount;
+
+    event LokaPayment(
+        uint256 indexed receiptId,
+        bytes32 indexed invoiceId,
+        address indexed merchant,
+        address payer,
+        address token,
+        uint256 amount,
+        uint256 fee,
+        bytes32 memoHash
+    );
+    event TreasuryUpdated(address indexed oldTreasury, address indexed newTreasury);
+    event FeeBpsUpdated(uint256 oldFeeBps, uint256 newFeeBps);
+
+    constructor(
+        address initialOwner_,
+        address payable treasury_,
+        uint256 feeBps_
+    ) Ownable(initialOwner_) {
+        require(initialOwner_ != address(0), "OWNER_ZERO");
+        require(feeBps_ <= MAX_FEE_BPS, "FEE_TOO_HIGH");
+
+        treasury = treasury_ == address(0) ? payable(initialOwner_) : treasury_;
+        feeBps = feeBps_;
+    }
+
+    function payNative(
+        bytes32 invoiceId,
+        address payable merchant,
+        bytes32 memoHash
+    ) external payable returns (uint256 receiptId) {
+        require(msg.value > 0, "AMOUNT_ZERO");
+        require(invoiceId != bytes32(0), "INVOICE_EMPTY");
+        require(merchant != address(0), "MERCHANT_ZERO");
+
+        uint256 fee = _feeFor(msg.value);
+        uint256 payout = msg.value - fee;
+
+        receiptId = _recordPayment(
+            invoiceId,
+            msg.sender,
+            merchant,
+            address(0),
+            msg.value,
+            fee,
+            memoHash
+        );
+
+        if (fee > 0) {
+            (bool feeOk, ) = treasury.call{value: fee}("");
+            require(feeOk, "FEE_TRANSFER_FAILED");
+        }
+
+        (bool payOk, ) = merchant.call{value: payout}("");
+        require(payOk, "PAYMENT_TRANSFER_FAILED");
+    }
+
+    function payToken(
+        bytes32 invoiceId,
+        address merchant,
+        address token,
+        uint256 amount,
+        bytes32 memoHash
+    ) external returns (uint256 receiptId) {
+        require(amount > 0, "AMOUNT_ZERO");
+        require(invoiceId != bytes32(0), "INVOICE_EMPTY");
+        require(merchant != address(0), "MERCHANT_ZERO");
+        require(token != address(0), "TOKEN_ZERO");
+
+        IERC20 paymentToken = IERC20(token);
+        uint256 fee = _feeFor(amount);
+        uint256 payout = amount - fee;
+
+        paymentToken.safeTransferFrom(msg.sender, address(this), amount);
+
+        receiptId = _recordPayment(
+            invoiceId,
+            msg.sender,
+            merchant,
+            token,
+            amount,
+            fee,
+            memoHash
+        );
+
+        if (fee > 0) {
+            paymentToken.safeTransfer(treasury, fee);
+        }
+        paymentToken.safeTransfer(merchant, payout);
+    }
+
+    function setTreasury(address payable newTreasury) external onlyOwner {
+        require(newTreasury != address(0), "TREASURY_ZERO");
+
+        address oldTreasury = treasury;
+        treasury = newTreasury;
+
+        emit TreasuryUpdated(oldTreasury, newTreasury);
+    }
+
+    function setFeeBps(uint256 newFeeBps) external onlyOwner {
+        require(newFeeBps <= MAX_FEE_BPS, "FEE_TOO_HIGH");
+
+        uint256 oldFeeBps = feeBps;
+        feeBps = newFeeBps;
+
+        emit FeeBpsUpdated(oldFeeBps, newFeeBps);
+    }
+
+    function _recordPayment(
+        bytes32 invoiceId,
+        address payer,
+        address merchant,
+        address token,
+        uint256 amount,
+        uint256 fee,
+        bytes32 memoHash
+    ) internal returns (uint256 receiptId) {
+        receiptId = ++totalPayments;
+        invoicePaymentCount[invoiceId] += 1;
+
+        receipts[receiptId] = Receipt({
+            invoiceId: invoiceId,
+            payer: payer,
+            merchant: merchant,
+            token: token,
+            amount: amount,
+            fee: fee,
+            memoHash: memoHash,
+            paidAt: uint64(block.timestamp)
+        });
+
+        emit LokaPayment(
+            receiptId,
+            invoiceId,
+            merchant,
+            payer,
+            token,
+            amount,
+            fee,
+            memoHash
+        );
+    }
+
+    function _feeFor(uint256 amount) internal view returns (uint256) {
+        return (amount * feeBps) / BPS_DENOMINATOR;
+    }
+
+    receive() external payable {}
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "@bamzzstudio/loka-agent";
+export * from "@bamzzstudio/loka-contracts";
+export * from "@bamzzstudio/loka-core";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "@bamzzstudio/loka-agent";
+export * from "@bamzzstudio/loka-contracts";
+export * from "@bamzzstudio/loka-core";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC"}

package/docs/REMIX_DEPLOYMENT.md

@@ -0,0 +1,64 @@
+# Remix Deployment
+
+This guide deploys `LokaPayLedger.sol` from Remix to Celo.
+
+## Compiler
+
+- Solidity: `0.8.24` or newer compatible `0.8.x`
+- Enable optimization: `200` runs
+
+## Constructor Values
+
+`LokaPayLedger` constructor:
+
+```solidity
+constructor(
+  address initialOwner_,
+  address payable treasury_,
+  uint256 feeBps_
+)
+```
+
+Recommended values:
+
+- `initialOwner_`: owner wallet that can update fee and treasury
+- `treasury_`: wallet that receives protocol fees, or zero address to use `initialOwner_`
+- `feeBps_`: fee in basis points
+
+Examples:
+
+- `0`: no protocol fee
+- `30`: 0.30%
+- `50`: 0.50%
+
+The contract caps fees at `500` basis points, which is 5%.
+
+## After Deployment
+
+Add the deployed contract address to the app:
+
+```bash
+NEXT_PUBLIC_LOKA_LEDGER_ADDRESS=0xDDBc0b6fB1fB0AAaE4321d69B3625ba4CaB2a952
+```
+
+Then add the same contract address to the project profile on Talent App.
+
+Current Celo Mainnet ledger:
+
+```text
+0xDDBc0b6fB1fB0AAaE4321d69B3625ba4CaB2a952
+```
+
+## Mainnet Defaults
+
+Celo Mainnet:
+
+- Chain ID: `42220`
+- RPC: `https://forno.celo.org`
+- Explorer: `https://celoscan.io`
+
+USDm on Celo Mainnet:
+
+```text
+0x765DE816845861e75A25fCA122bb6898B8B1282a
+```

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@bamzzstudio/loka-sdk",
+  "version": "0.1.0",
+  "description": "SDK, contracts, and invoice agent helpers for Loka merchant payments on Celo.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "contracts",
+    "docs",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adekunlebamz/localpay-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/adekunlebamz/localpay-sdk/issues"
+  },
+  "homepage": "https://github.com/adekunlebamz/localpay-sdk#readme",
+  "license": "MIT",
+  "scripts": {
+    "build": "npm run build:packages && tsc -p tsconfig.json",
+    "build:packages": "npm run build --prefix packages/core && npm run build --prefix packages/contracts && npm run build --prefix packages/agent",
+    "typecheck": "npm run typecheck:packages && tsc -p tsconfig.json --noEmit",
+    "typecheck:packages": "npm run typecheck --prefix packages/core && npm run typecheck --prefix packages/contracts && npm run typecheck --prefix packages/agent"
+  },
+  "workspaces": [
+    "packages/core",
+    "packages/contracts",
+    "packages/agent"
+  ],
+  "dependencies": {
+    "@bamzzstudio/loka-agent": "^0.1.0",
+    "@bamzzstudio/loka-contracts": "^0.1.0",
+    "@bamzzstudio/loka-core": "^0.1.0",
+    "viem": "^2.48.8"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}