Skip to content
You are reading the Ratify Protocol v2 beta documentation. Protocol v1 remains available at the site root.

Upgrade from v1

v2 is not a drop-in upgrade. Keys, delegations, challenges, status, and the verifier call all change, and v1 proofs stay on a v1 verifier. This page follows the protocol’s upgrade guide, which also holds the full v1 to v2 concept map. Section numbers refer to SPEC-v2.

  • v2 is not backward compatible with v1. Signed bytes, key IDs, challenge signing, status references, and verifier ordering all differ. A v2 verifier rejects v1 objects, and there is no automatic fallback in either direction.
  • Migration is a clean re-enrollment. Generate fresh v2 keys and issue new v2 delegations. No v1 key can authorize a v2 key, and importing a v1 key into a v2 identity is prohibited.
  • Side by side is supported. v1 and v2 run together in one build or environment in every ecosystem. A deployment chooses the version explicitly at each API boundary and keeps a v1 verifier for v1 proofs until it retires them.
  • v1 stays available and pinned. Released v1 tags and artifacts are never moved or replaced, and v2 never widens a v1 dependency range. There is no fixed, dated v1 support window today; v1 support terms will be announced with 2.0.0.
  • Some capabilities stay on v1 until 2.1: the SessionToken fast path, A2A mutual presentation, the HTTP and registry bindings, and the geo and speed constraints. A claim that depends on one is a v1 claim. See v1-only until 2.1.

More detail: Is v2 compatible with v1?

ABI
SDKv2 (beta line)v1 (stays available)
Gogo get github.com/identities-ai/ratify-protocol/[email protected], import github.com/identities-ai/ratify-protocol/v2go get github.com/identities-ai/[email protected] (original module path)
TypeScriptnpm install @identities-ai/[email protected] (dist-tag next), import from @identities-ai/ratify-protocol/v2npm install @identities-ai/[email protected] (dist-tag latest)
Pythonpip install "ratify-protocol[protocol-v2]==2.0.0b2", import ratify_protocol.v2pip install ratify-protocol==1.0.0a21, import ratify_protocol
Rustcargo add [email protected], use ratify_protocol::v2ratify-protocol = "=1.0.0-alpha.21"
C/C++ratify-c 2.x release archive, or cargo build –release in sdks/c; include ratify.h, call ratify_v2_, check ratify_v2_abi_version()The 1.0.0-alpha.21 release archive and its ratify_
  • Go: the two lines have different module paths, so one module can require both and import them under different names, for example ratifyv1 and ratify.

  • TypeScript: the 2.x package exports v2 from the /v2 subpath and keeps the v1 API at the package root. To keep the exact v1 release as well, add an alias:

    Terminal window
    npm install ratify-v1@npm:@identities-ai/[email protected]

    An unpinned npm install resolves to v1 until 2.0.0.

  • Python: the 2.x distribution keeps the v1 API at ratify_protocol and adds ratify_protocol.v2, so one environment runs both, and import ratify_protocol never loads v2. The protocol-v2 extra brings v2’s requirements (the ratify-protocol-native-v2 signing backend and a pinned tzdata release); the base install keeps v1’s. The exact v1 release cannot sit next to 2.x in one environment because both use the same distribution name, so a process that must run the exact v1 release needs its own environment.

  • Rust: the 2.x crate keeps the v1 API at the crate root and adds ratify_protocol::v2. To keep the exact v1 release as well, rename it:

    ratify_v1 = { package = "ratify-protocol", version = "=1.0.0-alpha.21" }
  • C/C++: the 2.x library exports the unchanged v1 ratify_* ABI next to the ratify_v2_* ABI. Check ratify_v2_abi_version() at startup.

  1. Keep v1 running and pin it. Pin the exact v1 release you run today and keep its verifier for existing v1 proofs. Do not widen a v1 dependency range to include 2.x. Install v2 next to it on a test branch.

  2. Generate v2 keys and prove possession. Every principal (organization or person root, issuer, agent, verifier, status publisher) gets a fresh v2 hybrid key. Establish who owns each root out of band, have the holder prove possession of the new key, and configure trust as the complete root public key. Never pin trust to a key ID alone: the verifier recomputes the ID from the key you configured and fails closed on any mismatch or ambiguity. See Typed signing and key IDs.

  3. Reissue delegations with v2 constraint schemas. Use the typed signer (SignDelegationCertV2 or its external-signer form), which checks issuer duties before it signs.

    • Every certificate has a finite expires_at, at most 315360000 seconds (ten years) after issue. There is no no-expiry sentinel.
    • Amounts move from floats to integers: 50.00 USD is {"type":"max_amount","currency":"USD","max_amount_micros":50000000}, and the verifier receives the requested amount in the same unit.
    • A required custom: scope is one exact custom:<name> that every certificate in the chain lists. custom:* is invalid.
    • Application-specific constraints move to extension types evaluated by a registered profile: the standard com.ratifyprotocol.max_count/v1 and com.ratifyprotocol.allowed_values/v1, or your own versioned profile. A verifier without the profile fails closed with constraint_unknown.
    • geo_circle, geo_polygon, geo_bbox, and max_speed_mps have no v2.0 equivalent. Keep those delegations on v1 until 2.1, or bind the condition in application policy after release.

    See Delegation and constraints.

  4. Set up signed status with a separate status key. Give each issuer a status key distinct from every root, issuer, agent, and verifier key. Record key roles and the status key epoch in the SecurityJournalV2, and run the status publisher: a genesis list, heartbeats that refresh freshness, and revocations as a signed push plus the cumulative list. Persist the publisher state before you publish each object. This replaces v1 revocation callbacks; an unavailable or stale status yields indeterminate, never allow. See Status from signed evidence.

  5. Issue challenges with the issuance helper. It reads the authoritative clock, draws 32 random bytes, and persists the full record before it returns the challenge. The verifier loads the record by the presented challenge. Challenge lifetime is 1 to 300 seconds, and every deadline is exclusive. See One-time challenges and claims.

  6. Move verifiers to verify, commit, release. Call VerifyProofBundleV2 with the stored expected challenge, an explicit context policy, the required scope, the request context, the status keys and policy, and the evaluator registry. Publish the committed receipt body to your receipt log, wait for the checkpoint acknowledgement, and call ReleaseV2Decision. Gate each side effect on Allowed(clock) just before it runs. Move application policy (the v1 PolicyProvider role) to after release, where it may only narrow the decision. Map v1 statuses to the v2 decision, reason, and the 49 error classes (§2.7). See Committed vs. released.

  7. Supply durable Part B stores. The SDKs’ reference stores are in-memory and test-only. Production needs durable implementations of the claim store with an authoritative clock, the challenge issuance store, stream sequence and rate reservation, the receipt outbox and log, an independent checkpoint in a separate failure domain, and the anchored journal store with compare-and-swap. See Deployment profiles.

  8. Test before cutover. Run the SDK’s own suite against testvectors/v2, the lifecycle scenarios, and your deployment’s failure cases: status unavailable, checkpoint withheld, signer failure, clock regression, replay, and restore.

  9. Run side by side, then retire v1. Send a v1 proof to the v1 verifier and a v2 proof to the v2 verifier, with no fallback between them. Move issuers first so new delegations are v2, then move verifiers, then stop issuing v1 delegations. Remove the v1 verifier when no live v1 delegation remains. Retiring a hosted v1 endpoint does not revoke proofs that third-party offline verifiers may still accept, so revoke outstanding v1 delegations through the v1 status path first.

2.0.0 changes what an unpinned install resolves to. It changes no import path, so code written against 2.0.0-beta.2 needs no import change.

  • Import paths are permanent. v2 stays at github.com/identities-ai/ratify-protocol/v2, @identities-ai/ratify-protocol/v2, ratify_protocol.v2, ratify_protocol::v2, and the ratify_v2_* C ABI. The package roots keep the v1 API; nothing changes meaning under an existing import.
  • Default installs move to v2. npm latest moves to 2.0.0, a plain pip install ratify-protocol and cargo add ratify-protocol resolve to 2.0.0, and the GitHub release is marked latest.
  • Python’s v2 requirements join the base install. From 2.0.0, installing ratify-protocol also installs the v2 signing backend and the pinned tzdata release. The protocol-v2 extra stays accepted, so existing install commands keep working.
  • v1 stays installable. Released v1 versions are never moved or replaced. After 2.0.0, v1 maintenance releases publish to npm under the v1 dist-tag and never take latest back. Pinned v1 installs in every ecosystem are unaffected. v1 support terms will be announced with 2.0.0.

The before side is the v1 flow you run today. The after side is the v2 quickstart example, rendered from the protocol repository at a pinned commit.

Before (v1):

Terminal window
go get github.com/identities-ai/[email protected]

v1 calls: ratify.GenerateChallenge (verifier generates a challenge), ratify.Verify(bundle, opts) returning a result with Valid and IdentityStatus, and an optional RevocationProvider. Full v1 program: Go SDK, three minutes end to end.

After (v2):

Terminal window
go get github.com/identities-ai/ratify-protocol/[email protected]

v2 calls: V2ChallengeIssuer.IssueChallengeV2, VerifyProofBundleV2 (committed outcome), ReleaseV2Decision, then (*V2ReleasedDecision).Allowed(ctx, clock) before the side effect. Status comes from NewV2StatusPublisher.

examples/v2/go/quickstart/main.go
// Ratify Protocol v2 quickstart: delegate, present, verify, publish, release.
//
// DEVELOPMENT ONLY. This program uses the in-memory reference stores from
// package v2reference (claim store, receipt log, checkpoint, journal and
// challenge issuance store). They exist for tests and examples. A production
// verifier supplies durable Part B stores and an independent checkpoint
// (SPEC-v2 §7).
//
// Run from the repository root: go run ./examples/v2/go/quickstart
package main
import (
"context"
"fmt"
"os"
"strings"
ratify "github.com/identities-ai/ratify-protocol/v2"
"github.com/identities-ai/ratify-protocol/v2/v2reference"
)
const (
start = int64(1800000000) // fixed clock so the output is reproducible
namespace = "quickstart"
epoch = int64(1)
logID = "00000000000000000000000000000001"
)
func main() {
if err := run(); err != nil {
fmt.Fprintln(os.Stderr, "error:", err)
os.Exit(1)
}
}
func run() error {
ctx := context.Background()
fmt.Println("Ratify Protocol v2 quickstart")
fmt.Println("development only: in-memory reference stores")
// 1. Keys. Every party holds a hybrid Ed25519 + ML-DSA-65 key. The status
// key is separate from the root key that issues delegations.
rootPub, rootPriv, err := ratify.GenerateHybridKeypair()
if err != nil {
return err
}
agentPub, agentPriv, err := ratify.GenerateHybridKeypair()
if err != nil {
return err
}
statusPub, statusPriv, err := ratify.GenerateHybridKeypair()
if err != nil {
return err
}
verifierPub, verifierPriv, err := ratify.GenerateHybridKeypair()
if err != nil {
return err
}
rootID, _ := ratify.KeyIDV2(rootPub)
agentID, _ := ratify.KeyIDV2(agentPub)
verifierID, _ := ratify.KeyIDV2(verifierPub)
fmt.Printf("keys: root, agent, status and verifier generated (key IDs are %d hex characters)\n", len(rootID))
// 2. The root delegates payments:send to the agent, capped at 50.00 USD
// per action (amounts are integer micro-units in v2).
cert, err := ratify.SignDelegationCertV2(&ratify.DelegationCertV2{
Version: 2, CertID: "quickstart-cert-1",
IssuerID: rootID, IssuerPubKey: rootPub,
SubjectID: agentID, SubjectPubKey: agentPub,
Scope: []string{"payments:send"},
Constraints: []ratify.ConstraintV2{
{Type: ratify.ConstraintMaxAmount, Currency: "USD", MaxAmountMicros: 50_000_000},
},
IssuedAt: start, ExpiresAt: start + 86400,
}, rootPriv)
if err != nil {
return err
}
fmt.Println("delegation: scope=payments:send max_amount=50000000 USD micros lifetime=86400s")
// 3. Verifier state: the reference store is the claim store, receipt log,
// checkpoint and authoritative clock. The journal records key roles and
// the root's status key.
store, err := v2reference.NewStore(start, 30, logID, verifierPriv)
if err != nil {
return err
}
journal, err := v2reference.NewJournalStore()
if err != nil {
return err
}
for role, pub := range map[string]ratify.HybridPublicKey{"issuer": rootPub, "delegation": agentPub, "verifier": verifierPub} {
if _, err := ratify.RecordSecurityKeyRoleV2(ctx, journal, role, pub); err != nil {
return err
}
}
if _, err := ratify.ConfigureStatusKeyEpochV2(ctx, journal, rootID, 1, statusPub); err != nil {
return err
}
// 4. The root's status publisher signs a genesis revocation list (no
// revocations) under the separate status key.
publisher, err := ratify.NewV2StatusPublisherWithKey(ctx, journal, rootPub, statusPriv, 3600)
if err != nil {
return err
}
genesis, err := publisher.Genesis(ctx, start)
if err != nil {
return err
}
statusWire, err := ratify.EncodeRevocationListV2(genesis.List)
if err != nil {
return err
}
fmt.Printf("status: genesis list signed by the status key (sequence %d, %d revoked)\n", genesis.State.Sequence, len(genesis.State.Revoked))
// 5. The verifier issues a challenge. The helper persists the record
// before it returns the challenge.
issuance := v2reference.NewTestOnlyChallengeIssuanceStore()
issuer := ratify.V2ChallengeIssuer{Clock: store, Store: issuance}
challenge, err := issuer.IssueChallengeV2(ctx, ratify.V2ChallengeIssueRequest{
VerifierNamespace: namespace, ReplayEpoch: epoch, VerifierID: verifierID,
LifetimeSeconds: 120, ExpectedAgentID: agentID, ExpectedAgentPublicKey: &agentPub,
})
if err != nil {
return err
}
fmt.Printf("challenge: issued and persisted, expires in %ds\n", challenge.ExpiresAt-challenge.IssuedAt)
// 6. The agent signs a proof bundle over the challenge.
store.SetTime(start + 2)
bundle, err := ratify.SignProofBundleV2(&ratify.ProofBundleV2{
Version: 2, VerifierID: verifierID, AgentID: agentID, AgentPubKey: agentPub,
Delegations: []ratify.DelegationCertV2{*cert},
Challenge: challenge.Value, ChallengeAt: challenge.IssuedAt,
}, agentPriv)
if err != nil {
return err
}
bundleWire, err := ratify.EncodeProofBundleV2(bundle)
if err != nil {
return err
}
fmt.Printf("proof: agent signed the presentation (%d delegation)\n", len(bundle.Delegations))
// 7. Verify. The verifier loads the issuance record for the presented
// challenge, then runs the full v2 decision path.
verify := func() (ratify.V2VerifyOutcome, error) {
expected, err := ratify.LoadExpectedChallengeV2(ctx, issuance, namespace, epoch, bundle.Challenge)
if err != nil {
return ratify.V2VerifyOutcome{}, err
}
policy, err := ratify.NewV2ContextPolicy("example.quickstart/v1", false, nil, nil)
if err != nil {
return ratify.V2VerifyOutcome{}, err
}
req := ratify.V2VerifyRequest{
Bundle: bundleWire, Expected: expected, ContextPolicy: policy,
RequiredScope: "payments:send", VerifierNamespace: namespace, ReplayEpoch: epoch, VerifierID: verifierID,
Now: store.Now(), MaxChallengeAgeSeconds: 300, FutureSkewSeconds: 5,
Context: ratify.ConstraintContextV2{HasAmount: true, RequestedAmountMicros: 12_500_000, RequestedCurrency: "USD"},
TZDBVersion: ratify.TZDBVersionV2,
StatusKeys: map[string]ratify.V2StatusKeyConfig{rootID: {Epoch: 1, Key: statusPub}},
StatusPolicy: ratify.RevocationStatusPolicyV2{MaxListLifetimeSeconds: 3600, MaxStatusAgeSeconds: 3600, ClockSkewSeconds: 5},
}
cb := ratify.V2VerifyCallbacks{
ClaimStore: store,
// Trust is pinned to the complete root public key, never a key ID.
Trust: func(_ context.Context, chain []ratify.DelegationCertV2) (ratify.V2TrustResolution, error) {
if last := chain[len(chain)-1]; last.IssuerID == rootID {
return ratify.V2TrustResolution{Outcome: ratify.V2TrustTrusted, RootKey: rootPub}, nil
}
return ratify.V2TrustResolution{Outcome: ratify.V2TrustUntrusted}, nil
},
StatusEvidence: func(context.Context, ratify.V2StatusEvidenceRequest) (ratify.V2StatusEvidenceBatch, error) {
return ratify.V2StatusEvidenceBatch{Objects: []ratify.V2StatusEvidenceObject{{ObjectType: 3, Wire: statusWire}}}, nil
},
StatusJournal: journal,
}
return ratify.VerifyProofBundleV2(ctx, req, cb)
}
outcome, err := verify()
if err != nil {
return err
}
if outcome.Stage != ratify.V2StageCommitted {
return fmt.Errorf("verify stopped at %s: %v", outcome.Stage, outcome.Error)
}
fmt.Println("verify: stage=committed (not actionable until released)")
// 8. Publish the signed receipt to the log; the checkpoint acknowledges it.
receiptWire, err := store.PublishV2Receipt(ctx, outcome.Committed.ClaimID(), outcome.Committed.ReceiptBody())
if err != nil {
return err
}
receipt, err := ratify.DecodeVerificationReceiptV2(receiptWire)
if err != nil {
return err
}
fmt.Printf("receipt: published at log sequence %d\n", receipt.Sequence)
ack, err := store.GetV2Acknowledgement(ctx, logID, receipt.Sequence)
if err != nil {
return err
}
fmt.Printf("checkpoint: acknowledged sequence %d\n", ack.Sequence)
// 9. Release. Only a released decision is actionable.
result := ratify.ReleaseV2Decision(ctx, outcome.Committed, receiptWire, ratify.V2ReleaseConfig{
VerifierPublicKey: verifierPub, LogID: logID, ClaimStore: store, Checkpoint: store,
})
if result.Status != ratify.V2ReleaseReleased {
return fmt.Errorf("release %s: %s", result.Status, result.Reason)
}
decision := result.Decision
fmt.Printf("release: status=%s decision=%s reason=%s\n", result.Status, decision.Decision(), decision.Reason())
fmt.Printf("granted scope: %s\n", strings.Join(decision.GrantedScope(), ","))
// 10. Gate the side effect on Allowed at the receiver's authoritative time.
fmt.Printf("allowed now: %t\n", decision.Allowed(ctx, store))
// 11. Presenting the same proof again is a replay and is never evaluated.
store.SetTime(start + 3)
replay, _ := verify()
fmt.Printf("replay: stage=%s disposition=%s\n", replay.Stage, replay.Disposition)
// 12. The released allow ends at the challenge expiry (an exclusive deadline).
store.SetTime(challenge.ExpiresAt)
fmt.Printf("allowed at challenge expiry: %t\n", decision.Allowed(ctx, store))
return nil
}

Source: examples/v2/go/quickstart at commit 5ca7585c2c1d, SHA-256 checked at build time.

v1 v2
HumanRoot, Anchor, AgentIdentity Complete hybrid keys and key_id_v2 in caller-authenticated trust configuration. No enrollment object
AnchorResolver Application code after release, for metadata only. It never supplies trust
PolicyProvider, PolicyVerdict Application policy after ReleaseV2Decision; it may only narrow the result
AuditProvider Mandatory signed verification receipts in an acknowledged log
RevocationProvider, IsRevoked Signed status evidence and the anchored SecurityJournalV2. No ForceRevocationCheck switch: an allow always needs current status
ConstraintEvaluator The closed v2 registry plus registered evaluator profiles (com.ratifyprotocol.max_count/v1, com.ratifyprotocol.allowed_values/v1, or your own)
max_amount (float) max_amount_micros (integer) with currency
custom: required scope One exact custom: scope listed by every certificate in the chain
Self-issued challenges Archival verification only (freshness_unverified, never actionable)
VerifyResult statuses Error classes, plus the terminal decision, reason, and assessments
SessionToken, mutual presentation, HTTP and registry bindings, geo and speed v1-only until 2.1