| Name | farcaster-py JSON |
| Version |
0.1.6
JSON |
| download |
| home_page | None |
| Summary | Python bindings for Farcaster |
| upload_time | 2024-10-15 11:21:36 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# farcaster-py
Python bindings for [Farcaster](https://farcaster.xyz).
The bindings are based on the protocol implementation by [Hubble](https://thehubble.xyz) which can be found at [@farcaster/hub-monorepo](https://github.com/farcasterxyz/hub-monorepo/).
farcaster-py makes use of the gRPC interface exposed by farcaster hubs.
# Quick start
Until there is a proper pipy package, a quick and easy way to play around:
1. `pip install farcaster-py`
2. Create `.env` with the following entries:
```
FARCASTER_HUB="farcaster_hub:grpc_port"
OP_ETH_PROVIDER="OP provider endpoint"
APP_FID="application fid"
APP_PRIVATE_KEY="application private key"
USER_FID="User fid"
USER_PRIVATE_KEY="User private key"
APP_SIGNER_KEY="You have to create a signer first. Use examples/approve_new_signer.py."
```
3. Download the examples found in `examples/` and try `python ./get_user_casts.py`
# Internals
I have tried to both follow Farcaster's conventions and naming, but also provide a pythonic API that make sense to use without requiring deep knowledge of the underlying protocols.
## HubServce
The `HubService` class uses Hubble's gRPC interface to interact with hubs. Most of the gRPC described in [the protocol specification](https://github.com/farcasterxyz/protocol/blob/main/docs/SPECIFICATION.md) is avalable through farcaster-py.
Example:
```python
from farcaster.HubService import HubService
hub = HubService(hub_address, use_async=False)
casts = hub.GetCastsByFid(fid=280)
for cast in casts.messages:
print(cast)
```
- Secure connections have not been implemented.
- 99% of the gRPC API is read-only: You get data from the hubs. The only (I think) call that allows you to change the global state is `HubService.SubmitMessage(Message) -> Message`. (see next section)
## Message
The `Message.MessageBuilder` class offers three types of methods:
- The initializer that creates a new `MessageBuilder` with specific characteristics (hash scheme, signature scheme and the user's private key)
- Methods like `MessageBuilder.link.add(...)` and `Message.link.remove(...)` that return a `MessageData` protobuf.
- `MessageBuilder.message(self, data: MessageData)` that gets `MessageData` and hashes, signs, etc and returns a `Message` protobuf object ready to be used by `HubService.SubmitMessage(Message)`
Example:
```python
from farcaster.HubService import HubService
from farcaster.fcproto.message_pb2 import SignatureScheme, HashScheme, Embed
from farcaster import Message
hub_address = '....'
app_signer = '....'
user_fid = '....'
hub = HubService(hub_address, use_async=False)
message_builder = Message.MessageBuilder(
HashScheme.HASH_SCHEME_BLAKE3,
SignatureScheme.SIGNATURE_SCHEME_ED25519,
bytes.fromhex(app_signer[2:])
)
data = message_builder.cast.add(
fid = user_fid,
text = "Hello, world!"
)
msg = message_builder.message(data)
ret = hub.SubmitMessage(msg)
```
## Signer
The `Signer` class provides a simple interface to creating signers.
To create a signer, you need:
1. Fid and corresponding private key of the user that will approve the signer.
2. The fid and private key of the application that will create and use the signer.
Once you have this data, you create a new `Signer`, and use `approve_signer()` to submit the on-chain tx:
```python
# snippet from examples/approve_new_signer.py
s = Signer( op_eth_provider, user_fid, user_key, app_fid, app_key )
tx_hash = s.approve_signer()
signer_private_key = s.key
signer_public_key = s.signer_pub()
```
## Updating protobuf shemas
If you are installing from source, you use `generate_proto.sh <HUBBLE VERSION>`
to generate the corresponding protbuffer Python code.
```bash
./generate_proto.sh 1.5.6 git:main*
x schemas/
x schemas/gossip.proto
x schemas/hub_event.proto
x schemas/hub_state.proto
x schemas/job.proto
x schemas/message.proto
x schemas/onchain_event.proto
x schemas/request_response.proto
x schemas/rpc.proto
x schemas/sync_trie.proto
x schemas/username_proof.proto
Protobuf schemas parsed.
```
# Versioning
Eventually, farcaster-py will follow the version numbers of farcaster protocol buffers (when/if they become a separate package).
Until then, I'll keep version numbers low (0.0.x) and update them manually.
# License
`farcaster-py` is distributed under the [MIT License](LICENSE).
# Credits
This package was created and is maintained by [@vrypan.eth](https://warpcast.com/vrypan.eth).
An older repository, called [hub_py](https://github.com/mirceapasoi/hub_py) has been a valuable source while building the initial version of `farcaster-py`.
Raw data
{
"_id": null,
"home_page": null,
"name": "farcaster-py",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Panayotis Vryonis <vrypan@gmail.comm>",
"download_url": "https://files.pythonhosted.org/packages/4b/ec/32707b9c5946bf13fa824a2cf7d1cedeca807ff0dbb128a78a1b0df73c05/farcaster_py-0.1.6.tar.gz",
"platform": null,
"description": "# farcaster-py\nPython bindings for [Farcaster](https://farcaster.xyz).\n\nThe bindings are based on the protocol implementation by [Hubble](https://thehubble.xyz) which can be found at [@farcaster/hub-monorepo](https://github.com/farcasterxyz/hub-monorepo/).\n\nfarcaster-py makes use of the gRPC interface exposed by farcaster hubs.\n\n\n# Quick start\n\nUntil there is a proper pipy package, a quick and easy way to play around:\n\n1. `pip install farcaster-py`\n2. Create `.env` with the following entries:\n```\nFARCASTER_HUB=\"farcaster_hub:grpc_port\"\n\nOP_ETH_PROVIDER=\"OP provider endpoint\"\n\nAPP_FID=\"application fid\"\nAPP_PRIVATE_KEY=\"application private key\"\n\nUSER_FID=\"User fid\"\nUSER_PRIVATE_KEY=\"User private key\" \nAPP_SIGNER_KEY=\"You have to create a signer first. Use examples/approve_new_signer.py.\" \n```\n3. Download the examples found in `examples/` and try `python ./get_user_casts.py`\n\n# Internals\n\nI have tried to both follow Farcaster's conventions and naming, but also provide a pythonic API that make sense to use without requiring deep knowledge of the underlying protocols.\n\n## HubServce\nThe `HubService` class uses Hubble's gRPC interface to interact with hubs. Most of the gRPC described in [the protocol specification](https://github.com/farcasterxyz/protocol/blob/main/docs/SPECIFICATION.md) is avalable through farcaster-py.\n\nExample:\n\n```python\nfrom farcaster.HubService import HubService\nhub = HubService(hub_address, use_async=False)\ncasts = hub.GetCastsByFid(fid=280)\nfor cast in casts.messages:\n\tprint(cast)\n```\n\n- Secure connections have not been implemented.\n- 99% of the gRPC API is read-only: You get data from the hubs. The only (I think) call that allows you to change the global state is `HubService.SubmitMessage(Message) -> Message`. (see next section)\n\n## Message\n\nThe `Message.MessageBuilder` class offers three types of methods:\n- The initializer that creates a new `MessageBuilder` with specific characteristics (hash scheme, signature scheme and the user's private key)\n- Methods like `MessageBuilder.link.add(...)` and `Message.link.remove(...)` that return a `MessageData` protobuf.\n- `MessageBuilder.message(self, data: MessageData)` that gets `MessageData` and hashes, signs, etc and returns a `Message` protobuf object ready to be used by `HubService.SubmitMessage(Message)`\n\nExample:\n\n```python\nfrom farcaster.HubService import HubService\nfrom farcaster.fcproto.message_pb2 import SignatureScheme, HashScheme, Embed\nfrom farcaster import Message\n\nhub_address\t= '....'\napp_signer = '....'\nuser_fid = '....'\n\nhub = HubService(hub_address, use_async=False)\nmessage_builder = Message.MessageBuilder(\n\tHashScheme.HASH_SCHEME_BLAKE3, \n\tSignatureScheme.SIGNATURE_SCHEME_ED25519, \n\tbytes.fromhex(app_signer[2:])\n)\ndata = message_builder.cast.add(\n\tfid = user_fid, \n\ttext = \"Hello, world!\" \n\t)\nmsg = message_builder.message(data)\nret = hub.SubmitMessage(msg)\n```\n\n## Signer\nThe `Signer` class provides a simple interface to creating signers.\n\nTo create a signer, you need:\n1. Fid and corresponding private key of the user that will approve the signer.\n2. The fid and private key of the application that will create and use the signer.\n\nOnce you have this data, you create a new `Signer`, and use `approve_signer()` to submit the on-chain tx:\n```python\n# snippet from examples/approve_new_signer.py\ns = Signer( op_eth_provider, user_fid, user_key, app_fid, app_key )\ntx_hash = s.approve_signer()\nsigner_private_key = s.key\nsigner_public_key = s.signer_pub()\n```\n\n## Updating protobuf shemas\n\nIf you are installing from source, you use `generate_proto.sh <HUBBLE VERSION>`\nto generate the corresponding protbuffer Python code.\n\n\n```bash\n./generate_proto.sh 1.5.6 git:main*\nx schemas/\nx schemas/gossip.proto\nx schemas/hub_event.proto\nx schemas/hub_state.proto\nx schemas/job.proto\nx schemas/message.proto\nx schemas/onchain_event.proto\nx schemas/request_response.proto\nx schemas/rpc.proto\nx schemas/sync_trie.proto\nx schemas/username_proof.proto\n\nProtobuf schemas parsed.\n```\n\n# Versioning\n\nEventually, farcaster-py will follow the version numbers of farcaster protocol buffers (when/if they become a separate package).\n\nUntil then, I'll keep version numbers low (0.0.x) and update them manually.\n\n# License\n`farcaster-py` is distributed under the [MIT License](LICENSE).\n\n# Credits\n\nThis package was created and is maintained by [@vrypan.eth](https://warpcast.com/vrypan.eth).\n\nAn older repository, called [hub_py](https://github.com/mirceapasoi/hub_py) has been a valuable source while building the initial version of `farcaster-py`.\n",
"bugtrack_url": null,
"license": null,
"summary": "Python bindings for Farcaster",
"version": "0.1.6",
"project_urls": {
"Documentation": "https://github.com/vrypan/farcaster-py#readme",
"Issues": "https://github.com/vrypan/farcaster-py/issues",
"Source": "https://github.com/vrypan/farcaster-py"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9170d72cff8f8f8ab7cc0c3c03cd58a9e189334de143fcf39c0a6982ee1c91b5",
"md5": "82d9aaa47d1507835f93f89c6d4a9bf4",
"sha256": "abe7fb312741042707506885ad49d6cb8f70b6f5289dea5263f1301de33bccd7"
},
"downloads": -1,
"filename": "farcaster_py-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "82d9aaa47d1507835f93f89c6d4a9bf4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 59044,
"upload_time": "2024-10-15T11:21:37",
"upload_time_iso_8601": "2024-10-15T11:21:37.755006Z",
"url": "https://files.pythonhosted.org/packages/91/70/d72cff8f8f8ab7cc0c3c03cd58a9e189334de143fcf39c0a6982ee1c91b5/farcaster_py-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4bec32707b9c5946bf13fa824a2cf7d1cedeca807ff0dbb128a78a1b0df73c05",
"md5": "9cec613285ead9669f58ca97ccdce671",
"sha256": "1e38f30d7fb8e7c9de40bcc7f9d33cc2894b1bbd589c7851a375ed51377e6db4"
},
"downloads": -1,
"filename": "farcaster_py-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "9cec613285ead9669f58ca97ccdce671",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 46934,
"upload_time": "2024-10-15T11:21:36",
"upload_time_iso_8601": "2024-10-15T11:21:36.550150Z",
"url": "https://files.pythonhosted.org/packages/4b/ec/32707b9c5946bf13fa824a2cf7d1cedeca807ff0dbb128a78a1b0df73c05/farcaster_py-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-15 11:21:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vrypan",
"github_project": "farcaster-py#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "farcaster-py"
}
