@pearcurve/sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,64 @@
+Business Source License
+
+Licensor: Pearcurve Labs
+
+---
+
+**Definitions**
+
+For purposes of this License:
+
+**"Competitive Product or Service"** means any product or service providing lending, borrowing, liquidity, or closely substitutable functionality that is materially similar in purpose or function to those provided by the Pearcurve Protocol.
+
+**"Derivative"** means any work that modifies, incorporates, is based upon, or would otherwise be considered a derivative work of, the Licensed Work, including under applicable copyright law.
+
+**"Production Environment"** means an environment in which users interact with the Licensed Work using "live", real, economically meaningful or value-bearing digital assets.
+
+**"Test Environment"** means an environment in which users interact with the Licensed Work using non-live test, simulated, or synthetic data.
+
+---
+
+**Terms**
+
+1. **Scope**
+
+All copies of the original or modified Licensed Work, and any Derivative works of the Licensed Work, are subject to this License. This License applies separately for each version of the Licensed Work, and the Change Date may vary for each version. You must conspicuously reproduce this License in each copy of the Licensed Work or Derivative work.
+
+2. **Grant of Rights**
+
+Licensor hereby grants you a non-exclusive, non-transferable, non-sublicensable right to copy, modify, create Derivative works, redistribute, and use the Licensed Work solely in a Test Environment, subject to the conditions set forth in this License.
+
+3. **No Competitive Production Deployment**
+
+Any use of the Licensed Work, or any Derivative thereof, in a Production Environment is strictly prohibited. Licensor may grant waivers or commercial licenses for specific parties or use cases, at the direction of Pearcurve Protocol governance. If you are uncertain whether your intended use complies with this License, you must obtain a separate commercial license from Licensor before proceeding.
+
+4. **No Prior Competitive Fork Operators**
+
+You represent that you are not currently, and have not been within the four years prior to your first use of the Licensed Work, a Materially Involved Contributor to any project that has deployed or is seeking to deploy a Competitive Product or Service. This License automatically terminates at such time that this representation is no longer accurate. "Materially Involved Contributor" means direct participation in protocol design, smart contract development, deployment execution, or governance or operational decision-making relating to a Competitive Product or Service.
+
+5. **No Material Misrepresentation of Affiliation**
+
+You may not materially misrepresent affiliation with, or endorsement by, the Pearcurve Protocol or the Pearcurve brand even when using the Licensed Work.
+
+6. **Change Date**
+
+The Change Date is the earlier of:
+
+- 5 years after the deployment date of the Pearcurve Protocol on Ethereum Mainnet
+- If specified, a date designated by Pearcurve Protocol governance and recorded in the "changedate" text record at [designated address]
+
+A Change Date set through governance takes precedence over the stated date above.
+
+7. **Change License**
+
+The Change License shall be the MIT License.
+
+8. **General**
+
+If your use of the Licensed Work does not comply with the requirements of this License, your rights under this License automatically terminate and you must either refrain from using the Licensed Work or obtain a separate commercial license from Licensor or its authorized delegates.
+
+If any condition of this License is held unenforceable as applied, such condition shall be severed to the minimum extent necessary, and the remaining conditions shall remain in full force and effect.
+
+This License does not grant you any right in any trademark or logo of Pearcurve, except as required for accurate attribution.
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.

package/README.md

@@ -1,3 +1,123 @@
-# Temporary Holding Version
+# Pearcurve TypeScript SDK (`@pearcurve/sdk`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Install this package to write on-chain** — encode calldata and submit transactions via [ethers v6](https://docs.ethers.org/v6/).
+
+For **reading** protocol state (intent book, loans, health), use the **public read API** — no install. See the [pearcurve-api](https://github.com/pearcurve/pearcurve-api) README.
+
+> **Repo note:** The SDK moved here from the `pearcurve-solidity` monorepo and publishes as `@pearcurve/sdk` on npm. Its ABIs and addresses come from `@pearcurve/contracts`, published by pearcurve-solidity.
+
+## Contents
+
+- **ABIs** — `Main`, `MatchingEngine`, `IntentRegistry` (core), **`IntentRegistryViews`**, `YieldSourceRegistry`, `IYieldSource`, and **`Errors.sol`** (`src/abis/json/errors.json`). Refresh after a contracts release with `npm run sync-abis`, which always copies `abis/` from `@pearcurve/contracts@latest` (the contracts package builds them from Foundry `out/` + `Errors.sol` error fragments + enum normalization). Or manually copy ABIs and run `npm run normalize-abis` so enum fields use `uint8` (avoids ethers `[Warning] Invalid Fragment`).
+- **Custom errors** — `decodeProtocolError` / `formatProtocolError` map revert selectors (`bytes4(keccak256("FillExceedsCapacity()"))`) from `Errors.sol` to human-readable copy. UI, API, and bots should use this instead of scraping wallet text.
+- **Preflight** — `assertLenderSubmitLiquidity(provider, …)` mirrors on-chain checks for `committedCapacity + maxPrincipal` vs yield `balanceOf` or wallet `min(balance, allowance)` before `submitLenderIntent`.
+- **Encoding** — `encodeSubmitLenderIntent`, `encodeMatchBundleOnChain`, etc.
+- **Clients** — `getMain`, `getMatchingEngine`, `getIntentRegistry` (core), **`getIntentRegistryViews`**, `getYieldSourceRegistry`, `getYieldSource` helpers.
+- **Loan positions** — `transferLoanPosition`, `listLoanPosition`, `delistLoanPosition`, and `getLoanPositionTokenFromMain` for direct lender position NFT ownership flows.
+- **Yield sources** — `listApprovedYieldSourceAddresses`, `fetchSupportedYieldSourceApys`, `fetchSupportedYieldSourceApysFromMain` (wraps registry + `IYieldSource.currentApy` / `name`).
+- **Network config** — `src/networkConfig.ts`: `deployments`, `getDeployment`, `requireDeployment`, and `PearcurveChainId` (regenerate after a deployment with `npm run sync-deployments -- @pearcurve/contracts@<version> <chainId>`, then `npm run build`).
+
+## Install
+
+```bash
+npm install
+```
+
+Consumers should depend on **`ethers` ^6.16** (see `peerDependencies`).
+
+## API vs SDK
+
+| | Read API | SDK (this package) |
+|--|----------|---------------------|
+| **Install** | **None** — public URL | `npm install @pearcurve/sdk` |
+| **Access** | `GET https://api.pearcurve.io/v1/...` | Import + wallet / signer |
+| **Use for** | Dashboards, analytics, bot polling | Submit intents, matches, liquidations |
+| **Location** | Hosted service (pearcurve-api) | This repository |
+
+```bash
+# Reading — no install
+curl https://api.pearcurve.io/v1/intents/book
+
+# Writing — install SDK
+npm install @pearcurve/sdk ethers
+```
+
+The solver bot reads the on-chain intent book via this SDK (IntentRegistryViews + PriceOracle) and submits `matchBundleOnChain`. Other bots/apps may still fetch the public API for state.
+
+### On-chain solver match (integrator / solver bot)
+
+```typescript
+import { Wallet } from 'ethers'
+import { getMain, type SolverSolution } from '@pearcurve/sdk'
+
+const wallet = new Wallet(privateKey, provider)
+
+const sol: SolverSolution = {
+  lenderIntentIds: [lenderIntentId],
+  borrowerIntentIds: [borrowerIntentId],
+  agreedRates: [agreedRateBps],
+  fillAmounts: [fillAmount],
+  solverTip: 0n,
+  solver: wallet.address,
+  deadline,
+  signature,
+}
+await getMain(mainAddress, wallet).matchBundleOnChain(sol)
+```
+
+## Build
+
+```bash
+npm run build
+```
+
+Output: `dist/` (TypeScript declarations included).
+
+## Publish
+
+`npm run publish:sdk` publishes this package as `@pearcurve/sdk`. It copies ABIs from `@pearcurve/contracts@latest`, runs the test suite, then `npm publish --access public`. A merge does not publish it.
+
+Bump `version` in `package.json` first. npm rejects a second publish of the same version. You need to be logged in as a member of the `pearcurve` npm org.
+
+```bash
+npm run publish:sdk
+npm run publish:sdk -- --dry-run
+```
+
+## Integration tests
+
+Tests deploy the same mock stack as `test/TestBase.sol` in pearcurve-solidity against a local **Anvil** instance (spawned by Vitest on port **19545** by default).
+
+```bash
+# pearcurve-solidity cloned next to this repo, or set PEARCURVE_CONTRACTS_DIR to it
+(cd ../pearcurve-solidity && forge build) && npm test
+```
+
+Override port: `ANVIL_PORT=19546 npm test`. Use an existing node: `SKIP_ANVIL=1 ANVIL_RPC_URL=http://127.0.0.1:8545 npm test`.
+
+### ethers + Anvil nonces
+
+ethers v6’s `Wallet` can cache the account nonce incorrectly across rapid `ContractFactory.deploy` / contract calls. The test helpers use an explicit nonce counter for the deployer during setup, and per-actor counters in integration tests. In your app, prefer `provider.getTransactionCount(address, 'latest')` (or a `NonceManager`-style pattern) when automating many txs from the same key.
+
+## Loan Position Helpers
+
+```typescript
+import {
+  getMain,
+  getLoanPositionTokenFromMain,
+  transferLoanPosition,
+  listLoanPosition,
+  delistLoanPosition,
+} from '@pearcurve/sdk'
+
+const main = getMain(mainAddress, signer)
+const loanPositionToken = await getLoanPositionTokenFromMain(main)
+
+await transferLoanPosition(loanPositionToken, signer.address, recipient, 42n)
+await listLoanPosition(main, 42n, 1_050_000000n, usdcAddress, BigInt(Math.floor(Date.now() / 1000) + 7 * 86400))
+await delistLoanPosition(main, 42n)
+```
+
+## License
+
+Business Source License — see [`LICENSE`](LICENSE); contracts use `LicenseRef-BUSL` SPDX.

package/dist/abis/json/collateralTokenRegistry.json

@@ -0,0 +1,257 @@
+[
+    {
+        "type": "constructor",
+        "inputs": [
+            {
+                "name": "governor_",
+                "type": "address",
+                "internalType": "address"
+            },
+            {
+                "name": "_priceOracle",
+                "type": "address",
+                "internalType": "address"
+            }
+        ],
+        "stateMutability": "nonpayable"
+    },
+    {
+        "type": "function",
+        "name": "acceptGovernance",
+        "inputs": [],
+        "outputs": [],
+        "stateMutability": "nonpayable"
+    },
+    {
+        "type": "function",
+        "name": "governor",
+        "inputs": [],
+        "outputs": [
+            {
+                "name": "",
+                "type": "address",
+                "internalType": "address"
+            }
+        ],
+        "stateMutability": "view"
+    },
+    {
+        "type": "function",
+        "name": "isApproved",
+        "inputs": [
+            {
+                "name": "",
+                "type": "address",
+                "internalType": "address"
+            }
+        ],
+        "outputs": [
+            {
+                "name": "",
+                "type": "bool",
+                "internalType": "bool"
+            }
+        ],
+        "stateMutability": "view"
+    },
+    {
+        "type": "function",
+        "name": "listApprovedCollateralTokens",
+        "inputs": [],
+        "outputs": [
+            {
+                "name": "",
+                "type": "address[]",
+                "internalType": "address[]"
+            }
+        ],
+        "stateMutability": "view"
+    },
+    {
+        "type": "function",
+        "name": "listPricedCollateralTokensForLoanAsset",
+        "inputs": [
+            {
+                "name": "loanAsset",
+                "type": "address",
+                "internalType": "address"
+            }
+        ],
+        "outputs": [
+            {
+                "name": "",
+                "type": "address[]",
+                "internalType": "address[]"
+            }
+        ],
+        "stateMutability": "view"
+    },
+    {
+        "type": "function",
+        "name": "pendingGovernor",
+        "inputs": [],
+        "outputs": [
+            {
+                "name": "",
+                "type": "address",
+                "internalType": "address"
+            }
+        ],
+        "stateMutability": "view"
+    },
+    {
+        "type": "function",
+        "name": "priceOracle",
+        "inputs": [],
+        "outputs": [
+            {
+                "name": "",
+                "type": "address",
+                "internalType": "address"
+            }
+        ],
+        "stateMutability": "view"
+    },
+    {
+        "type": "function",
+        "name": "registerCollateral",
+        "inputs": [
+            {
+                "name": "token",
+                "type": "address",
+                "internalType": "address"
+            }
+        ],
+        "outputs": [],
+        "stateMutability": "nonpayable"
+    },
+    {
+        "type": "function",
+        "name": "removeCollateral",
+        "inputs": [
+            {
+                "name": "token",
+                "type": "address",
+                "internalType": "address"
+            }
+        ],
+        "outputs": [],
+        "stateMutability": "nonpayable"
+    },
+    {
+        "type": "function",
+        "name": "requireApproved",
+        "inputs": [
+            {
+                "name": "token",
+                "type": "address",
+                "internalType": "address"
+            }
+        ],
+        "outputs": [],
+        "stateMutability": "view"
+    },
+    {
+        "type": "function",
+        "name": "transferGovernance",
+        "inputs": [
+            {
+                "name": "newGovernor",
+                "type": "address",
+                "internalType": "address"
+            }
+        ],
+        "outputs": [],
+        "stateMutability": "nonpayable"
+    },
+    {
+        "type": "event",
+        "name": "CollateralRegistered",
+        "inputs": [
+            {
+                "name": "token",
+                "type": "address",
+                "indexed": true,
+                "internalType": "address"
+            }
+        ],
+        "anonymous": false
+    },
+    {
+        "type": "event",
+        "name": "CollateralRemoved",
+        "inputs": [
+            {
+                "name": "token",
+                "type": "address",
+                "indexed": true,
+                "internalType": "address"
+            }
+        ],
+        "anonymous": false
+    },
+    {
+        "type": "event",
+        "name": "GovernorTransferInitiated",
+        "inputs": [
+            {
+                "name": "currentGovernor",
+                "type": "address",
+                "indexed": true,
+                "internalType": "address"
+            },
+            {
+                "name": "pendingGovernor_",
+                "type": "address",
+                "indexed": true,
+                "internalType": "address"
+            }
+        ],
+        "anonymous": false
+    },
+    {
+        "type": "event",
+        "name": "GovernorUpdated",
+        "inputs": [
+            {
+                "name": "oldGovernor",
+                "type": "address",
+                "indexed": true,
+                "internalType": "address"
+            },
+            {
+                "name": "newGovernor",
+                "type": "address",
+                "indexed": true,
+                "internalType": "address"
+            }
+        ],
+        "anonymous": false
+    },
+    {
+        "type": "error",
+        "name": "CallerIsNotGovernor",
+        "inputs": []
+    },
+    {
+        "type": "error",
+        "name": "CallerIsNotPendingGovernor",
+        "inputs": []
+    },
+    {
+        "type": "error",
+        "name": "UnsupportedCollateral",
+        "inputs": [
+            {
+                "name": "token",
+                "type": "address",
+                "internalType": "address"
+            }
+        ]
+    },
+    {
+        "type": "error",
+        "name": "ZeroAddress",
+        "inputs": []
+    }
+]