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
- v1 (
dynamo-hop-intent-v1) is signed over the budget, the parent stream, the depth, the
payee, the cap, the category and a fresh nonce.
- v2 (
dynamo-hop-intent-v2) is the v1 fields plusmandateHash: the hash of the child
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.
- On a v2 delegation the core compares
mandateHashwith the mandate it resolves for the child.
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
- Nobody is forced to move. A v1 delegation is accepted and verified unchanged.
- Agents in a money mode (stablecoin or credit card) must sign their hops: from owner-api 1.8.0
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.
- Agents that want the mandate bound into their signature move to v2.
Steps
- Check the core serves owner-api 1.8.0 (
/owner/v1/version). - 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.
- Sign the v2 intent:
hopIntentV2thensignHopIntent(TypeScript), orhop_intent_v2then
sign_hop_intent (Python). Sign with the delegator's own key; the core never holds it.
- Send the signature as
delegation, with itsmandateHash, on the stream open or child open.
The TypeScript SDK checks the core's version first and raises UnsupportedByServer on an older core.
- 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
| Component | Hop intent v2 |
|---|---|
| The engine and owner-api 1.8.0 | verifies v1 and v2 |
@dynamoprotocol/sdk 3.3.0 | signs v1 and v2 |
dynamoprotocol 0.6.0 (Python) | signs v1 and v2 |
@dynamoprotocol/agents 0.3.0 | signs 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
- A v1 intent verifies exactly as before; nothing about v1 records changed.
mandateHashis optional on a delegation. A client that does not send it gets the 1.7.0 answer.