treessera 0.1.0__py3-none-any.whl

treessera/__init__.py

@@ -0,0 +1,102 @@
+"""Tessera SDK — build and consume Verified, transactable A2A agents.
+
+Two entry points cover almost everything:
+
+* :class:`Agent` — the provider. Give it a capability, a price, and a work
+  function; it mints a persistent signed identity, publishes a card, negotiates,
+  proves itself under challenge, and self-registers::
+
+      from treessera import Agent
+
+      agent = Agent(name="Terraform Bot", description="Generates Terraform",
+                    capability="terraform.generate", list_price=45, min_price=30,
+                    registry_url="https://registry.example", keys_dir="./keys")
+
+      @agent.task
+      def handle(task):
+          return {"main.tf": generate(task.input)}
+
+      agent.run(port=8100)
+
+* :class:`Client` — the requester. Discover, cryptographically verify, negotiate,
+  and delegate — peer to peer, never through the registry::
+
+      from treessera import Client
+
+      client = Client(registry_url="https://registry.example")
+      agent = client.discover("terraform.generate")[0]
+      result = client.delegate(agent, {"provider": "aws"}, max_price=40)
+
+Everything below the two facades (Identity, Pricing, Evidence, the protocol
+constants) is exported too, for advanced or clean-room use.
+"""
+
+from treessera.card import build_card
+from treessera.client import Client, ClientError, RemoteAgent
+from treessera.config import (
+    A2A_PROTOCOL_VERSION,
+    PRINCIPAL_PREFIX,
+    SDK_VERSION,
+    TRUST_EXTENSION_URI,
+    WELL_KNOWN_CARD_PATH,
+)
+from treessera.evidence import Evidence, sha256_hex
+from treessera.identity import (
+    Identity,
+    derive_principal_id,
+    principal_matches_pubkey,
+    verify_signature,
+)
+from treessera.negotiation import Pricing
+from treessera.protocol import (
+    A2A_METHOD,
+    ProtocolError,
+    TASK_ACCEPT,
+    TASK_COUNTER,
+    TASK_OFFER,
+    TASK_REQUEST,
+    TASK_RESULT,
+    TRUST_CHALLENGE,
+    TRUST_PROOF,
+)
+from treessera.provider import Agent, Task
+from treessera.server import AgentServer
+
+__version__ = SDK_VERSION
+
+__all__ = [
+    # facades
+    "Agent",
+    "Task",
+    "Client",
+    "RemoteAgent",
+    "ClientError",
+    # identity + crypto
+    "Identity",
+    "derive_principal_id",
+    "principal_matches_pubkey",
+    "verify_signature",
+    # building blocks
+    "Pricing",
+    "Evidence",
+    "sha256_hex",
+    "build_card",
+    "AgentServer",
+    "ProtocolError",
+    # protocol vocabulary
+    "TASK_REQUEST",
+    "TASK_OFFER",
+    "TASK_COUNTER",
+    "TASK_ACCEPT",
+    "TASK_RESULT",
+    "TRUST_CHALLENGE",
+    "TRUST_PROOF",
+    "A2A_METHOD",
+    # constants
+    "TRUST_EXTENSION_URI",
+    "A2A_PROTOCOL_VERSION",
+    "SDK_VERSION",
+    "PRINCIPAL_PREFIX",
+    "WELL_KNOWN_CARD_PATH",
+    "__version__",
+]

treessera/card.py

@@ -0,0 +1,59 @@
+"""The A2A agent card — the public identity + capability descriptor an agent
+publishes at ``/.well-known/agent-card.json``.
+
+The card is what makes an agent discoverable and callable. Declaring the trust
+extension (with the agent's ``principal_id``) is what makes it eligible for the
+Verified tier; the SDK always includes it.
+"""
+
+from treessera.config import A2A_PROTOCOL_VERSION, TRUST_EXTENSION_URI
+
+
+def build_card(name, description, url, principal_id, skills,
+               version="0.1.0", verification_url=None, requires_auth=False):
+    # type: (str, str, str, str, list, str, str, bool) -> dict
+    """Build the A2A card. ``skills`` is a list of ``{"id", "name"?,
+    "description"?, "tags"?}`` — the ``id`` is the capability the agent offers
+    (dot-namespaced), and the registry indexes discovery off it."""
+    trust_params = {"principal_id": principal_id}
+    if verification_url:
+        trust_params["verification_service_url"] = verification_url
+
+    card = {
+        "name": name,
+        "description": description,
+        "url": url,
+        "version": version,
+        "protocolVersion": A2A_PROTOCOL_VERSION,
+        "preferredTransport": "JSONRPC",
+        "capabilities": {
+            "streaming": False,
+            "pushNotifications": False,
+            "extensions": [
+                {
+                    "uri": TRUST_EXTENSION_URI,
+                    "description": "Tessera: signed identity, negotiated "
+                    "work, machine-checkable evidence, independent "
+                    "verification, and provable per-capability reputation.",
+                    "required": False,
+                    "params": trust_params,
+                }
+            ],
+        },
+        "defaultInputModes": ["application/json"],
+        "defaultOutputModes": ["application/json"],
+        "skills": [_normalize_skill(s) for s in skills],
+    }
+    if requires_auth:
+        card["securitySchemes"] = {"bearer": {"type": "http", "scheme": "bearer"}}
+        card["security"] = [{"bearer": []}]
+    return card
+
+
+def _normalize_skill(skill):
+    # type: (object) -> dict
+    if isinstance(skill, str):
+        return {"id": skill, "name": skill}
+    s = dict(skill)
+    s.setdefault("name", s.get("id", ""))
+    return s

treessera/client.py

@@ -0,0 +1,242 @@
+"""The requester side — discover, verify, negotiate, and delegate work.
+
+A requester never proxies through the registry: it looks up candidates, calls
+each agent *directly* at its card ``url``, proves the agent's identity with a
+signature challenge, negotiates a price, and delegates the task. This is the
+peer-to-peer half of Tessera.
+
+    from treessera import Client
+
+    client = Client(registry_url="https://registry.example")
+    agent = client.discover("terraform.generate")[0]      # a RemoteAgent
+    if client.verify(agent):                               # cryptographic proof
+        result = client.delegate(agent, {"provider": "aws"}, max_price=40)
+        print(result["output"])
+"""
+
+import base64
+import json
+import os
+import urllib.error
+import urllib.request
+
+from treessera import registry as _registry
+from treessera.config import TRUST_EXTENSION_URI, WELL_KNOWN_CARD_PATH
+from treessera.identity import principal_matches_pubkey, verify_signature
+from treessera.protocol import (
+    TASK_ACCEPT,
+    TASK_COUNTER,
+    TASK_OFFER,
+    TASK_REQUEST,
+    TASK_RESULT,
+    TRUST_CHALLENGE,
+    TRUST_PROOF,
+    payload_of_result,
+    wrap_request,
+)
+
+_HEADERS = {
+    "User-Agent": "treessera-sdk/0.1",
+    "Content-Type": "application/json",
+    "Accept": "application/json",
+}
+
+
+class ClientError(Exception):
+    pass
+
+
+class RemoteAgent(object):
+    """A discovered agent: its card plus the endpoints derived from it. Kept
+    small and serializable so a requester can cache or pass it around."""
+
+    def __init__(self, card, reputation=None):
+        # type: (dict, dict) -> None
+        self.card = card or {}
+        self.name = self.card.get("name", "")
+        self.reputation = reputation or {}
+        self.endpoint_url = self.card.get("url") or ""
+        self.principal_id = _principal_of(self.card)
+        self.verified = False   # flips true once verify() proves the identity
+
+    @property
+    def declares_trust(self):
+        # type: () -> bool
+        return bool(self.principal_id)
+
+    def capabilities(self):
+        # type: () -> list
+        return [s.get("id") for s in self.card.get("skills") or [] if s.get("id")]
+
+
+class Client(object):
+    def __init__(self, registry_url=None, auth_token=None, timeout=10.0):
+        # type: (str, str, float) -> None
+        self.registry_url = registry_url
+        self.auth_token = auth_token
+        self.timeout = timeout
+
+    # -- discovery ------------------------------------------------------------
+
+    def discover(self, capability, min_reputation=None):
+        # type: (str, float) -> list
+        """Find agents offering ``capability`` via the registry. Returns
+        RemoteAgents, best-reputation first (order as the registry ranks them)."""
+        if not self.registry_url:
+            raise ClientError("no registry_url configured for discovery")
+        candidates = _registry.search(self.registry_url, capability, min_reputation, self.timeout)
+        return [RemoteAgent(c.get("agent_card"), c.get("reputation_summary")) for c in candidates]
+
+    def fetch_card(self, url):
+        # type: (str) -> RemoteAgent
+        """Fetch an agent card directly by URL (base or full well-known URL) —
+        for connecting to an agent you already know, no registry involved."""
+        card = _get_json(_card_url(url), self.timeout)
+        return RemoteAgent(card)
+
+    # -- verification (the cryptographic proof) -------------------------------
+
+    def verify(self, agent, nonce=None):
+        # type: (RemoteAgent, str) -> bool
+        """Prove the agent holds the private key behind its ``principal_id``.
+
+        Sends a random nonce as a ``trust.challenge`` and checks the returned
+        ``trust.proof``: (a) the public key hashes to the declared principal_id
+        (binding) AND (b) the signature over the nonce validates. A copied
+        principal_id fails — the attacker cannot sign for a key it doesn't hold.
+        Never raises; returns False on any failure. Sets ``agent.verified``.
+        """
+        if not agent.declares_trust:
+            return False
+        nonce = nonce or _nonce()
+        try:
+            envelope = self._call(agent, {"type": TRUST_CHALLENGE, "nonce": nonce})
+        except ClientError:
+            return False
+        proof = payload_of_result(envelope)
+        if proof.get("type") != TRUST_PROOF:
+            return False
+        public_key = proof.get("public_key")
+        signature = proof.get("signature")
+        if not isinstance(public_key, str) or not isinstance(signature, str):
+            return False
+        bound = principal_matches_pubkey(agent.principal_id, public_key)
+        signed = verify_signature(public_key, nonce.encode("utf-8"), signature)
+        agent.verified = bool(bound and signed)
+        return agent.verified
+
+    # -- negotiation + delegation ---------------------------------------------
+
+    def negotiate(self, agent, task_input, max_price=None, counter_price=None):
+        # type: (RemoteAgent, dict, float, float) -> dict
+        """Run the negotiation and return an accepted offer dict
+        (``{task_id, price, ...}``), or raise ClientError if no acceptable
+        price is reached.
+
+        Sends ``task.request`` -> receives ``task.offer``. If the offer exceeds
+        ``max_price`` and a ``counter_price`` is given, sends one
+        ``task.counter``; a single counter round is the whole surface. The final
+        price must be <= ``max_price`` (when set) or the deal is declined."""
+        offer = self._expect(
+            self._call(agent, {"type": TASK_REQUEST, "input": task_input}),
+            TASK_OFFER, "task.offer",
+        )
+        if max_price is not None and offer.get("price", 0) > max_price:
+            proposed = counter_price if counter_price is not None else max_price
+            offer = self._expect(
+                self._call(agent, {
+                    "type": TASK_COUNTER,
+                    "task_id": offer.get("task_id"),
+                    "proposed_price": proposed,
+                }),
+                TASK_OFFER, "task.offer (counter response)",
+            )
+        if max_price is not None and offer.get("price", 0) > max_price:
+            raise ClientError(
+                "no acceptable price: agent held %s %s, budget was %s"
+                % (offer.get("price"), offer.get("currency", ""), max_price))
+        return offer
+
+    def accept(self, agent, offer):
+        # type: (RemoteAgent, dict) -> dict
+        """Accept an offer and collect the result payload (includes evidence)."""
+        return self._expect(
+            self._call(agent, {"type": TASK_ACCEPT, "task_id": offer.get("task_id")}),
+            TASK_RESULT, "task.result",
+        )
+
+    def delegate(self, agent, task_input, max_price=None, counter_price=None, require_verified=True):
+        # type: (RemoteAgent, dict, float, float, bool) -> dict
+        """The whole happy path: (verify) -> negotiate -> accept. Returns the
+        result payload. By default refuses to transact with an unverified agent
+        — the Verified tier is what makes a result trustworthy."""
+        if require_verified and not agent.verified and not self.verify(agent):
+            raise ClientError(
+                "agent %r is not Verified — refusing to transact "
+                "(pass require_verified=False to override)" % (agent.name,))
+        offer = self.negotiate(agent, task_input, max_price, counter_price)
+        return self.accept(agent, offer)
+
+    # -- transport ------------------------------------------------------------
+
+    def _call(self, agent, payload):
+        # type: (RemoteAgent, dict) -> dict
+        if not agent.endpoint_url:
+            raise ClientError("agent %r has no callable url" % (agent.name,))
+        request = wrap_request(payload)
+        headers = dict(_HEADERS)
+        headers["X-A2A-Extensions"] = TRUST_EXTENSION_URI
+        if self.auth_token:
+            headers["Authorization"] = "Bearer " + self.auth_token
+        data = json.dumps(request).encode("utf-8")
+        req = urllib.request.Request(agent.endpoint_url, data=data, headers=headers, method="POST")
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                envelope = json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as exc:
+            raise ClientError("agent returned HTTP %s calling %s" % (exc.code, agent.endpoint_url))
+        except Exception as exc:
+            raise ClientError("could not reach agent at %s: %s" % (agent.endpoint_url, exc))
+        if isinstance(envelope, dict) and envelope.get("error"):
+            err = envelope["error"]
+            raise ClientError("agent error %s: %s" % (err.get("code"), err.get("message")))
+        return envelope
+
+    def _expect(self, envelope, ptype, label):
+        # type: (dict, str, str) -> dict
+        payload = payload_of_result(envelope)
+        if payload.get("type") != ptype:
+            raise ClientError("expected %s, got %r" % (label, payload.get("type")))
+        return payload
+
+
+def _principal_of(card):
+    # type: (dict) -> str
+    for ext in ((card or {}).get("capabilities") or {}).get("extensions") or []:
+        if isinstance(ext, dict) and ext.get("uri") == TRUST_EXTENSION_URI:
+            return (ext.get("params") or {}).get("principal_id") or ""
+    return ""
+
+
+def _card_url(url):
+    # type: (str) -> str
+    url = url.rstrip("/")
+    if url.endswith(WELL_KNOWN_CARD_PATH):
+        return url
+    return url + WELL_KNOWN_CARD_PATH
+
+
+def _get_json(url, timeout):
+    # type: (str, float) -> dict
+    req = urllib.request.Request(url, headers={"Accept": "application/json",
+                                               "User-Agent": _HEADERS["User-Agent"]})
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except Exception as exc:
+        raise ClientError("could not fetch agent card at %s: %s" % (url, exc))
+
+
+def _nonce():
+    # type: () -> str
+    return base64.urlsafe_b64encode(os.urandom(24)).decode("ascii").rstrip("=")

treessera/config.py

@@ -0,0 +1,28 @@
+"""Protocol + brand constants — the ONE place the Tessera identity lives.
+
+The trust-extension URI is a namespace identifier (compared as an exact
+string), not a URL that gets fetched. It must match on both sides — an agent
+declares it on its card, and the registry/verification service compare against
+it — so change it here and everything (cards, verification, discovery) follows.
+It can also be overridden per-process via the ``TREESSERA_URI`` env var without
+touching code.
+"""
+
+import os
+
+#: The A2A extension URI that marks an agent as a Tessera participant.
+TRUST_EXTENSION_URI = os.environ.get(
+    "TREESSERA_URI", "https://treessera.com/extensions/trust/v1"
+)
+
+#: A2A protocol version this SDK speaks.
+A2A_PROTOCOL_VERSION = "0.3.0"
+
+#: This SDK's version.
+SDK_VERSION = "0.1.0"
+
+#: Prefix for Tessera principal identifiers.
+PRINCIPAL_PREFIX = "atp:principal:"
+
+#: Where an agent publishes its card and where verifiers fetch it.
+WELL_KNOWN_CARD_PATH = "/.well-known/agent-card.json"

treessera/evidence.py

@@ -0,0 +1,56 @@
+"""Evidence — the machine-checkable proof that a task result is real.
+
+A result carries evidence (artifact hashes, self-checks) so an independent
+verification service can confirm it before it counts toward reputation. This is
+what makes Tessera reputation *provable* rather than self-reported.
+"""
+
+import hashlib
+
+import uuid
+
+
+def sha256_hex(data):
+    # type: (object) -> str
+    if isinstance(data, str):
+        data = data.encode("utf-8")
+    elif not isinstance(data, (bytes, bytearray)):
+        data = str(data).encode("utf-8")
+    return hashlib.sha256(data).hexdigest()
+
+
+class Evidence(object):
+    """Builds the evidence record for a task result.
+
+    ``artifacts`` maps a filename to its content; each is hashed. ``schema_valid``
+    and ``tests_passed`` are the agent's self-checks — the verifier re-runs its
+    own, but the agent asserts what it believes.
+    """
+
+    def __init__(self, capability_id, session_id=None):
+        # type: (str, str) -> None
+        self.capability_id = capability_id
+        self.session_id = session_id or "sess-%s" % uuid.uuid4().hex
+        self._artifacts = {}   # filename -> content
+        self.schema_valid = True
+        self.tests_passed = True
+
+    def add_artifact(self, filename, content):
+        # type: (str, object) -> Evidence
+        self._artifacts[filename] = content
+        return self
+
+    def artifacts(self):
+        # type: () -> dict
+        return dict(self._artifacts)
+
+    def to_dict(self):
+        # type: () -> dict
+        return {
+            "evidence_id": "ev-%s" % uuid.uuid4().hex,
+            "session_id": self.session_id,
+            "capability_id": self.capability_id,
+            "schema_valid": bool(self.schema_valid),
+            "tests_passed": bool(self.tests_passed),
+            "artifact_hashes": {name: sha256_hex(c) for name, c in self._artifacts.items()},
+        }

treessera/identity.py

@@ -0,0 +1,120 @@
+"""Agent identity — the ed25519 keypair that makes an agent *provable*.
+
+The private key never leaves the process; only the public key and a derived
+``principal_id`` are ever shared. The id is cryptographically bound to the key
+(``atp:principal:<label>:sha256(b64_pubkey)[:16]``) so a verifier can confirm a
+presented public key really belongs to a claimed id — this is what the
+signature challenge relies on.
+"""
+
+import base64
+import hashlib
+import os
+import re
+
+import nacl.exceptions
+import nacl.signing
+
+from treessera.config import PRINCIPAL_PREFIX
+
+_KEY_FILENAME = "principal.key"
+_SLUG_RE = re.compile(r"[^a-z0-9]+")
+
+
+def _b64(raw):
+    # type: (bytes) -> str
+    return base64.b64encode(raw).decode("ascii")
+
+
+def _slug(label):
+    # type: (str) -> str
+    s = _SLUG_RE.sub("-", (label or "agent").lower()).strip("-")
+    return s or "agent"
+
+
+def derive_principal_id(public_key_b64, label="agent"):
+    # type: (str, str) -> str
+    """Bind a principal id to a public key. The label is cosmetic; only the
+    trailing hash is verified, so the id cannot be forged for a key you do not
+    hold."""
+    digest = hashlib.sha256(public_key_b64.encode("ascii")).hexdigest()[:16]
+    return "%s%s:%s" % (PRINCIPAL_PREFIX, _slug(label), digest)
+
+
+def principal_matches_pubkey(principal_id, public_key_b64):
+    # type: (str, str) -> bool
+    """True iff ``public_key_b64`` is the key ``principal_id`` was derived
+    from. Supports the raw-pubkey form (``principal_id`` == the base64 key)
+    for compatibility with user principals."""
+    if not isinstance(principal_id, str) or not isinstance(public_key_b64, str):
+        return False
+    digest = hashlib.sha256(public_key_b64.encode("ascii")).hexdigest()[:16]
+    return principal_id.endswith(":" + digest) or principal_id == public_key_b64
+
+
+class Identity(object):
+    """An agent's ed25519 identity, loaded from — or created once in — a
+    directory. Reuse the same ``keys_dir`` across restarts to keep a stable
+    ``principal_id`` (and therefore stable reputation)."""
+
+    def __init__(self, signing_key, label="agent"):
+        # type: (nacl.signing.SigningKey, str) -> None
+        self._sk = signing_key
+        self.public_key_b64 = _b64(bytes(signing_key.verify_key))
+        self.principal_id = derive_principal_id(self.public_key_b64, label)
+
+    # -- construction ---------------------------------------------------------
+
+    @classmethod
+    def generate(cls, label="agent"):
+        # type: (str) -> Identity
+        return cls(nacl.signing.SigningKey.generate(), label)
+
+    @classmethod
+    def load_or_create(cls, keys_dir, label="agent"):
+        # type: (str, str) -> Identity
+        """Load the key from ``keys_dir`` if present, else create it once. The
+        directory gets a ``.gitignore`` so the private key can never be
+        committed."""
+        os.makedirs(keys_dir, exist_ok=True)
+        gitignore = os.path.join(keys_dir, ".gitignore")
+        if not os.path.exists(gitignore):
+            with open(gitignore, "w") as fh:
+                fh.write("*\n")
+        path = os.path.join(keys_dir, _KEY_FILENAME)
+        if os.path.exists(path):
+            with open(path, "rb") as fh:
+                seed = base64.b64decode(fh.read().strip())
+            return cls(nacl.signing.SigningKey(seed), label)
+        sk = nacl.signing.SigningKey.generate()
+        with open(path, "wb") as fh:
+            fh.write(base64.b64encode(bytes(sk)))
+        try:
+            os.chmod(path, 0o600)
+        except OSError:
+            pass
+        return cls(sk, label)
+
+    # -- signing --------------------------------------------------------------
+
+    def sign(self, message):
+        # type: (bytes) -> str
+        """Return the base64 signature over ``message``."""
+        return _b64(self._sk.sign(message).signature)
+
+    def sign_text(self, text):
+        # type: (str) -> str
+        return self.sign(text.encode("utf-8"))
+
+
+def verify_signature(public_key_b64, message, signature_b64):
+    # type: (str, bytes, str) -> bool
+    """Verify an ed25519 signature; never raises — returns False on any
+    problem."""
+    try:
+        vk = nacl.signing.VerifyKey(base64.b64decode(public_key_b64))
+        vk.verify(message, base64.b64decode(signature_b64))
+        return True
+    except (ValueError, TypeError, nacl.exceptions.BadSignatureError,
+            nacl.exceptions.CryptoError):
+        return False

treessera/negotiation.py

@@ -0,0 +1,60 @@
+"""Price negotiation — the offer/counter logic, with a PRIVATE reserve.
+
+The reserve (``min_price``) is never serialized: it appears in no card, no
+offer, and no counter response. A counter at or above the reserve is accepted at
+the countered price; below it, the agent holds its list price. This is the whole
+negotiation surface — single-round by design (RFC-0001/KTD6).
+"""
+
+from treessera.protocol import TASK_OFFER
+
+
+class Pricing(object):
+    def __init__(self, list_price, min_price=None, currency="USD", delivery="immediate"):
+        # type: (float, float, str, str) -> None
+        if list_price is None:
+            raise ValueError("list_price is required")
+        self.list_price = float(list_price)
+        # reserve defaults to list price (no discounting) and is clamped so it
+        # can never exceed the public price
+        reserve = self.list_price if min_price is None else float(min_price)
+        self.min_price = min(reserve, self.list_price)
+        self.currency = currency
+        self.delivery = delivery
+
+    def offer(self, task_id, capability_id, terms=None):
+        # type: (str, str, dict) -> dict
+        """The public opening offer. Only the list price crosses the wire."""
+        payload = {
+            "type": TASK_OFFER,
+            "task_id": task_id,
+            "capability_id": capability_id,
+            "price": self.list_price,
+            "currency": self.currency,
+            "delivery": self.delivery,
+        }
+        if terms:
+            payload["terms"] = terms
+        return payload
+
+    def respond_to_counter(self, task_id, capability_id, proposed_price, terms=None):
+        # type: (str, str, float, dict) -> dict
+        """Evaluate a counter-offer. At/above the private reserve -> re-offer at
+        the countered price (a deal). Below it -> hold the list price. Either way
+        the reserve itself is never revealed."""
+        try:
+            proposed = float(proposed_price)
+        except (TypeError, ValueError):
+            proposed = None
+        price = proposed if (proposed is not None and proposed >= self.min_price) else self.list_price
+        payload = {
+            "type": TASK_OFFER,
+            "task_id": task_id,
+            "capability_id": capability_id,
+            "price": price,
+            "currency": self.currency,
+            "delivery": self.delivery,
+        }
+        if terms:
+            payload["terms"] = terms
+        return payload