@provex/abis 1.6.2 → 1.7.0-rc.20260522201545.020a3eb

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Provex
+
+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,57 @@
+# @provex/abis
+
+Solidity contract ABIs for the Provex protocol. Exported as typed viem-compatible `as const` arrays so calldata encoding and event decoding stay type-safe end-to-end.
+
+## Install
+
+```bash
+npm install @provex/abis viem
+```
+
+Peer dependency: `viem ^2.0.0`.
+
+## Versions
+
+The protocol has two on-chain versions. Both are exported as named subpath imports so a single application can interact with either.
+
+| Subpath | What it exports | When to use |
+|---------|-----------------|-------------|
+| `@provex/abis/v3` | `Escrow`, `Orchestrator`, `UnifiedPaymentVerifier`, `PaymentVerifierRegistry`, `NullifierRegistry` | Current protocol. Off-chain zkTLS attestations via Reclaim. Use for all new integrations. |
+| `@provex/abis/v2` | `Escrow`, `Verifiers` (per-provider verifier ABIs) | Legacy protocol. On-chain proof verification. Read-only access for historical deposits. |
+| `@provex/abis` | Re-exports both as `{ v2, v3 }` namespaces | Convenience entry when consuming both. |
+
+## Usage
+
+```ts
+import { createPublicClient, http } from 'viem'
+import { pulsechain } from 'viem/chains'
+import { Escrow, Orchestrator } from '@provex/abis/v3'
+
+const client = createPublicClient({ chain: pulsechain, transport: http() })
+
+// Read a deposit
+const deposit = await client.readContract({
+  address: '0x...', // V3 Escrow address — see @provex/utils/contracts
+  abi: Escrow,
+  functionName: 'getDeposit',
+  args: [1n],
+})
+
+// Decode an event
+const logs = await client.getContractEvents({
+  address: '0x...',
+  abi: Orchestrator,
+  eventName: 'IntentSignaled',
+  fromBlock: 'earliest',
+})
+```
+
+Contract addresses per chain live in `@provex/utils/contracts` — keep ABIs and addresses in sync by version.
+
+## Integration
+
+For the full SDK and React hooks built on these ABIs, see [@provex/react](https://www.npmjs.com/package/@provex/react). For typed indexer queries, see [@provex/indexer-client](https://www.npmjs.com/package/@provex/indexer-client).
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@provex/abis",
-  "version": "1.6.2",
+  "version": "1.7.0-rc.20260522201545.020a3eb",
   "type": "module",
   "repository": {
     "type": "git",
@@ -10,8 +10,9 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
+  "license": "MIT",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -28,6 +29,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md"
   ],
   "scripts": {

package/skills/abis-integration/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: abis-integration
+description: Use when integrating the Provex protocol via `@provex/abis` — when reading deposits, intents, or events from Provex's Escrow/Orchestrator/UnifiedPaymentVerifier contracts, when encoding calldata for `signalIntent` / `createDeposit` / `fulfillIntent`, when decoding `IntentSignaled` / `DepositCreated` / `IntentFulfilled` event logs via viem, or when wiring a custom subgraph/indexer that needs the ABIs. Covers the v2-vs-v3 split, the `as const` typing requirement for viem inference, and the contract-address sourcing pattern.
+---
+
+# `@provex/abis` Integration
+
+Typed Solidity ABIs for the Provex protocol, exported as `as const` arrays so viem can infer types end-to-end.
+
+## What you get
+
+| Subpath | Exports | When to use |
+|---|---|---|
+| `@provex/abis/v3` | `Escrow`, `Orchestrator`, `UnifiedPaymentVerifier`, `PaymentVerifierRegistry`, `NullifierRegistry` | **Current protocol.** Off-chain zkTLS attestations via Reclaim. Use for all new integrations. |
+| `@provex/abis/v2` | `Escrow`, `Verifiers` | Legacy. On-chain proof verification. Read-only for historical deposits. |
+| `@provex/abis` | `{ v2, v3 }` namespaced re-export | Convenience if you read from both eras. |
+
+The `viem` peer dependency is required (`^2.0.0`). The ABIs are pure data — no runtime — but the type inference depends on viem's `Abi` type.
+
+## Canonical reads
+
+Pair the ABI with an address from `@provex/utils/contracts` — never hardcode. The contracts package keeps the address ↔ chain mapping in sync with the deployed protocol version.
+
+```ts
+import { createPublicClient, http } from 'viem'
+import { pulsechain } from 'viem/chains'
+import { Escrow, Orchestrator } from '@provex/abis/v3'
+import { contracts } from '@provex/utils/contracts'
+
+const client = createPublicClient({ chain: pulsechain, transport: http() })
+
+// Read a deposit by local ID
+const deposit = await client.readContract({
+  address: contracts.escrow[369],
+  abi: Escrow,
+  functionName: 'getDeposit',
+  args: [1n],
+})
+
+// Read intent by hash
+const intent = await client.readContract({
+  address: contracts.orchestrator[369],
+  abi: Orchestrator,
+  functionName: 'getIntent',
+  args: ['0xabc...' as `0x${string}`],
+})
+```
+
+### Gotcha: `getIntent` returns an empty struct for both fulfilled AND pruned intents
+
+V3's `Orchestrator.getIntent(hash)` returns the zero-struct for two unrelated terminal states. Use the indexer (or event presence) to distinguish — RPC is the freshness signal, indexer is the type signal. During indexer lag, prefer `fulfilled` over `cancelled` to avoid false-cancel UI flicker.
+
+## Canonical writes
+
+```ts
+import { createWalletClient, http } from 'viem'
+import { pulsechain } from 'viem/chains'
+import { Orchestrator } from '@provex/abis/v3'
+import { contracts } from '@provex/utils/contracts'
+
+const wallet = createWalletClient({ chain: pulsechain, transport: http() })
+
+const hash = await wallet.writeContract({
+  address: contracts.orchestrator[369],
+  abi: Orchestrator,
+  functionName: 'signalIntent',
+  args: [/* IntentParams struct */],
+  account: '0x...',
+})
+```
+
+If you don't need a wallet client, use `encodeFunctionData` from viem and hand the calldata to any signer (Safe SDK, Privy, EIP-7702 relayer, etc.):
+
+```ts
+import { encodeFunctionData } from 'viem'
+import { Orchestrator } from '@provex/abis/v3'
+
+const data = encodeFunctionData({
+  abi: Orchestrator,
+  functionName: 'signalIntent',
+  args: [/* IntentParams */],
+})
+// → submit { to: contracts.orchestrator[369], data, value: 0n } via your signer
+```
+
+## Decoding events
+
+```ts
+import { decodeEventLog } from 'viem'
+import { Orchestrator } from '@provex/abis/v3'
+
+for (const log of receipt.logs) {
+  try {
+    const event = decodeEventLog({ abi: Orchestrator, data: log.data, topics: log.topics })
+    if (event.eventName === 'IntentSignaled') {
+      const { intentHash, owner, depositId, amount } = event.args
+      // ...
+    }
+  } catch {} // log isn't from this contract
+}
+```
+
+## Chain support
+
+| Chain | ID | Status |
+|---|---|---|
+| PulseChain | `369` | primary — production protocol |
+| Base | `8453` | peer-trade only (not full Provex escrow) |
+
+Identity attestations live on Ethereum mainnet (`1`) via EAS, not on Provex's chains.
+
+## When NOT to import from this package
+
+- **You want contract addresses** → use `@provex/utils/contracts` (it cross-references the ABI version).
+- **You want SDK ergonomics** (deposit lookups by token+method, reputation tier math, signalIntent with prepared calldata) → use `@provex/react`'s `createProveXClient()` or hooks.
+- **You want typed indexer queries** → use `@provex/indexer-client`.
+
+This package is for low-level ABI access. Most consumers should go through `@provex/react` and only reach for `@provex/abis` when bypassing the SDK (smart accounts, batched calls, custom subgraphs).