@kehtus/proportion-sdk 0.1.0 → 0.1.1

package/arch.md

@@ -11,6 +11,14 @@ This document is intentionally aligned to the code in:
 
 If documentation and Solidity diverge, Solidity is the source of truth.
 
+## Key Contract Integration Notes
+
+- **Single Managed Signer:** Only `apiWallet` exists on FundedAccount. It is set by the relayer via `setApiWallet()`. No `riskEngineWallet` or `builderRiskEngineWallet`.
+- **Unified Mode:** FundedAccount operates in Hyperliquid unified mode (shared spot + perp balance). Withdrawals use one-step `spotSend` instead of two-step `usdClassTransfer` + `spotSend`.
+- **6dec Account Values:** `accountMarginSummary` returns 6dec. `highWaterMark`, `dayStartValue`, and drawdown floors are all 6dec. `spotBalance` and `spotSend` use 8dec.
+- **Multi-DEX:** `PERP_DEX_COUNT = 2` replaces `PERP_DEX_INDEX = 0`. Account value is summed across all DEXes + spot.
+- **`bridgeToEvm()`** is restricted to `Returning` state only (retry `spotSend` for stuck funds during close flow).
+
 ## Architecture
 
 The SDK has four runtime modules:
@@ -203,25 +211,22 @@ const config = await prop.account.getAccountConfig("0xAccount");
 Writes:
 
 ```ts
-await prop.account.setApiWallet("0xAccount", "0xWallet");
-await prop.account.setRiskEngineWallet("0xAccount", "0xWallet");
+await prop.account.setApiWallet("0xAccount", "0xWallet"); // relayer-only
 await prop.account.requestWithdrawProfit("0xAccount");
 await prop.account.cancelSubscription("0xAccount");
-await prop.account.cancelStuckWithdrawal("0xAccount");
 
 await prop.account.checkpoint("0xAccount");
 await prop.account.initiateClose("0xAccount");
 await prop.account.initiateCloseForPerp("0xAccount", 0);
 await prop.account.initiateCloseAdmin("0xAccount");
 await prop.account.closeAndReturn("0xAccount");
+await prop.account.bridgeToEvm("0xAccount");       // Returning state only — retry spotSend
 await prop.account.finalizeReturn("0xAccount");
 await prop.account.claimWithdrawal("0xAccount");
 await prop.account.claimSubscriptionFee("0xAccount");
 await prop.account.rescueStuckFunds("0xAccount");
 ```
 
-`setRiskEngineWallet()` maps to the current contract behavior in which the same method is used by the protocol relayer and by the builder; on-chain access control decides which of `riskEngineWallet` or `builderRiskEngineWallet` is updated.
-
 ### `prop.factory`
 
 Canonical on-chain surface of the current factory:
@@ -321,12 +326,14 @@ The utility layer mirrors the current contract formulas.
 Decimals:
 
 ```ts
-toUsdc(100);          // 100_000_000n
+toUsdc(100);          // 100_000_000n (6dec)
 fromUsdc(100_000_000n); // 100
-to8Dec(100_000_000n);   // 10_000_000_000n
-toUsdc6(10_000_000_000n); // 100_000_000n
+to8Dec(100_000_000n);   // 10_000_000_000n (6dec→8dec, for spotSend)
+toUsdc6(10_000_000_000n); // 100_000_000n (8dec→6dec)
 ```
 
+Note: On-chain `highWaterMark`, `dayStartValue`, and drawdown floors are all 6dec (matching `accountMarginSummary` output). `spotBalance` and `spotSend` use 8dec.
+
 Activation fee:
 
 ```ts

package/dist/__tests__/reads.test.js

@@ -180,6 +180,5 @@ describe("account reads", () => {
             return;
         const pw = await account.getPendingWithdrawal(existingAccount);
         expect(pw.profit).toBeTypeOf("bigint");
-        expect(typeof pw.requestedAt).toBe("number");
     });
 });

package/dist/abi/factory.d.ts

@@ -7,6 +7,10 @@ export declare const factoryAbi: readonly [{
         readonly internalType: "address";
         readonly name: "_implementation";
         readonly type: "address";
+    }, {
+        readonly internalType: "address";
+        readonly name: "_forwarder";
+        readonly type: "address";
     }];
     readonly stateMutability: "nonpayable";
     readonly type: "constructor";
@@ -189,6 +193,16 @@ export declare const factoryAbi: readonly [{
     }];
     readonly stateMutability: "nonpayable";
     readonly type: "function";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "forwarder";
+    readonly outputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "";
+        readonly type: "address";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
 }, {
     readonly inputs: readonly [];
     readonly name: "implementation";

package/dist/abi/factory.js

@@ -10,6 +10,11 @@ export const factoryAbi = [
                 "internalType": "address",
                 "name": "_implementation",
                 "type": "address"
+            },
+            {
+                "internalType": "address",
+                "name": "_forwarder",
+                "type": "address"
             }
         ],
         "stateMutability": "nonpayable",
@@ -244,6 +249,19 @@ export const factoryAbi = [
         "stateMutability": "nonpayable",
         "type": "function"
     },
+    {
+        "inputs": [],
+        "name": "forwarder",
+        "outputs": [
+            {
+                "internalType": "address",
+                "name": "",
+                "type": "address"
+            }
+        ],
+        "stateMutability": "view",
+        "type": "function"
+    },
     {
         "inputs": [],
         "name": "implementation",

package/dist/abi/forwarder.d.ts

@@ -0,0 +1,287 @@
+export declare const forwarderAbi: readonly [{
+    readonly inputs: readonly [];
+    readonly stateMutability: "nonpayable";
+    readonly type: "constructor";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "uint48";
+        readonly name: "deadline";
+        readonly type: "uint48";
+    }];
+    readonly name: "ERC2771ForwarderExpiredRequest";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "signer";
+        readonly type: "address";
+    }, {
+        readonly internalType: "address";
+        readonly name: "from";
+        readonly type: "address";
+    }];
+    readonly name: "ERC2771ForwarderInvalidSigner";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "uint256";
+        readonly name: "requestedValue";
+        readonly type: "uint256";
+    }, {
+        readonly internalType: "uint256";
+        readonly name: "msgValue";
+        readonly type: "uint256";
+    }];
+    readonly name: "ERC2771ForwarderMismatchedValue";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "target";
+        readonly type: "address";
+    }, {
+        readonly internalType: "address";
+        readonly name: "forwarder";
+        readonly type: "address";
+    }];
+    readonly name: "ERC2771UntrustfulTarget";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "FailedCall";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "uint256";
+        readonly name: "balance";
+        readonly type: "uint256";
+    }, {
+        readonly internalType: "uint256";
+        readonly name: "needed";
+        readonly type: "uint256";
+    }];
+    readonly name: "InsufficientBalance";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "account";
+        readonly type: "address";
+    }, {
+        readonly internalType: "uint256";
+        readonly name: "currentNonce";
+        readonly type: "uint256";
+    }];
+    readonly name: "InvalidAccountNonce";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "InvalidShortString";
+    readonly type: "error";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "string";
+        readonly name: "str";
+        readonly type: "string";
+    }];
+    readonly name: "StringTooLong";
+    readonly type: "error";
+}, {
+    readonly anonymous: false;
+    readonly inputs: readonly [];
+    readonly name: "EIP712DomainChanged";
+    readonly type: "event";
+}, {
+    readonly anonymous: false;
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly internalType: "address";
+        readonly name: "signer";
+        readonly type: "address";
+    }, {
+        readonly indexed: false;
+        readonly internalType: "uint256";
+        readonly name: "nonce";
+        readonly type: "uint256";
+    }, {
+        readonly indexed: false;
+        readonly internalType: "bool";
+        readonly name: "success";
+        readonly type: "bool";
+    }];
+    readonly name: "ExecutedForwardRequest";
+    readonly type: "event";
+}, {
+    readonly inputs: readonly [];
+    readonly name: "eip712Domain";
+    readonly outputs: readonly [{
+        readonly internalType: "bytes1";
+        readonly name: "fields";
+        readonly type: "bytes1";
+    }, {
+        readonly internalType: "string";
+        readonly name: "name";
+        readonly type: "string";
+    }, {
+        readonly internalType: "string";
+        readonly name: "version";
+        readonly type: "string";
+    }, {
+        readonly internalType: "uint256";
+        readonly name: "chainId";
+        readonly type: "uint256";
+    }, {
+        readonly internalType: "address";
+        readonly name: "verifyingContract";
+        readonly type: "address";
+    }, {
+        readonly internalType: "bytes32";
+        readonly name: "salt";
+        readonly type: "bytes32";
+    }, {
+        readonly internalType: "uint256[]";
+        readonly name: "extensions";
+        readonly type: "uint256[]";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly components: readonly [{
+            readonly internalType: "address";
+            readonly name: "from";
+            readonly type: "address";
+        }, {
+            readonly internalType: "address";
+            readonly name: "to";
+            readonly type: "address";
+        }, {
+            readonly internalType: "uint256";
+            readonly name: "value";
+            readonly type: "uint256";
+        }, {
+            readonly internalType: "uint256";
+            readonly name: "gas";
+            readonly type: "uint256";
+        }, {
+            readonly internalType: "uint48";
+            readonly name: "deadline";
+            readonly type: "uint48";
+        }, {
+            readonly internalType: "bytes";
+            readonly name: "data";
+            readonly type: "bytes";
+        }, {
+            readonly internalType: "bytes";
+            readonly name: "signature";
+            readonly type: "bytes";
+        }];
+        readonly internalType: "struct ERC2771Forwarder.ForwardRequestData";
+        readonly name: "request";
+        readonly type: "tuple";
+    }];
+    readonly name: "execute";
+    readonly outputs: readonly [];
+    readonly stateMutability: "payable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly components: readonly [{
+            readonly internalType: "address";
+            readonly name: "from";
+            readonly type: "address";
+        }, {
+            readonly internalType: "address";
+            readonly name: "to";
+            readonly type: "address";
+        }, {
+            readonly internalType: "uint256";
+            readonly name: "value";
+            readonly type: "uint256";
+        }, {
+            readonly internalType: "uint256";
+            readonly name: "gas";
+            readonly type: "uint256";
+        }, {
+            readonly internalType: "uint48";
+            readonly name: "deadline";
+            readonly type: "uint48";
+        }, {
+            readonly internalType: "bytes";
+            readonly name: "data";
+            readonly type: "bytes";
+        }, {
+            readonly internalType: "bytes";
+            readonly name: "signature";
+            readonly type: "bytes";
+        }];
+        readonly internalType: "struct ERC2771Forwarder.ForwardRequestData[]";
+        readonly name: "requests";
+        readonly type: "tuple[]";
+    }, {
+        readonly internalType: "address payable";
+        readonly name: "refundReceiver";
+        readonly type: "address";
+    }];
+    readonly name: "executeBatch";
+    readonly outputs: readonly [];
+    readonly stateMutability: "payable";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly internalType: "address";
+        readonly name: "owner";
+        readonly type: "address";
+    }];
+    readonly name: "nonces";
+    readonly outputs: readonly [{
+        readonly internalType: "uint256";
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}, {
+    readonly inputs: readonly [{
+        readonly components: readonly [{
+            readonly internalType: "address";
+            readonly name: "from";
+            readonly type: "address";
+        }, {
+            readonly internalType: "address";
+            readonly name: "to";
+            readonly type: "address";
+        }, {
+            readonly internalType: "uint256";
+            readonly name: "value";
+            readonly type: "uint256";
+        }, {
+            readonly internalType: "uint256";
+            readonly name: "gas";
+            readonly type: "uint256";
+        }, {
+            readonly internalType: "uint48";
+            readonly name: "deadline";
+            readonly type: "uint48";
+        }, {
+            readonly internalType: "bytes";
+            readonly name: "data";
+            readonly type: "bytes";
+        }, {
+            readonly internalType: "bytes";
+            readonly name: "signature";
+            readonly type: "bytes";
+        }];
+        readonly internalType: "struct ERC2771Forwarder.ForwardRequestData";
+        readonly name: "request";
+        readonly type: "tuple";
+    }];
+    readonly name: "verify";
+    readonly outputs: readonly [{
+        readonly internalType: "bool";
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}];