Skip to content
INK Protocol

Versioning & Compatibility

INK versions its wire format with a ink/<major>.<minor> string carried in the protocol field of each object. Major versions are incremented for incompatible wire changes; minor versions for backward-compatible additions. The ink/0.2 minor is scoped to the intent envelope and its body-signature negotiation. The Agent Card, handshake message, inclusion receipt, audit-query-response and encrypted outer envelope have frozen per-surface schemas that accept only ink/0.1 and reject ink/0.2.

Current wire version

ink/0.2 is the current defined wire version and the recommended target for new receiver implementations. It is a backward-compatible minor over ink/0.1 on the intent envelope, changing only the body-signature domain: the neutral ink/sign in place of the legacy tulpa/sign, selected from the signed protocol field. Everything else, including the transport-auth signature base (whose first line is the fixed literal ink/0.1 on every request), the envelope shape and the encryption, audit and receipt sub-protocols, is identical to ink/0.1.

ink/0.1 remains fully supported. Both versions are major version 0, and a conformant major-0 receiver accepts either on the intent envelope. The non-intent surfaces named above stay ink/0.1.

What a receiver must accept

The shipped envelope schema is strict about which version strings it accepts:

  • The envelope protocol field is a strict enum accepting only ink/0.1 and ink/0.2.
  • A receiver MUST reject any other protocol version, including an unrecognized minor within major 0. There is no “accept any minor” fallthrough.
  • A receiver verifies both body-signature domains, so a ink/0.1 and a ink/0.2 envelope both verify on the same receiver.

Because the body-signature domain is keyed off the signed protocol field, relabelling an envelope from one version to another breaks its signature. A receiver never tries an alternate domain, so a signature minted under one version is never accepted under another.

Will ink/0.1 be dropped?

No, not within major 0. A version is sunset only at the major boundary, with the notice process described in the compatibility policy. There is no plan to drop ink/0.1 while major 0 is supported, and a new receiver that verifies both domains needs no migration when peers move to ink/0.2.

What senders emit today

Sending is receiver-first. A sender emits ink/0.1 by default and only emits ink/0.2 on the intent envelope, to a receiver that advertises ink/0.2 in its Agent Card supportedProtocolVersions. So adopting ink/0.2 on the receive side is safe and additive: you gain the ability to verify ink/0.2 envelopes without changing what you send.

The package version is not the wire version

Two numbers move independently, and they are easy to conflate.

  • The wire version is the ink/<major>.<minor> string in the protocol field. It changes only when the bytes on the wire change, and everything above on this page is about it.
  • The package version of @adastracomputing/ink is the library’s own semantic version. It moves on releases that change no wire behavior at all: a new conformance category, a bug fix, a new export.

Library releases regularly add normative rules that are not wire-version changes. The raw-body UTF-8 rule on the signed-body profile (Canonicalization) and inbound acceptance of the ink: agentId alias alongside the canonical tulpa: prefix (Identity) both arrived this way: they bind a receiver, and neither one alters the protocol field or the set of version strings a receiver accepts.

A receiver that says “we are on the latest package” has not said which wire versions it verifies. Advertise the wire versions in the Agent Card supportedProtocolVersions array, and make conformance claims against a profile and a set of declared capabilities. See Test Vectors.

Dist-tags on npm

The @adastracomputing/ink package uses two npm dist-tags, and they are policy, not fixed numbers.

  • latest is the release a bare npm install @adastracomputing/ink resolves to. A version is promoted to latest only after it has been validated against the conformance corpus, so it is the tag to depend on in production.
  • next is the most recent published release, promoted or not. npm install @adastracomputing/ink@next is how you get a release that is still being validated, and how implementers pick up a new conformance category before it becomes the default.

The two tags routinely point at different versions, and next is never behind latest. Neither tag is a statement about the wire version: a next release can be wire-identical to latest.

To see the current values, ask npm rather than a document:

Terminal window
npm view @adastracomputing/ink dist-tags

Release notes for each version are in the INK repository.

For the normative compatibility rules, see the compatibility policy.