Skip to main content

​
nexus_getVaultState

Get vault state for a user.
​
params[0]
string
required
User’s public key (hex)
​
result
object
Vault state including balances and pending withdrawals
curl -X POST http://localhost:9945 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"nexus_getVaultState","params":["0x1234..."],"id":1}'
Response
{
  "jsonrpc": "2.0",
  "result": {
    "l1_balance": 100000,
    "l2_balance": 50000,
    "pending_withdrawals": [],
    "vault_address": "bcrt1p..."
  },
  "id": 1
}

​
nexus_getVaultAddress

Get deposit vault address for an NEXUS address.
​
params[0]
string
required
NEXUS account address
​
result
object
Vault address information
curl -X POST http://localhost:9945 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"nexus_getVaultAddress","params":["bcrt1p..."],"id":1}'
Response
{
  "jsonrpc": "2.0",
  "result": {
    "vault_address": "bcrt1p...",
    "l2_address": "bcrt1p...",
    "protocol_key": "1234...",
    "timelock": 16128
  },
  "id": 1
}

​
nexus_deriveVaultFromPubkey

Derive vault address from public key.
​
params[0]
string
required
32-byte x-only public key (hex)
​
result
object
Derived vault address
curl -X POST http://localhost:9945 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"nexus_deriveVaultFromPubkey","params":["0x1234..."],"id":1}'

​
nexus_registerPubkey

Register a public key for vault derivation.
​
params[0]
string
required
32-byte x-only public key (hex)
​
result
object
Registration result
curl -X POST http://localhost:9945 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"nexus_registerPubkey","params":["0x1234..."],"id":1}'

​
nexus_requestWithdrawal

Request a withdrawal from NEXUS to L1.
​
params[0]
string
required
User’s public key
​
params[1]
string
required
Zcash destination address (t-addr: tmXxx on regtest, t1xxx on mainnet)
​
params[2]
number
required
Amount in zatoshi (1 ZEC = 100,000,000 zatoshi)
​
result
object
Withdrawal request result
curl -X POST http://localhost:9945 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"nexus_requestWithdrawal","params":["0x1234...", "bcrt1p...", 10000],"id":1}'

​
Vault Architecture

Zcash vaults use P2SH transparent addresses (t-addr) with two spending paths:

​
Protocol Path

Both the user key and protocol key are required (2-of-2). Used for normal deposits and withdrawals. L1 vault balance always equals NEXUS vZEC balance (1:1 backing).

​
Escape Path

Users can unilaterally recover funds after 16,128 blocks (~2 weeks at 75s/block) — no protocol permission needed. 
Zcash Vault (P2SH t-addr)
├── Normal Path: <ProtocolKey> + <UserKey> (2-of-2, instant)
└── Escape Path: <16128-block timelock> + <UserKey> (unilateral, ~2 weeks)
The escape path ensures users can always recover their funds, even if the protocol becomes unresponsive.