Migrating hop intent v1 → v2

With own hops, each agent signs its own hop with its own key: the delegator signs a hop intent for the child it opens, and the payee signs an offer of the categories it serves. Owner-api 1.8.0 adds a second form of the hop intent, dynamo-hop-intent-v2 (Live). v1 intents still verify.

Back to Changelog, versioning, deprecation and migration.

What changed

payee, the cap, the category and a fresh nonce.

mandate the delegator computed locally from its own mandate narrowed by the fields it asks for, hashed the way the core hashes it into the hop record.

If they differ the open is refused with 409 hop_mandate_mismatch and nothing is opened. The delegator therefore signs exactly the authority it grants, not just the cap and category.

Who has to act

own hops default to required in money modes and optional in Control Mode, unless the operator sets CORE_OWN_HOPS. Either intent version satisfies it.

Steps

  1. Check the core serves owner-api 1.8.0 (/owner/v1/version).
  2. Compute the child's mandate hash from your own current mandate and the fields you ask for:

childMandateHash in the TypeScript SDK 3.3.0, child_mandate_hash in the Python SDK dynamoprotocol 0.6.0.

  1. Sign the v2 intent: hopIntentV2 then signHopIntent (TypeScript), or hop_intent_v2 then

sign_hop_intent (Python). Sign with the delegator's own key; the core never holds it.

  1. Send the signature as delegation, with its mandateHash, on the stream open or child open.

The TypeScript SDK checks the core's version first and raises UnsupportedByServer on an older core.

  1. If you get 409 hop_mandate_mismatch, recompute the hash over your current mandate (it may

have been narrowed since) and sign again.

Where v2 is supported

ComponentHop intent v2
The engine and owner-api 1.8.0verifies v1 and v2
@dynamoprotocol/sdk 3.3.0signs v1 and v2
dynamoprotocol 0.6.0 (Python)signs v1 and v2
@dynamoprotocol/agents 0.3.0signs v1 and v2
litellm-dynamo 1.7.0 (A2A hop signer)key_hop_signer signs v1; sign_hop_intent also signs v2

The implementations are checked byte for byte against the shared vectors in the repository:

cd "$DYNAMO_REPO"
pwd
make test-own-hops-required

Compatibility guarantees