VXPVerifiable eXchange Protocol Draft 0.1

VXP docs · draft 0.1

Quickstart

From a clean clone to a company and a personal agent in separate processes, an operation with its proof verified, a company-initiated request answered, and a conformance report, with no Poppy, no PACT and no SOVRAS service.

Requirements#

  • Node.js 22.18 or newer. Nothing to install with npm: the repository has no dependencies.
  • Python 3 with cryptography, for the Python verifier: python3 -m pip install cryptography (inside a virtual environment, python3 -m venv .venv && . .venv/bin/activate, where the system's Python refuses packages).
  • Git.
Clonesh
git clone https://github.com/vxp-protocol/vxp.git
cd vxp

The commands below are for bash: Linux, macOS, WSL or Git Bash on Windows. Where python3 does not exist, as in Git Bash, use python.

1. Start a company#

The reference implementation serves fictitious test companies and tells them apart by host name: Ferretería Demo at localhost:3100 and Hotel Demo at 127.0.0.1:3100. They are Chilean, so their pages and messages are in Spanish. Start it as a native-only gateway, with persistent keys outside the repository, and with the company's channel printed to the console (the channel is simulated: it stands for the SMS or WhatsApp line through which a real company would reach its customer).

Terminal 1 · the companysh
cd reference
VXP_ADAPTERS=none VXP_KEYS_DIR=/tmp/vxp-keys VXP_SHOW_CHANNEL=1 \
  ORIGENES_LOCALES=http://localhost:3811 node src/main.ts

ORIGENES_LOCALES lets the gateway fetch your agent's documents over plain http on localhost. In production both sides use https. Check it from another terminal:

Discoverysh
curl http://127.0.0.1:3100/.well-known/vxp.json

You get the hotel's vxp.json: its issuer, its /v1 endpoint and its capabilities, with "status": "experimental".

2. Run a personal agent#

The agent is another process with its own identity, its own keys and its own HTTP server for the documents companies fetch and for the inbox. The example does the task of the agent guide: a hotel in Santiago, two nights with breakfast, up to CLP 250,000 (printed as $250.000).

Terminal 1 prints an internal key for the reference's test console (llave interna: …). Pass it to the agent, so that step 4 can run at once:

Terminal 2 · the agentsh
cd agent
KEY=<the value printed after "llave interna:" in Terminal 1>
node examples/hotel-santiago.ts --state /tmp/vxp-agent --origin http://localhost:3811 --port 3811 \
  --allow-http http://localhost:3100,http://127.0.0.1:3100,http://localhost:3811 \
  --hotel-console http://localhost:3100 --hotel-console-key "$KEY" \
  localhost:3100 127.0.0.1:3100 localhost:3999

The last three arguments are candidate domains: VXP has no registry, so the agent starts from domains the person names or finds. The agent then:

  1. discovers which candidates speak VXP and which one offers bookings (the third one does not answer);
  2. records the person's rules: book up to CLP 250,000, and answer mantener (keep) to a late-arrival question;
  3. reads availability, rates and services, a public read with no consent;
  4. asks for the stay. The hotel answers authorization_required with exactly what to ask the person for.

The agent prints a link on the hotel's own page and waits. You are the person now: open the link, enter the test phone +56 9 0000 0101, enter the code that Terminal 1 prints as [simulated company channel …], read the consent and press “Permitir” (allow). The consent covers the booking up to CLP 250,000 and a relationship so the hotel can ask about a late arrival.

The agent continues on its own:

  1. sends the same request again with the same Idempotency-Key and receives signed terms;
  2. negotiates within the hotel's policy: a discretionary discount is refused, and the “Escapada” package lowers the total in a new revision;
  3. accepts that exact revision within your cap (approved_by: "standing_permission"). The hotel executes it once and reads its system back;
  4. downloads the proof and verifies it locally, anchored by the hotel's issuer.

3. Verify the proof yourself#

The agent saved what it verified in its state directory. Check the same package with the Python verifier, which shares no code with the agent's JavaScript verifier (its modes and flags are in Spanish: paquete is the package, operacion the operation):

From the repository rootsh
REQ=$(ls /tmp/vxp-agent/proofs/ | grep -m1 '.package.json' | sed 's/.package.json//')
python3 verifier/verificar_paquete.py material \
  --material /tmp/vxp-agent/proofs/$REQ.material.json \
  --paquete /tmp/vxp-agent/proofs/$REQ.package.json \
  --operacion /tmp/vxp-agent/proofs/$REQ.operation.json

Expected: "valid": true, "final_state": "succeeded" and "key_source": "issuer_metadata_saved", since the keys come from the material the agent saved. The terms travel signed inside each statement, so the way to see a mismatch is to change what the agent claims it was shown. Lower the total in the operation file and run the verifier again:

Claim different termssh
sed 's/"total": *230400/"total": 200000/' /tmp/vxp-agent/proofs/$REQ.operation.json > /tmp/claimed.json
python3 verifier/verificar_paquete.py material \
  --material /tmp/vxp-agent/proofs/$REQ.material.json \
  --paquete /tmp/vxp-agent/proofs/$REQ.package.json \
  --operacion /tmp/claimed.json

Expected: {"valid": false, "error": "operation_terms_mismatch", "seq": null}. To alter the signed statements themselves and see which link breaks, use the verifier in a browser. Verifier guide.

4. The company starts the next request#

The hotel's rule asks the guest's agent, inside the relationship, whether to hold or release a booking when the guest has not arrived after 20:00 on the arrival day (R17). The gateway checks every minute; the --hotel-console options of step 2 run the rule at once, with the reference's clock moved to that evening. Without them, the agent waits for the real evening.

The hotel signs a closed question and posts it to the agent's inbox. The agent verifies the signature with the key anchored to the issuer, rejects a repeated jti, answers mantener with the person's standing answer, and verifies the signed receipt. The /interno/ console is the reference's test-only console, standing in for the hotel's own clock; it is not part of VXP.

5. Run the conformance validator#

From the repository rootsh
node conformance/reference/run.ts --report conformance-report.json

It starts its own native-only reference company, acts as a personal agent against it, and reports every check with the rule it tests. Expected: {"pass":51,"fail":0,"optional":0,"manual":3,"skipped":0}. The report is in conformance-report.md. To check your own company, see Conformance.

Where next#

View as Markdown Source