feat: role-management bindings & permission docs (#56)

## What's inside - Go & Python helpers for `GrantRole`, `RevokeRole`, `AreMembersOf`, `ListRoleMembers`. - `TNClient` exposes matching methods + new typed dicts. - Bump `sdk-go` to v0.3.2; add `eth_account` for tests. - Integration suite: role grant/revoke happy-path + permission gate; fixtures auto-whitelist writer role. - Docs: short call-outs that stream deployment needs `system:network_writer`; no self-grant guidance. ## Issue - fix #51 - fix #52 ## Validation `pytest` green;

Author: outerlook

README.md

@@ -129,6 +129,14 @@ client.deploy_stream(composite_stream_id, STREAM_TYPE_COMPOSED)
 
 For the full example, refer to the [Complex Example README](./examples/complex_example/README.md).
 
+## Role-based Permissions
+
+> **Heads-up:** Deploying streams requires the `system:network_writer` role; reading public streams is permissionless.
+
+Don't have the role? Contact the TRUF.NETWORK team to get whitelisted.
+
+Check your role status using the **Role Management** APIs in the [API Reference](./docs/api-reference.md#role-management).
+
 ## Stream Creation and Management
 
 ### Stream Types

bindings/bindings.go

@@ -832,6 +832,10 @@ func convertToString(val any) string {
 return v.String()
 case civil.Date:
 return v.String()
+case util.EthereumAddress:
+return v.Address()
+case *util.EthereumAddress:
+return v.Address()
 case fmt.Stringer:
 return v.String()
 default:
@@ -928,3 +932,123 @@ func BatchFilterStreamsByExistence(client *tnclient.Client, locators []types.Str
 }
 return output, nil
 }
+
+// helper to convert slice of hex wallet strings to []util.EthereumAddress
+func strSliceToEthAddrs(wallets []string) ([]util.EthereumAddress, error) {
+out := make([]util.EthereumAddress, len(wallets))
+for i, w := range wallets {
+addr, err := util.NewEthereumAddressFromString(w)
+if err != nil {
+return nil, err
+}
+out[i] = addr
+}
+return out, nil
+}
+
+// GrantRole grants a role to multiple wallets.
+func GrantRole(client *tnclient.Client, owner string, roleName string, wallets []string) (string, error) {
+ctx := context.Background()
+
+roleMgmt, err := client.LoadRoleManagementActions()
+if err != nil {
+return "", errors.Wrap(err, "error loading role management actions")
+}
+
+addrs, err := strSliceToEthAddrs(wallets)
+if err != nil {
+return "", errors.Wrap(err, "invalid wallet address")
+}
+
+input := types.GrantRoleInput{
+Owner: owner,
+RoleName: roleName,
+Wallets: addrs,
+}
+
+txHash, err := roleMgmt.GrantRole(ctx, input)
+if err != nil {
+return "", errors.Wrap(err, "error granting role")
+}
+return txHash.String(), nil
+}
+
+// RevokeRole revokes a role from multiple wallets.
+func RevokeRole(client *tnclient.Client, owner string, roleName string, wallets []string) (string, error) {
+ctx := context.Background()
+
+roleMgmt, err := client.LoadRoleManagementActions()
+if err != nil {
+return "", errors.Wrap(err, "error loading role management actions")
+}
+
+addrs, err := strSliceToEthAddrs(wallets)
+if err != nil {
+return "", errors.Wrap(err, "invalid wallet address")
+}
+
+input := types.RevokeRoleInput{
+Owner: owner,
+RoleName: roleName,
+Wallets: addrs,
+}
+
+txHash, err := roleMgmt.RevokeRole(ctx, input)
+if err != nil {
+return "", errors.Wrap(err, "error revoking role")
+}
+return txHash.String(), nil
+}
+
+// AreMembersOf checks if a list of wallets are members of a specific role.
+func AreMembersOf(client *tnclient.Client, owner string, roleName string, wallets []string) ([]map[string]string, error) {
+ctx := context.Background()
+
+roleMgmt, err := client.LoadRoleManagementActions()
+if err != nil {
+return nil, errors.Wrap(err, "error loading role management actions")
+}
+
+addrs, err := strSliceToEthAddrs(wallets)
+if err != nil {
+return nil, errors.Wrap(err, "invalid wallet address")
+}
+
+input := types.AreMembersOfInput{
+Owner: owner,
+RoleName: roleName,
+Wallets: addrs,
+}
+
+results, err := roleMgmt.AreMembersOf(ctx, input)
+if err != nil {
+return nil, errors.Wrap(err, "error checking role members")
+}
+
+return recordsToMapSlice(results), nil
+}
+
+// ListRoleMembers lists the current members of a role with optional pagination.
+// It returns a slice of map[string]string where each map contains `Wallet`, `GrantedAt`, and `GrantedBy`.
+func ListRoleMembers(client *tnclient.Client, owner string, roleName string, limit int, offset int) ([]map[string]string, error) {
+ctx := context.Background()
+
+roleMgmt, err := client.LoadRoleManagementActions()
+if err != nil {
+return nil, errors.Wrap(err, "error loading role management actions")
+}
+
+input := types.ListRoleMembersInput{
+Owner: owner,
+RoleName: roleName,
+Limit: limit,
+Offset: offset,
+}
+
+results, err := roleMgmt.ListRoleMembers(ctx, input)
+if err != nil {
+return nil, errors.Wrap(err, "error listing role members")
+}
+
+return recordsToMapSlice(results), nil
+}

docs/api-reference.md

@@ -43,6 +43,12 @@ market_index_stream_id = generate_stream_id('market_index')
 
 ## Stream Deployment
 
+> **Note: Stream Deployment Permissions**
+>
+> Deploying new streams on the TRUF.NETWORK requires the `system:network_writer` role.
+>
+> If you're interested in deploying streams, please contact the TRUF.NETWORK team for assistance.
+
 ### `client.deploy_stream(stream_id: str, stream_type: str) -> str`
 Deploys a new stream to the TRUF.NETWORK.
 
@@ -166,8 +172,90 @@ tx_hash = client.set_taxonomy(
 )
 ```
 
+## Role Management
+
+> Only wallets with manager privileges (e.g. `system:network_writers_manager`) can grant or revoke roles. Regular users should request access from the TRUF.NETWORK team.
+
+### `client.grant_role(owner: str, role_name: str, wallets: List[str]) -> str`
+Grants a specified role to a list of wallet addresses.
+
+#### Parameters
+- `owner: str` - The owner of the role (e.g., 'system' or an Ethereum address).
+- `role_name: str` - The name of the role to grant.
+- `wallets: List[str]` - A list of wallet addresses to grant the role to.
+
+#### Returns
+- `str` - Transaction hash of the role grant operation.
+
+#### Example
+```python
+# Grant the system:network_writer role to a specific wallet
+tx_hash = client.grant_role(
+ "system",
+ "network_writer",
+ ["0xAbC...123"]
+)
+```
+
+### `client.revoke_role(owner: str, role_name: str, wallets: List[str]) -> str`
+Revokes a specified role from a list of wallet addresses.
+
+#### Parameters
+- `owner: str` - The owner of the role.
+- `role_name: str` - The name of the role to revoke.
+- `wallets: List[str]` - A list of wallet addresses from which to revoke the role.
+
+#### Returns
+- `str` - Transaction hash of the role revocation operation.
+
+#### Example
+```python
+tx_hash = client.revoke_role(
+ "system",
+ "network_writer",
+ ["0xAbC...123"]
+)
+```
+
+### `client.are_members_of(owner: str, role_name: str, wallets: List[str]) -> List[Dict]`
+Checks if a list of wallets are members of a specific role.
+
+#### Parameters
+- `owner: str` - The owner of the role to check against.
+- `role_name: str` - The name of the role.
+- `wallets: List[str]` - A list of wallet addresses to check.
+
+#### Returns
+- `List[Dict]` - A list of objects, each containing:
+ - `wallet: str` - The wallet address checked.
+ - `is_member: bool` - True if the wallet is a member, false otherwise.
+
+#### Example
+```python
+wallets_to_check = ["0xAbC...123", "0xDeF...456"]
+membership_status = client.are_members_of(
+ "system",
+ "network_writer",
+ wallets_to_check
+)
+# Example output:
+# [
+# {'wallet': '0xabc...123', 'is_member': True},
+# {'wallet': '0xdef...456', 'is_member': False}
+# ]
+```
+
 ## Visibility and Permissions
 
+### System vs. User Roles
+
+| Role Namespace | Example | Who can create/manage | Typical purpose |
+|----------------|---------|-----------------------|-----------------|
+| `system:` | `system:network_writer` | Core protocol maintainers | Gate network-wide operations (e.g. create streams) |
+| `<wallet>:` | `0x1234…abcd:pro_subscribers` | The wallet prefix (owner) | Business-specific read/write groups |
+
+> Tip: You can list all roles owned by a wallet with `client.list_role_members(owner, role_name)`.
+
 ### `client.set_read_visibility(stream_id: str, visibility: str) -> str`
 Controls stream read access.
 
@@ -206,8 +294,8 @@ client.wait_for_tx(tx_hash)
 ```
 
 ## Performance Recommendations
-- Use batch record insertions
-- Handle errors with specific exception handling
+- Use `batch_insert_records` for multiple records to one or more streams to reduce network overhead and transaction costs.
+- Handle errors with specific exception handling to build robust applications.
 
 ## SDK Compatibility
 - Minimum Python Version: 3.8 

examples/README.md

@@ -73,6 +73,8 @@ Date: 2024-01-16, Value: 106.50
 
 ## Notes
 
+> **Permission note:** This script only *reads* public streams, so no roles are required. Deploying streams needs the `system:network_writer` role; contact the TRUF.NETWORK team to obtain it.
+
 - Always handle private keys securely
 - Be mindful of rate limits
 - This is a basic example; adapt for your specific use case

examples/complex_example/README.md

@@ -17,6 +17,7 @@ This example demonstrates the full lifecycle of stream management in the TRUF.NE
 - Python 3.8+
 - `venv` module (usually comes with Python standard library)
 - A valid private key for the TRUF.NETWORK gateway
+- Your wallet must **hold `system:network_writer`** or the deployment steps will fail. Contact the TRUF.NETWORK team if you need access.
 
 ## Setup
 

examples/complex_example/main.py

@@ -15,6 +15,10 @@ def create_example_streams(client):
  5. Inserting records into primitive streams
  6. Reading records from streams
  7. Cleaning up (destroying) streams
+ 
+ ⚠️ **Permissions:** Running this example requires the calling wallet to
+ hold the `system:network_writer` role. Contact the TRUF.NETWORK team to
+ obtain the role before executing the script.
  """
  # Generate unique stream IDs
  market_stream_id = generate_stream_id("market_performance")

go.mod

@@ -8,7 +8,7 @@ require (
 github.com/golang-sql/civil v0.0.0-20220223132316-b832511892a9
 github.com/kwilteam/kwil-db/core v0.4.2-0.20250506000241-da9d3ddea45e
 github.com/pkg/errors v0.9.1
-github.com/trufnetwork/sdk-go v0.3.1-0.20250605170548-90336b5849e0
+github.com/trufnetwork/sdk-go v0.3.2-0.20250611160829-e760d3bd55e1
 google.golang.org/genproto v0.0.0-20250324211829-b45e905df463
 )
 

go.sum

@@ -44,6 +44,10 @@ github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOf
 github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
 github.com/trufnetwork/sdk-go v0.3.1-0.20250605170548-90336b5849e0 h1:POu08dKYKli/SALB1btYO1WhqFEZNGhi29yIMb5d2NA=
 github.com/trufnetwork/sdk-go v0.3.1-0.20250605170548-90336b5849e0/go.mod h1:vcSgIR+ZRpkUJZ3DWaQVj0YSaPYkfcCPLd332Oo6RUM=
+github.com/trufnetwork/sdk-go v0.3.2-0.20250610130152-da8b60294d3f h1:NlLw5UykCxuxvPYgI/XTD1RintMDSfLZP5kUyp8KlMg=
+github.com/trufnetwork/sdk-go v0.3.2-0.20250610130152-da8b60294d3f/go.mod h1:vcSgIR+ZRpkUJZ3DWaQVj0YSaPYkfcCPLd332Oo6RUM=
+github.com/trufnetwork/sdk-go v0.3.2-0.20250611160829-e760d3bd55e1 h1:t1gmok1YGKI8WxQ3s/igQ7reRAmKQzUczx0p7Qe8JII=
+github.com/trufnetwork/sdk-go v0.3.2-0.20250611160829-e760d3bd55e1/go.mod h1:vcSgIR+ZRpkUJZ3DWaQVj0YSaPYkfcCPLd332Oo6RUM=
 go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
 go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
 go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0=

pyproject.toml

@@ -20,7 +20,8 @@ dev = [
  "pytest-mock>=3.14.0",
  "requests>=2.31.0",
  "pybindgen",
- "python-dotenv"
+ "python-dotenv",
+ "eth_account>=0.8.0"
 ]
 
 [project.urls]