VaultFactory + Vault

Every user gets their own Vault contract, deployed by VaultFactory. The platform deploys it for you (see Backend auto-deploy); a deposit does not create it, because depositERC20 is called on the vault itself. Each vault is a full, non-upgradeable contract, not a proxy. Its address is assigned at deploy time (plain CREATE, not CREATE2), so read it from vaultOf(user) rather than computing it.

VaultFactory

function deployVault(address user) external returns (address vault);
function vaultOf(address user) external view returns (address);

deployVault is not idempotent — it reverts with VaultAlreadyExists(user) (selector 0x4293864f) if the wallet already has a vault. The platform deploys partner vaults automatically (Backend auto-deploy), so integration code should only read vaultOf(user) (or poll GET /api/me/vault) and never call deployVault itself.
At creation the vault is initialised with vaultOwner = user and max USDC + ERC-1155 approvals to CTFExchange, ConditionalTokens, NegRiskAdapter and NegRiskCtfExchange.

Bootstrap: vault → deposit

// 1. Wait for the platform to deploy your vault
//    (GET /api/me/vault → deployed: true), then read it from chain.
//    Do not call deployVault: the platform deploys the vault for you,
//    and the call reverts with VaultAlreadyExists once a vault exists.
const vault = await vaultFactory.vaultOf(eoa);
if (vault === ZeroAddress) throw new Error('vault not deployed yet');

// 2. Approve USDC and deposit into the vault
await (await usdc.connect(user).approve(vault, parseUnits('1000', 6))).wait();
await (await new Contract(
  vault,
  ['function depositERC20(address token, uint256 amount)'],
  user,
).depositERC20(usdc.target, parseUnits('1000', 6))).wait();

Per-EOA deposit limits in DepositLimitRegistry are set by the platform — partners do not initialise them. This is a separate step from the vault deploy, so deployed: true alone does not mean the vault accepts deposits: until the platform has assigned your EOA a deposit tier, depositERC20 reverts with KycRequired() (selector 0x709ea86e). Before the first deposit, poll GET /api/me/deposit-limits until restrictions.depositBlocked is false.

Vault entry points

The calls below require two EIP-712 signatures (the vault owner’s plus a platform backend co-signature). msg.sender is unconstrained.

Function	Purpose
`withdrawERC20(token, to, amount, salt, deadline, ownerSig, backendSig)`	External withdrawal
`splitPosition(kind, collateral, conditionId, partition, amount, salt, deadline, ownerSig, backendSig)`	Mint full outcome set inside the vault
`mergePositions(...)`	Collapse outcome set → collateral
`convertPositions(marketId, indexSet, amount, salt, deadline, ownerSig, backendSig)`	Neg-risk NO-basket conversion. The `negRiskAdapter` reference is held as a constructor-set immutable on the vault, so it is not part of the signed struct, which carries only `marketId`, `indexSet`, `amount`, `salt` and `deadline`.

There is no ERC-1155 withdraw. Outcome tokens leave the vault by trading, by mergePositions followed by withdrawERC20, by redemption after resolution, or through the emergency withdraw.

Splitting USDC into YES + NO inside the vault

SELL orders need the outcome ERC-1155 to live in the vault: at settlement the exchange debits the tokens from the order’s maker vault, so they must be there, not in your EOA. The supported flow is:

Backend co-signature. POST /api/vault/split-signature with { marketId, amount }. Body of response carries the dual-sig payload the vault expects:

{
  "signedOpId":      "...",
  "digest":          "0x...",
  "kind":            0,
  "collateralToken": "0x9bC8...241e1",
  "conditionId":     "0x...",
  "partition":       ["1", "2"],
  "amount":          "30000000",
  "salt":            "...",
  "deadline":        1776999999,
  "vaultAddress":    "0x...",
  "backendSig":      "0x..."
}

Owner signature. Sign the same SplitPosition typed-data with the vault EIP-712 domain (see below) using the EOA key.
On-chain submit. Call vault.splitPosition(kind, collateral, conditionId, partition, amount, salt, deadline, ownerSig, backendSig).

After the tx confirms, the vault holds equal balances of YES and NO ERC-1155 for conditionId, and SELL orders on either outcome become possible.

Merging YES + NO back into USDC

mergePositions is the inverse of splitPosition: it burns equal units of every outcome ERC-1155 inside the vault and returns the matching USDC. Useful for closing a hedged position before resolution, freeing locked outcome tokens back into spendable USDC, or just exiting a market early without waiting for the oracle. The flow mirrors split:

Backend co-signature. POST /api/vault/merge-signature with { marketId, amount }. Response shape is identical to split’s:

{
  "signedOpId":      "...",
  "digest":          "0x...",
  "kind":            0,
  "collateralToken": "0x9bC8...241e1",
  "conditionId":     "0x...",
  "partition":       ["1", "2"],
  "amount":          "30000000",
  "salt":            "...",
  "deadline":        1776999999,
  "vaultAddress":    "0x...",
  "backendSig":      "0x..."
}

Owner signature. Sign the same MergePositions typed-data with the vault EIP-712 domain. The struct field shape is identical to SplitPosition (same 7 fields); only the EIP-712 primary type changes from SplitPosition → MergePositions. Use type table below.
On-chain submit. Call vault.mergePositions(kind, collateral, conditionId, partition, amount, salt, deadline, ownerSig, backendSig).

After the tx confirms, the vault burns amount of each outcome’s ERC-1155 and credits amount USDC; the platform reflects the balance change with ~1-block lag and your /api/me/balances shows available += amount. Both SplitPosition and MergePositions use the same EIP-712 type shape on chain:

{
  "<SplitPosition or MergePositions>": [
    { "name": "kind",            "type": "uint8"     },
    { "name": "collateralToken", "type": "address"   },
    { "name": "conditionId",     "type": "bytes32"   },
    { "name": "partition",       "type": "uint256[]" },
    { "name": "amount",          "type": "uint256"   },
    { "name": "salt",            "type": "uint256"   },
    { "name": "deadline",        "type": "uint256"   }
  ]
}

The partition is always [1, 2] (YES + NO of one condition). kind is 0 on binary markets and 1 on neg-risk markets. On a neg-risk market each outcome is its own YES / NO question: send outcomeIndex to POST /api/vault/split-signature / merge-signature to pick it (without it: 400 outcome_index_required), and the signed conditionId is that outcome’s condition.

Emergency withdraw

initiateEmergencyWithdraw()            // vault owner only; starts the 7-day timelock
// ... wait 7 days, then within the following 7 days:
emergencyWithdrawERC20(token)          // sends the vault's full `token` balance to the vault owner
emergencyWithdrawERC1155(token, id)    // sends the vault's full balance of position `id` to the vault owner

Call these from the vault-owner EOA. No signatures are involved. The emergency is one-way: neither the platform nor anyone else can cancel it. While the timelock or the execution window is running, the exchange rejects orders from your vault. If the 7-day execution window lapses, call initiateEmergencyWithdraw() again.

Digest invalidation

invalidateDigest(bytes32 digest) external;             // vault owner or platform backend
invalidateDigests(bytes32[] calldata digests) external;

Cancels a dual-signed operation (withdraw, split, merge, convert) before it is submitted by marking its digest used. Either signer can do it: the vault owner or the platform backend; anyone else gets NotOwner(). invalidateDigest reverts DigestAlreadyUsed() on a digest that was already consumed; the batch form skips those.

Why a non-upgradeable per-user vault

Non-upgradeable — the vault bytecode is fixed in the factory when the factory is deployed; no admin can hot-patch or swap it.
Bug mitigation requires a new factory + user-driven emergency withdraw.

EIP-712 domain

name: "PredictStreetVault"
version: "1"
chainId: <chain>
verifyingContract: <your vault address>

Note verifyingContract is the vault address, not the factory.

Getting Started

Authentication

Vaults

Deposits

Trading

Events & Tags

Markets

Portfolio

Withdrawals

WebSocket

Settlement & Oracle

On-chain Contracts

Partners

Errors

VaultFactory

Bootstrap: vault → deposit

Vault entry points

Splitting USDC into YES + NO inside the vault

Merging YES + NO back into USDC

Emergency withdraw

Digest invalidation

Why a non-upgradeable per-user vault

EIP-712 domain

​VaultFactory

​Bootstrap: vault → deposit

​Vault entry points

​Splitting USDC into YES + NO inside the vault

​Merging YES + NO back into USDC

​Emergency withdraw

​Digest invalidation

​Why a non-upgradeable per-user vault

​EIP-712 domain

VaultFactory

Bootstrap: vault → deposit

Vault entry points

Splitting USDC into YES + NO inside the vault

Merging YES + NO back into USDC

Emergency withdraw

Digest invalidation

Why a non-upgradeable per-user vault

EIP-712 domain