@agenticprimitives/contracts 0.1.0-alpha.2

package/src/relationships/AgentRelationship.sol

@@ -0,0 +1,289 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+/**
+ * @title AgentRelationship
+ * @notice Trust-fabric edge store between Smart Agents.
+ *
+ * One edge per `(subject, object, relationshipType)` triple.
+ * Each edge carries a set of role labels (subject-side + object-side
+ * implicit; same bag for now) and a lifecycle status.
+ *
+ * Lifecycle: `PROPOSED → CONFIRMED → ACTIVE → REVOKED` (matches
+ * the TypeScript `EdgeStatus` enum in
+ * agenticprimitives/agent-relationships).
+ *
+ * Adapted from smart-agent
+ * (`packages/contracts/src/AgentRelationship.sol`, 392 LOC) with the
+ * following simplifications per spec 216 § Phase 3:
+ *
+ *   - **No baked-in relationship-type / role constants.** The
+ *     vocabulary lives in `AgentRelationshipPredicates.sol` (mirrored
+ *     by the TS SDK in `agent-relationships/src/constants.ts`), and
+ *     type semantics live in `RelationshipTypeRegistry.sol`. Keeps
+ *     this contract focused on edge mechanics.
+ *
+ *   - **No `isOwner(address)` fallback in auth.** Our AgentAccount is
+ *     ERC-7579 modular; quorum belongs in the CustodyPolicy module.
+ *     Authorization is `msg.sender == subject` (or `object` / the
+ *     `createdBy` for read-back), trusting the AgentAccount's execute
+ *     path to gate upstream.
+ *
+ *   - **Add `metadataHash`** field to the edge for off-chain
+ *     content-hash anchoring (matches the AgentName resolver pattern).
+ *     Off-chain JSON published at `metadataURI` MUST hash to
+ *     `metadataHash`; consumers reject mismatched fetches.
+ */
+contract AgentRelationship {
+    enum EdgeStatus {
+        NONE,        // 0 — never set (sentinel)
+        PROPOSED,    // 1
+        CONFIRMED,   // 2
+        ACTIVE,      // 3
+        REVOKED      // 4
+    }
+
+    struct Edge {
+        bytes32 edgeId;
+        address subject;
+        address object_;
+        bytes32 relationshipType;
+        EdgeStatus status;
+        address createdBy;
+        uint64 createdAt;
+        uint64 updatedAt;
+        string metadataURI;
+        bytes32 metadataHash;
+    }
+
+    // ─── Storage ────────────────────────────────────────────────────
+
+    mapping(bytes32 => Edge) private _edges;
+    mapping(bytes32 => bytes32[]) private _roles;                           // edgeId → role[]
+    mapping(bytes32 => mapping(bytes32 => bool)) private _hasRole;          // edgeId → role → exists
+    mapping(address => bytes32[]) private _edgesBySubject;
+    mapping(address => bytes32[]) private _edgesByObject;
+    mapping(address => mapping(address => mapping(bytes32 => bytes32))) private _byTriple;
+
+    // ─── Events ─────────────────────────────────────────────────────
+
+    event EdgeProposed(
+        bytes32 indexed edgeId,
+        address indexed subject,
+        address indexed object_,
+        bytes32 relationshipType,
+        address createdBy
+    );
+    event EdgeConfirmed(bytes32 indexed edgeId, address indexed confirmedBy);
+    event EdgeActivated(bytes32 indexed edgeId, address indexed activatedBy);
+    event EdgeRevoked(bytes32 indexed edgeId, address indexed revokedBy);
+    event RoleAdded(bytes32 indexed edgeId, bytes32 indexed role, address indexed updater);
+    event RoleRemoved(bytes32 indexed edgeId, bytes32 indexed role, address indexed updater);
+    event EdgeMetadataUpdated(bytes32 indexed edgeId, string metadataURI, bytes32 metadataHash, address indexed updater);
+
+    // ─── Errors ─────────────────────────────────────────────────────
+
+    error InvalidEdge();
+    error EdgeAlreadyExists();
+    error EdgeNotFound();
+    error RoleAlreadyExists();
+    error RoleNotFound();
+    error NotAuthorized();
+    error InvalidTransition();
+
+    // ─── Edge ID ────────────────────────────────────────────────────
+
+    /**
+     * @notice Deterministic edge id =
+     *         `keccak256(abi.encodePacked(subject, object, relationshipType))`.
+     *         Matches the TS SDK's `computeEdgeId` (lowercased addresses
+     *         packed in the same order).
+     */
+    function computeEdgeId(
+        address subject,
+        address object_,
+        bytes32 relationshipType
+    ) public pure returns (bytes32) {
+        return keccak256(abi.encodePacked(subject, object_, relationshipType));
+    }
+
+    // ─── Propose ────────────────────────────────────────────────────
+
+    /**
+     * @notice Propose a new edge. The caller must be the subject's
+     *         Smart Agent OR (for relayed flows) any party authorized
+     *         to act on its behalf upstream.
+     *
+     * Phase 3 auth model: `msg.sender` is the proposer (typically the
+     * subject's AgentAccount execute path). The contract trusts the
+     * caller to be gated upstream; cross-side confirmation is required
+     * before the edge becomes ACTIVE.
+     */
+    function proposeEdge(
+        address subject,
+        address object_,
+        bytes32 relationshipType,
+        bytes32[] calldata initialRoles,
+        string calldata metadataURI,
+        bytes32 metadataHash
+    ) external returns (bytes32 edgeId) {
+        if (subject == address(0) || object_ == address(0)) revert InvalidEdge();
+        if (subject == object_) revert InvalidEdge();
+        if (msg.sender != subject) revert NotAuthorized();
+        edgeId = computeEdgeId(subject, object_, relationshipType);
+        if (_edges[edgeId].createdAt != 0) revert EdgeAlreadyExists();
+
+        _edges[edgeId] = Edge({
+            edgeId: edgeId,
+            subject: subject,
+            object_: object_,
+            relationshipType: relationshipType,
+            status: EdgeStatus.PROPOSED,
+            createdBy: msg.sender,
+            createdAt: uint64(block.timestamp),
+            updatedAt: uint64(block.timestamp),
+            metadataURI: metadataURI,
+            metadataHash: metadataHash
+        });
+
+        _edgesBySubject[subject].push(edgeId);
+        _edgesByObject[object_].push(edgeId);
+        _byTriple[subject][object_][relationshipType] = edgeId;
+
+        for (uint256 i = 0; i < initialRoles.length; i++) {
+            _addRole(edgeId, initialRoles[i]);
+            emit RoleAdded(edgeId, initialRoles[i], msg.sender);
+        }
+
+        emit EdgeProposed(edgeId, subject, object_, relationshipType, msg.sender);
+    }
+
+    // ─── Confirm ────────────────────────────────────────────────────
+
+    /**
+     * @notice The object side confirms a PROPOSED edge.
+     *         PROPOSED → CONFIRMED. Caller MUST be the object.
+     */
+    function confirmEdge(bytes32 edgeId) external {
+        Edge storage e = _edges[edgeId];
+        if (e.createdAt == 0) revert EdgeNotFound();
+        if (e.status != EdgeStatus.PROPOSED) revert InvalidTransition();
+        if (msg.sender != e.object_) revert NotAuthorized();
+        e.status = EdgeStatus.CONFIRMED;
+        e.updatedAt = uint64(block.timestamp);
+        emit EdgeConfirmed(edgeId, msg.sender);
+    }
+
+    /**
+     * @notice Activate a CONFIRMED edge. CONFIRMED → ACTIVE. Either
+     *         side may activate; off-chain resolvers may sequence the
+     *         activation when ancillary checks pass (e.g. timelock).
+     */
+    function activateEdge(bytes32 edgeId) external {
+        Edge storage e = _edges[edgeId];
+        if (e.createdAt == 0) revert EdgeNotFound();
+        if (e.status != EdgeStatus.CONFIRMED) revert InvalidTransition();
+        if (msg.sender != e.subject && msg.sender != e.object_) revert NotAuthorized();
+        e.status = EdgeStatus.ACTIVE;
+        e.updatedAt = uint64(block.timestamp);
+        emit EdgeActivated(edgeId, msg.sender);
+    }
+
+    /**
+     * @notice Permissionless revocation from either side. Spec 216
+     *         security invariant: either party may revoke
+     *         unilaterally. Once REVOKED, the edge is terminal.
+     */
+    function revokeEdge(bytes32 edgeId) external {
+        Edge storage e = _edges[edgeId];
+        if (e.createdAt == 0) revert EdgeNotFound();
+        if (e.status == EdgeStatus.REVOKED) revert InvalidTransition();
+        if (msg.sender != e.subject && msg.sender != e.object_) revert NotAuthorized();
+        e.status = EdgeStatus.REVOKED;
+        e.updatedAt = uint64(block.timestamp);
+        emit EdgeRevoked(edgeId, msg.sender);
+    }
+
+    // ─── Roles ──────────────────────────────────────────────────────
+
+    /**
+     * @notice Add a role to an existing edge. Either side may add
+     *         roles to the edge's role bag.
+     */
+    function addRole(bytes32 edgeId, bytes32 role) external {
+        Edge storage e = _edges[edgeId];
+        if (e.createdAt == 0) revert EdgeNotFound();
+        if (msg.sender != e.subject && msg.sender != e.object_) revert NotAuthorized();
+        if (_hasRole[edgeId][role]) revert RoleAlreadyExists();
+        _addRole(edgeId, role);
+        e.updatedAt = uint64(block.timestamp);
+        emit RoleAdded(edgeId, role, msg.sender);
+    }
+
+    function removeRole(bytes32 edgeId, bytes32 role) external {
+        Edge storage e = _edges[edgeId];
+        if (e.createdAt == 0) revert EdgeNotFound();
+        if (msg.sender != e.subject && msg.sender != e.object_) revert NotAuthorized();
+        if (!_hasRole[edgeId][role]) revert RoleNotFound();
+        _removeRole(edgeId, role);
+        e.updatedAt = uint64(block.timestamp);
+        emit RoleRemoved(edgeId, role, msg.sender);
+    }
+
+    // ─── Metadata ───────────────────────────────────────────────────
+
+    function setMetadata(bytes32 edgeId, string calldata metadataURI, bytes32 metadataHash) external {
+        Edge storage e = _edges[edgeId];
+        if (e.createdAt == 0) revert EdgeNotFound();
+        if (msg.sender != e.subject && msg.sender != e.object_) revert NotAuthorized();
+        e.metadataURI = metadataURI;
+        e.metadataHash = metadataHash;
+        e.updatedAt = uint64(block.timestamp);
+        emit EdgeMetadataUpdated(edgeId, metadataURI, metadataHash, msg.sender);
+    }
+
+    // ─── Queries ────────────────────────────────────────────────────
+
+    function getEdge(bytes32 edgeId) external view returns (Edge memory) {
+        Edge memory e = _edges[edgeId];
+        if (e.createdAt == 0) revert EdgeNotFound();
+        return e;
+    }
+    function getRoles(bytes32 edgeId) external view returns (bytes32[] memory) {
+        return _roles[edgeId];
+    }
+    function hasRole(bytes32 edgeId, bytes32 role) external view returns (bool) {
+        return _hasRole[edgeId][role];
+    }
+    function getEdgesBySubject(address subject) external view returns (bytes32[] memory) {
+        return _edgesBySubject[subject];
+    }
+    function getEdgesByObject(address object_) external view returns (bytes32[] memory) {
+        return _edgesByObject[object_];
+    }
+    function getEdgeByTriple(address subject, address object_, bytes32 relationshipType) external view returns (bytes32) {
+        return _byTriple[subject][object_][relationshipType];
+    }
+    function edgeExists(bytes32 edgeId) external view returns (bool) {
+        return _edges[edgeId].createdAt != 0;
+    }
+
+    // ─── Internal ───────────────────────────────────────────────────
+
+    function _addRole(bytes32 edgeId, bytes32 role) internal {
+        _roles[edgeId].push(role);
+        _hasRole[edgeId][role] = true;
+    }
+
+    function _removeRole(bytes32 edgeId, bytes32 role) internal {
+        _hasRole[edgeId][role] = false;
+        bytes32[] storage roles = _roles[edgeId];
+        for (uint256 i = 0; i < roles.length; i++) {
+            if (roles[i] == role) {
+                roles[i] = roles[roles.length - 1];
+                roles.pop();
+                break;
+            }
+        }
+    }
+}

package/src/relationships/AgentRelationshipPredicates.sol

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+/**
+ * @title AgentRelationshipPredicates
+ * @notice Canonical bytes32 ids for the agent-relationships trust
+ *         fabric (relationship types + role labels). Single source of
+ *         truth shared by:
+ *           - AgentRelationship.sol (uses the IDs as bytes32 keys)
+ *           - Deploy.s.sol (bootstraps the type set in
+ *             RelationshipTypeRegistry)
+ *           - agenticprimitives/agent-relationships SDK (mirror
+ *             constants in src/constants.ts)
+ *
+ * The six well-known relationship types match spec 216 § 5; matching
+ * `keccak256(name)` IDs are derived here. The role set is deliberately
+ * narrower than the smart-agent original (start small, add via PR + a
+ * golden-vector test when concrete consumers need a role).
+ */
+library AgentRelationshipPredicates {
+    // ─── Well-known relationship types ──────────────────────────────
+
+    /// Membership: subject is a member of object.
+    bytes32 internal constant HAS_MEMBER               = keccak256("HAS_MEMBER");
+    /// Governance: subject has governance authority over object.
+    bytes32 internal constant HAS_GOVERNANCE_OVER      = keccak256("HAS_GOVERNANCE_OVER");
+    /// Validation: subject trusts object as a validator / verifier.
+    bytes32 internal constant VALIDATION_TRUST         = keccak256("VALIDATION_TRUST");
+    /// Bilateral partnership / cross-recognition (symmetric).
+    bytes32 internal constant PARTNERSHIP              = keccak256("PARTNERSHIP");
+    /// Operational delegation marker: subject operates on behalf of object.
+    bytes32 internal constant OPERATES_ON_BEHALF_OF    = keccak256("OPERATES_ON_BEHALF_OF");
+    /// Endorsement: subject recommends object.
+    bytes32 internal constant RECOMMENDS               = keccak256("RECOMMENDS");
+
+    // ─── Well-known roles ───────────────────────────────────────────
+
+    bytes32 internal constant ROLE_MEMBER              = keccak256("MEMBER");
+    bytes32 internal constant ROLE_BOARD_MEMBER        = keccak256("BOARD_MEMBER");
+    bytes32 internal constant ROLE_OPERATOR            = keccak256("OPERATOR");
+    bytes32 internal constant ROLE_VALIDATOR           = keccak256("VALIDATOR");
+    bytes32 internal constant ROLE_TREASURER           = keccak256("TREASURER");
+    bytes32 internal constant ROLE_RECOVERY_CONTACT    = keccak256("RECOVERY_CONTACT");
+}

package/src/relationships/RelationshipTypeRegistry.sol

@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.28;
+
+/**
+ * @title RelationshipTypeRegistry
+ * @notice Governed registry of relationship-type semantic metadata
+ *         used by `AgentRelationship` to interpret edges.
+ *
+ * Each relationship type can be annotated with:
+ *   - `isHierarchical` — edges induce parent → child semantics
+ *   - `isTransitive` — supports ancestor / descendant inference
+ *   - `isSymmetric` — direction-independent (`PARTNERSHIP`)
+ *
+ * Governance: only `governor` may register / update / deactivate
+ * types. Same pattern as `OntologyTermRegistry` (NS Phase 3 stack);
+ * deployer is the bootstrap governor; rotation via
+ * `transferGovernor`.
+ *
+ * Adapted from smart-agent
+ * (`packages/contracts/src/RelationshipTypeRegistry.sol`, 138 LOC) —
+ * structurally identical with constructor zero-governor guard.
+ */
+contract RelationshipTypeRegistry {
+    struct TypeSemantics {
+        bytes32 relationshipType;
+        string label;
+        bool isHierarchical;
+        bool isTransitive;
+        bool isSymmetric;
+        bool active;
+        uint256 registeredAt;
+    }
+
+    address public governor;
+    mapping(bytes32 => TypeSemantics) private _types;
+    bytes32[] private _typeIds;
+
+    event TypeRegistered(bytes32 indexed relationshipType, string label, bool isHierarchical, bool isTransitive, bool isSymmetric);
+    event TypeDeactivated(bytes32 indexed relationshipType);
+    event TypeActivated(bytes32 indexed relationshipType);
+    event TypeUpdated(bytes32 indexed relationshipType, bool isHierarchical, bool isTransitive, bool isSymmetric);
+    event GovernorTransferred(address indexed oldGovernor, address indexed newGovernor);
+
+    error NotGovernor();
+    error TypeExists();
+    error TypeNotFound();
+    error ZeroGovernor();
+
+    modifier onlyGovernor() {
+        if (msg.sender != governor) revert NotGovernor();
+        _;
+    }
+
+    constructor(address governor_) {
+        if (governor_ == address(0)) revert ZeroGovernor();
+        governor = governor_;
+    }
+
+    function transferGovernor(address newGovernor) external onlyGovernor {
+        if (newGovernor == address(0)) revert ZeroGovernor();
+        emit GovernorTransferred(governor, newGovernor);
+        governor = newGovernor;
+    }
+
+    // ─── Registration ───────────────────────────────────────────────
+
+    function registerType(
+        bytes32 relationshipType,
+        string calldata label,
+        bool hierarchical,
+        bool transitive,
+        bool symmetric
+    ) external onlyGovernor {
+        if (_types[relationshipType].registeredAt != 0) revert TypeExists();
+        _types[relationshipType] = TypeSemantics({
+            relationshipType: relationshipType,
+            label: label,
+            isHierarchical: hierarchical,
+            isTransitive: transitive,
+            isSymmetric: symmetric,
+            active: true,
+            registeredAt: block.timestamp
+        });
+        _typeIds.push(relationshipType);
+        emit TypeRegistered(relationshipType, label, hierarchical, transitive, symmetric);
+    }
+
+    function updateSemantics(
+        bytes32 relationshipType,
+        bool hierarchical,
+        bool transitive,
+        bool symmetric
+    ) external onlyGovernor {
+        if (_types[relationshipType].registeredAt == 0) revert TypeNotFound();
+        _types[relationshipType].isHierarchical = hierarchical;
+        _types[relationshipType].isTransitive = transitive;
+        _types[relationshipType].isSymmetric = symmetric;
+        emit TypeUpdated(relationshipType, hierarchical, transitive, symmetric);
+    }
+
+    function deactivateType(bytes32 relationshipType) external onlyGovernor {
+        if (_types[relationshipType].registeredAt == 0) revert TypeNotFound();
+        _types[relationshipType].active = false;
+        emit TypeDeactivated(relationshipType);
+    }
+
+    function activateType(bytes32 relationshipType) external onlyGovernor {
+        if (_types[relationshipType].registeredAt == 0) revert TypeNotFound();
+        _types[relationshipType].active = true;
+        emit TypeActivated(relationshipType);
+    }
+
+    // ─── Queries ────────────────────────────────────────────────────
+
+    function getTypeSemantics(bytes32 relationshipType) external view returns (TypeSemantics memory) {
+        return _types[relationshipType];
+    }
+
+    function isRegistered(bytes32 relationshipType) external view returns (bool) {
+        return _types[relationshipType].registeredAt != 0;
+    }
+    function isActive(bytes32 relationshipType) external view returns (bool) {
+        return _types[relationshipType].active;
+    }
+    function isHierarchical(bytes32 relationshipType) external view returns (bool) {
+        return _types[relationshipType].isHierarchical;
+    }
+    function isTransitive(bytes32 relationshipType) external view returns (bool) {
+        return _types[relationshipType].isTransitive;
+    }
+    function isSymmetric(bytes32 relationshipType) external view returns (bool) {
+        return _types[relationshipType].isSymmetric;
+    }
+    function typeCount() external view returns (uint256) {
+        return _typeIds.length;
+    }
+    function getTypeAt(uint256 index) external view returns (bytes32) {
+        return _typeIds[index];
+    }
+    function getAllTypeIds() external view returns (bytes32[] memory) {
+        return _typeIds;
+    }
+}