Skip to content

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.

How one access gets sealed
  1. Start: Agency

    Agency system

    An officer opens a citizen record. Your hook fires in that same code path.

  2. Step 1: Saksi

    Saksi API prepares

    Your backend sends the citizen code, purpose and legal basis. Saksi returns what to sign.

  3. Step 2: Agency

    The agency signs

    logAccess goes out from your registered wallet or HSM. Saksi never holds the key.

  4. 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.

  1. 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. 1prepare · Commitments and a draft token.
    2. 2logAccess · Signed by your key, sent to the journal.
    3. 3submit · Saksi checks contract, arguments and signer on chain.
    4. 4confirm · 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
      ]
    }
    args is exactly the logAccess argument list, in order. Pass it to the contract unchanged.

    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.mjs
    web/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/64

    Errors

    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/prepare

      Draft one access. Returns id, submitToken and the six logAccess arguments.

    • POST/api/controller/access/submit

      Attach the signed tx. Rejected unless Sepolia shows a matching logAccess from your registered wallet.

    • POST/api/controller/access/confirm

      Poll 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/prepare

      Draft a UU PDP Art. 46 notice. Returns the anchor arguments, mode and deadline.

    • POST/api/controller/breach/submit

      Attach the signed anchor or anchorLate transaction.

    • POST/api/controller/breach/confirm

      Poll 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/breaches

      Sealed breach notices with on-time and late counts.

    • GET/api/stats

      Citizens, 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.

    Who connects first. And where the hook goes.

    1. 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.

    2. 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.

    3. 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.