114 lines
4.3 KiB
Markdown
114 lines
4.3 KiB
Markdown
# P2Pix zkTLS prover
|
|
|
|
Proves that a BB Pay Pix charge was paid by having a Primus attestor replay
|
|
the bank's own `GET /solicitacoes/{n}` over zkTLS. The attestor signs what
|
|
the bank answered: the request URL and five revealed fields (amount, settled
|
|
sum, payee, Pix `txId`, reconciliation code). The P2Pix contract verifies
|
|
that signature and the fields in `release(lockID, proof)`. The charge is
|
|
bound to P2Pix's convênio only through the `numeroConvenio` query of the
|
|
attested URL, so the contract's URL suffix must be pinned to the URL exactly
|
|
as the attestor records it. The prover holds no signing key of its own.
|
|
|
|
## Variáveis de ambiente (`.env`, ver `.env.example`)
|
|
|
|
- `CLIENT_ID`, `CLIENT_SECRET`, `DEV_APP_KEY`, `CONVENIO`: fornecidas pelo Banco do Brasil
|
|
- `ITP_OAUTH_URL`, `ITP_API_URL`: endpoints BB Pay (homologação ou produção)
|
|
- `CLIENT_CRT`, `CLIENT_KEY`: certificado cliente mTLS e sua chave privada (PEM)
|
|
- `PRIVATE_KEY`: carteira que paga as tarefas Primus (ETH na `PRIMUS_CHAIN_ID`, Base Sepolia por padrão); o endereço dela é o `recipient` da atestação e tem que ser o `prover` configurado no contrato
|
|
|
|
## Como rodar
|
|
|
|
```
|
|
bun install # ou npm install
|
|
bun start # ou npm start
|
|
```
|
|
|
|
`DEBUG=true` liga os logs, inclusive o registro completo de cada atestação
|
|
(request, resolves, data, attConditions, additionParams, verificação).
|
|
|
|
## Endpoints
|
|
|
|
### POST /register
|
|
|
|
Registra um participante. Chamado pelo vendedor antes do `deposit`.
|
|
|
|
```
|
|
curl -X POST http://localhost:5000/register -H 'content-type: application/json' -d '{
|
|
"chainID": "11155111", "tipoDocumento": 1, "numeroDocumento": 12345678900,
|
|
"numeroConta": 1234567890123456, "numeroAgencia": 123, "tipoConta": 1, "codigoIspb": 0
|
|
}'
|
|
```
|
|
|
|
Retorna a resposta do BB, com `numeroParticipante` (usado no `deposit` como `<chainId>-<numeroParticipante>`).
|
|
|
|
### POST /request
|
|
|
|
Cria a solicitação de pagamento. Chamado pelo comprador depois do `lock`.
|
|
`lockId` e `chainId` viram o código de conciliação `<chainId>-<lockId>`, que
|
|
o contrato exige na prova.
|
|
|
|
```
|
|
curl -X POST http://localhost:5000/request -H 'content-type: application/json' -d '{
|
|
"amount": 100.00, "pixTarget": 123, "lockId": "42", "chainId": "11155111"
|
|
}'
|
|
```
|
|
|
|
Retorna a resposta do BB mais `numeroSolicitacao` (string) e `textoQrCode`.
|
|
|
|
### GET /release/{numeroSolicitacao}
|
|
|
|
Prova de pagamento Pix. Chamado pelo comprador depois de pagar.
|
|
|
|
- `402` enquanto o banco não confirma o pagamento
|
|
- `202` enquanto a atestação está sendo produzida (15 s a 1 min)
|
|
- `200` com a prova
|
|
- `502` banco ou Primus falharam de forma definitiva; `503` vale repetir
|
|
|
|
```
|
|
curl -i http://localhost:5000/release/1408799
|
|
```
|
|
|
|
```
|
|
{
|
|
"numeroSolicitacao": "1408799",
|
|
"proof": {
|
|
"recipient": "0x…", "attestor": "0x…",
|
|
"data": "{\"amount\":\"100\",…}",
|
|
"timestamp": 1766377317483,
|
|
"additionParams": "{\"algorithmType\":\"proxytls\"}",
|
|
"attConditions": "",
|
|
"signature": "0x…", "taskId": "0x…", "reportTxHash": "0x…",
|
|
"requests": [{ "url": "…", "header": "", "method": "GET", "body": "" }],
|
|
"responseResolves": [[…]],
|
|
"selfVerified": true, "contractRebuildMatches": true
|
|
}
|
|
}
|
|
```
|
|
|
|
`release(lockID, proof)` takes `numeroSolicitacao`, `recipient`, `data`,
|
|
`timestamp`, `additionParams`, `attConditions`, `attestor` and `signature`;
|
|
the rest is evidence. `selfVerified` means the signature recovers the
|
|
attestor over the returned struct; `contractRebuildMatches` means the
|
|
contract's rebuild rules (empty header and body, `GET`) reproduce it.
|
|
|
|
`bun run digest-check <release-body.json>` recomputes the digest of a saved
|
|
answer and prints the URL, header, parseType and data layout the contract
|
|
constants are pinned to.
|
|
|
|
## mTLS
|
|
|
|
`CLIENT_CRT` is the certificate chain BB has on file for this application and
|
|
`CLIENT_KEY` its private key, both PEM. Register a dedicated client
|
|
certificate for the prover; the attested requests run through the Primus
|
|
attestor, so the key material should not be the company e-CNPJ. To extract a
|
|
key-only PEM from a PKCS#12 file:
|
|
|
|
```
|
|
umask 077
|
|
openssl pkcs12 -in <arquivo>.p12 -legacy -nocerts -noenc -out client.key
|
|
openssl pkcs12 -in <arquivo>.p12 -legacy -nokeys -out client.crt
|
|
```
|
|
|
|
The `*.mtls.api.*.bb.com.br` hosts present a publicly trusted chain, so no
|
|
extra CA is needed; set `BB_CA` only for hosts signed by BB's own CA.
|