Your data stays with you. One hook seals each access.
Saksi never copies a register or a customer table. Where an officer opens a citizen record, your backend makes one call to Saksi, signs one transaction with your own key, and the citizen’s phone gets a receipt it can check against Sepolia.
- Start: Agency
Agency system
An officer opens a citizen record. Your hook fires in that same code path.
- Step 1: Saksi
Saksi API prepares
Your backend sends the citizen code, purpose and legal basis. Saksi returns what to sign.
- Step 2: Agency
The agency signs
logAccess goes out from your registered wallet or HSM. Saksi never holds the key.
- Step 3: Saksi, then the citizen
Saksi seals and notifies the citizen
Saksi checks the transaction on the public ledger. The citizen’s phone gets a receipt it can check.
- What Saksi receives
- A 6-character citizen code, the purpose, the legal basis. Never a NIK or a name.
- Who signs
- Your registered wallet or HSM. Saksi cannot forge or hide an entry for you.
- What it costs you
- One API call and one transaction per access. No database link, no data export.
Six steps. One signature, and it is yours.
The hook belongs in the code path that opens the record, not in a nightly report: Saksi can only witness what the hook reports. Prepare and sign are synchronous; submit and confirm can run in a background job.
An officer opens a citizen record
Prepare the commitment
POST /access/prepare
citizen code · purpose · basis · event
id · submitToken · args
Sign with your registered key
logAccess(args)
your wallet or HSM signs; Saksi never holds the key
Submit the transaction hash
POST /access/submit
id · txHash · submitToken
reads the tx
contract · args · signer
Confirm once mined
POST /access/confirm
anchored
The citizen gets the receipt
verified in the browser
Watch reconciles chain vs database
An officer opens a citizen record
Your system · your hook fires
Prepare the commitment
- Your system → Saksi APIPOST /access/preparecitizen code · purpose · basis · event
- Saksi API ⇠ Your systemid · submitToken · args
Sign with your registered key
- Your system → SepolialogAccess(args)your wallet or HSM signs; Saksi never holds the key
Submit the transaction hash
- Your system → Saksi APIPOST /access/submitid · txHash · submitToken
- Saksi API ⇠ Sepoliareads the txcontract · args · signer
Confirm once mined
- Your system → Saksi APIPOST /access/confirm
- Saksi API ⇠ Your systemanchored
The citizen gets the receipt
- Sepolia → Citizen · Regulatorverified in the browserWatch reconciles chain vs database
What goes on chain. What stays with you.
On Sepolia, public
The AccessLogged event. Anyone can read who acted, what kind of access, on what basis and when. Whose record and why are hashes that only the citizen’s receipt opens.
controllerIdbytes32
Who accessed. keccak256("ctrl:" + slug), bound to one wallet in ControllerRegistry.
subjectPseudonymbytes32
Whose record. An HMAC of the citizen with a per-controller salt, so two agencies’ entries for one person cannot be linked.
purposeHashbytes32
Why. keccak256 of the purpose text and a random salt.
legalBasisKeybytes32
On what basis. The UU PDP Art. 20(2) key, PDP-20-2-a to f, as text.
eventTypeuint8
What was done. 0 read, 1 update, 2 export, 3 shared with a third party.
evidenceHashbytes32
keccak256 of the canonical JSON evidence descriptor: system, data categories, officer reference, request time and a nonce.
timestampuint64
When. The block time, set by the chain, not by you or Saksi.
Never leaves your system
- Citizen name
- NIK and other ID numbers
- The record the officer opened
- Your database and its schema
- Your signing key
Held by Saksi, encrypted
AES-256-GCM at rest, opened only to show the citizen their own receipt and let the phone recompute the hashes.
- Purpose text
- Purpose salt
- Evidence descriptor
- Citizen code ↔ pseudonym salt
The evidence descriptor is built from what your backend sends (system, data categories, officer reference); Saksi adds the request time and a random nonce before hashing it.
The whole hook. One file, plain viem.
The same flow the controller console runs in the browser, written for a backend. There is no API key: prepare returns a submitToken bound to the draft, and the only credential that matters is the signature from the wallet registered for your controller.
- 1
prepare· Commitments and a draft token. - 2
logAccess· Signed by your key, sent to the journal. - 3
submit· Saksi checks contract, arguments and signer on chain. - 4
confirm· Poll until anchored.
seal-access.tsTypeScript
import { createWalletClient, http, type Hex } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
import { sepolia } from 'viem/chains'
import { accessAbi } from './abi' // generated from AccessJournal.sol (web/lib/shared/abi.ts)
const SAKSI_URL = 'https://saksiku.web.id'
const JOURNAL = '0xAb9b73586610697deb7Ae59A59e991f5177CB263' // AccessJournal on Sepolia
const CONTROLLER_ID = process.env.CONTROLLER_ID as Hex // keccak256("ctrl:" + slug), bound to your key on chain
// Any viem account works: a local key, or one backed by your HSM or cloud KMS.
const account = privateKeyToAccount(process.env.CONTROLLER_PRIVATE_KEY as Hex)
const wallet = createWalletClient({ account, chain: sepolia, transport: http(process.env.RPC_URL) })
type Prepared = { id: string; submitToken: string; args: readonly [Hex, Hex, Hex, Hex, number, Hex] }
type Confirmed = { status: 'submitted' | 'anchored' | 'failed'; reason?: string }
// Errors come back as { error: { code, message } }. Server-to-server calls send no Origin header: accepted.
async function saksi<T>(action: 'prepare' | 'submit' | 'confirm', body: object): Promise<T> {
const res = await fetch(`${SAKSI_URL}/api/controller/access/${action}`, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify(body),
})
const data = await res.json()
if (!res.ok) throw Object.assign(new Error(data.error.message), { code: data.error.code as string })
return data as T
}
// TX_NOT_VISIBLE: Saksi's RPCs have not seen the broadcast yet. TX_MISMATCH, TX_NOT_AUTHORIZED: final.
const RETRYABLE = new Set(['TX_NOT_VISIBLE', 'UNAVAILABLE', 'RATE_LIMITED'])
async function retrying<T>(step: () => Promise<T | undefined>): Promise<T> {
const deadline = Date.now() + 180_000
while (Date.now() < deadline) {
try {
const value = await step()
if (value !== undefined) return value
} catch (error) {
if (!RETRYABLE.has((error as { code?: string }).code ?? '')) throw error
}
await new Promise((resolve) => setTimeout(resolve, 3_000))
}
throw new Error('Sepolia is slow right now; call confirm again later.')
}
type DataCategory = 'identity' | 'address' | 'contact' | 'financial' | 'health' | 'employment' | 'biometric' | 'other'
// Call this from the code path that opens a citizen record.
export async function sealAccess(citizenCode: string, purposeText: string, dataCategories: DataCategory[], operatorRef = 'officer') {
// 1. Saksi returns commitments only, plus a token bound to this draft.
const { id, submitToken, args } = await saksi<Prepared>('prepare', {
controllerId: CONTROLLER_ID,
subjectCode: citizenCode, // the citizen's Saksi code, never a NIK
purposeText, // shown to the citizen; only its salted hash goes on chain
legalBasisKey: 'PDP-20-2-e', // UU PDP Art. 20(2)(e): public task
eventType: 0, // 0 READ · 1 UPDATE · 2 EXPORT · 3 SHARE_THIRD_PARTY
system: 'agency-backend', // where the record was opened; omit it and Saksi uses your registered name
dataCategories, // e.g. ['identity', 'health']: what the officer opened, shown on the citizen's receipt
operatorRef, // a desk or role reference, never a name
})
// 2. Your key signs. Saksi never holds it, so it can neither forge nor hide your entries.
const txHash = await wallet.writeContract({ address: JOURNAL, abi: accessAbi, functionName: 'logAccess', args })
// 3. Saksi checks Sepolia: same contract, same arguments, sent by your registered wallet.
await retrying(() => saksi('submit', { id, txHash, submitToken }))
// 4. "submitted" = not mined yet. "anchored" = the citizen's receipt is live.
const result = await retrying(async () => {
const answer = await saksi<Confirmed>('confirm', { id })
return answer.status === 'submitted' ? undefined : answer
})
if (result.status !== 'anchored') throw new Error(result.reason)
return { id, txHash }
}
prepare with curlShell
curl -X POST https://saksiku.web.id/api/controller/access/prepare \
-H 'content-type: application/json' \
-d '{
"controllerId": "0xa0e63a2e54ad8e184af15ab8f53025356b84a9f1dfd53302c09ffe6d85a51454",
"subjectCode": "JVHULK",
"purposeText": "Officer opened the record to process a service request",
"legalBasisKey": "PDP-20-2-e",
"eventType": 0,
"system": "agency-backend",
"dataCategories": ["identity", "contact"],
"operatorRef": "officer"
}'201 response, annotatedJSON
HTTP/1.1 201 Created
{
"id": "4c21a490-f991-4fc9-8af5-da591968d586",
"submitToken": "<43-character token, echo it to submit>",
"args": [
"0xa0e63a2e54ad8e184af15ab8f53025356b84a9f1dfd53302c09ffe6d85a51454",
"0x…", // subjectPseudonym
"0x…", // purposeHash
"0x5044502d32302d322d6500000000000000000000000000000000000000000000",
0,
"0x…" // evidenceHash
]
}run the full exampleShell
cd web
CONTROLLER_PRIVATE_KEY=0x… \
CONTROLLER_SLUG=rsud-contoh \
CITIZEN_CODE=JVHULK \
DATA_CATEGORIES=identity,health \
SYSTEM=SIMRS OPERATOR_REF=desk-07 \
node scripts/agency-example.mjsweb/scripts/agency-example.mjs reads the ABI generated from the contracts and the deployed addresses from the repo. The key is read from the environment and never printed.output against productionOutput
prepared 51fef091-ee5a-4c0c-90e7-8df9199b4f27 (SIMRS · identity, health · desk-07)
sent 0xb181…3acd
submitted
anchored block 12183248
proof https://saksiku.web.id/proof/0xb181a685ade923fe8ccbfe93a5ccfdf6b7e5296e6165818a7caa278cbd8a3acd/64Errors
Every error is { error: { code, message } }; the message is plain English and safe to show an officer.
TX_NOT_VISIBLERetry
409 · submit
Saksi’s RPCs have not seen the broadcast yet.
TX_MISMATCHStop
400 · submit
The tx is not logAccess on the journal with exactly the prepared arguments.
TX_NOT_AUTHORIZEDStop
403 · submit
The sending wallet is not registered for this controller.
SUBMIT_TOKEN_INVALIDStop
403 · submit
The token does not belong to this draft. Prepare again.
UNKNOWN_CITIZENStop
404 · prepare
No citizen with that Saksi code.
UNKNOWN_CONTROLLERStop
404 · prepare
The controller id is not registered on Sepolia.
BAD_ORIGINStop
403 · any POST
A browser on another origin. Call from your backend instead.
RATE_LIMITEDRetry
429 · prepare
Too many drafts from this network this minute.
UNAVAILABLERetry
503 · any
Database or RPC hiccup on Saksi’s side.
API reference. Public, JSON, no key.
POSTs take application/json. A browser on another origin is refused with BAD_ORIGIN; calls from your backend carry no Origin header and are accepted.
Access receipts
The hook. Prepare is open and rate-limited (20 drafts a minute per network); submit needs the submitToken that prepare returned.
POST
/api/controller/access/prepareDraft one access. Returns id, submitToken and the six logAccess arguments.
POST
/api/controller/access/submitAttach the signed tx. Rejected unless Sepolia shows a matching logAccess from your registered wallet.
POST
/api/controller/access/confirmPoll until anchored. Answers submitted, anchored, or failed with a reason.
GET
/api/controller/access/recent?controllerId=Your last ten signed records, citizen code masked to two characters.
Breach notices
Same three steps, signed to BreachReport.anchor, or anchorLate once the 72 hours have passed.
POST
/api/controller/breach/prepareDraft a UU PDP Art. 46 notice. Returns the anchor arguments, mode and deadline.
POST
/api/controller/breach/submitAttach the signed anchor or anchorLate transaction.
POST
/api/controller/breach/confirmPoll until anchored. Returns on_time or late, with lateBySec.
Public reads
No session, no key. What a regulator or journalist can check without asking you.
GET
/api/watch?controllerId=Every chain event reconciled with the database row: MATCH, ALTERED, DELETED, NOT_ANCHORED.
GET
/api/regulator/breachesSealed breach notices with on-time and late counts.
GET
/api/statsCitizens, sealed receipts, last seal time, recent records masked.
Contracts on Sepolia
The registry binds each controller id to one wallet; the journal refuses any other sender.
- 0xAb9b73586610697deb7Ae59A59e991f5177CB263
AccessJournal
logAccess(bytes32,bytes32,bytes32,bytes32,uint8,bytes32)
- 0x3d9dE4717a7398d24239b8370b23DCAd7a07f737
ControllerRegistry
isAuthorized(bytes32,address) → bool
- 0x71Ff16F068A845F3D3dfd63584a31A9de86fE462
BreachReport
anchor(…) · anchorLate(…)
Who connects first. And where the hook goes.
Lenders and banks under OJK
POJK 40/2024 already asks P2P lenders for non-repudiation when personal data is accessed and an audit trail usable for supervision and disputes. OJK logged 56,620 consumer complaints in 2025, 21,886 of them about fintech and 20,972 about banks.
Hook:The customer-data screen in the loan or core-banking back office.
Public registers
Government administration made up 58.34% of the Indonesian records BSSN found on the dark web in 2024. When NPWP data was alleged to have leaked, the only answer available was the tax office’s own six years of logs. Estonia has shown citizens who opened their register data since 2017.
Hook:The officer’s record lookup in the register application.
Every controller under UU PDP
Article 31 already requires a record of all processing, and the agency meant to enforce the law had not been formed by November 2026. A sealed record lets anyone check it without waiting for one.
Hook:Wherever the existing Art. 31 processing log is written today.