From a1535d638c54e2b30cc7fe5e12e6a7efc9f86df8 Mon Sep 17 00:00:00 2001 From: Simon Shieh Date: Fri, 14 Feb 2025 12:57:52 +0800 Subject: [PATCH] init ATTPs Doc --- .DS_Store | Bin 0 -> 6148 bytes README.md | 5 + docs/.DS_Store | Bin 0 -> 10244 bytes docs/ATTPs/.DS_Store | Bin 0 -> 6148 bytes docs/ATTPs/README.md | 377 +++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 382 insertions(+) create mode 100644 .DS_Store create mode 100644 docs/.DS_Store create mode 100644 docs/ATTPs/.DS_Store create mode 100644 docs/ATTPs/README.md diff --git a/.DS_Store b/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..20c58c4e576851078e2e7d25944ea90574a12bf3 GIT binary patch literal 6148 zcmeHKO-~a+7=8z;-SQy|w2By$#$HSyi1LvbV^|7}HhzFDK?q>owo6&r&NRDQDiD&M z_2dum2YB*o;vewh)tk|OpjS`&&PSmwc;I3T**BSa-g)PJW_F(L>~sKtB&)@n06G9@ zSU85dusXqbKQG6uLq&Ke;bWv7R>(Unk8M6+V1WXG0{^!HeD8*!2n-6~we8>K+n zOf2FsFJJR2YM+0|R~*~($H%{rj?U1z^IYpqpRy4 z>YVnia++>3oN)&=Ua0UcZ`pD^#ABS5Rnv7%TC$S68;+T`oCTU>zR$`lc7aj(vIS9yFZm($OIy9e{+f_g(l}v=LHBmMEiEBw;MdKm<>h5txNXungO< z2XEjlyn~PM3BJM)_(j4*C)dabnIw0~47pF9kPIo1En*W_4$#r~k*~JSL_BOC{>VF7 zmpY7=Fvj!4@DS242Pt?ASxB|L`tLEL`PGj=1~X@29-lG=V^D@-D}(%MWAwBza=5+d zi9G(y%`>(0UVwQbkH5gpJZzrUlx$k}X^BC8pg^F&nOA^+AL3Xz8Vc(Y#is)+aRopO zVOSXY;;%nqoCgpMg>{J-K_iliD5*qUF^IZ35J|^=L*>^cN;(iRGmfKXChCSl)Ww6u zMLG~eVo(PP1PZh&&?%cbKmSv>hyQZ_ZzTn-K!HGkGo=6t&1dJ6xFmJ99$OqgYvWj+ tW8ud0>JkM7D|H+Thabg5ScG9;oI8ky!n#C^pap*fgbYCyDDY1e_yd3&2eAME literal 0 HcmV?d00001 diff --git a/README.md b/README.md index af426d9..e55b0b4 100644 --- a/README.md +++ b/README.md @@ -218,6 +218,11 @@ English/[简体中文](https://github.com/deepseek-ai/awesome-deepseek-integrati Upsonic Upsonic offers a cutting-edge enterprise-ready agent framework where you can orchestrate LLM calls, agents, and computer use to complete tasks cost-effectively. + + Icon + ATTPs + A foundation framework that enables advanced agent based on DeepSeek to interactions with each other, data verification, and data queries with [ATTPs Protocol](https://docs.apro.com/attps) . + ### RAG frameworks diff --git a/docs/.DS_Store b/docs/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..41280d0a6ede459d8b7451faa610faaccbfc2b77 GIT binary patch literal 10244 zcmeHM%Wm676uq=%iHaOU=z9}@MK@g}j@%>$l5S*2MPZ;QiYjOqeJG^F$b>0U5JkzZ z>%!~yANmQ+wqMX?mtFKDvg@Ki0r%WX+L{^J@vbO>8DV&bG7Pg?1Q_#sNYj(;ViX*jy=Lwvgc46(+Dqs~@R)F{JH)xBt>5zKr z{(Ub_`$3!rc+XSnIr8S2q{khU>p;iY>kpAV%4kMIgR!$SqwpxEUE31{YYR#>=4fmVwemd_? z{b`=<`jfBt?n#=)!FkyazKFtkuldH~G@1HQ5>A8=4MIS^{xV7i>3lcMlR+ljZt=pc zyY*i4o#W&C_a5B#?myT*x$PZ4{Gf&Mz3r2ey8GsPcR&2RcMy+~^haqkIpqRIH;em= z>rZ-*;^9`epN_^C@3sDp(oU!BuX`)_$NB#GZ>+bX-6$PggBb6>tcF>4lEi5;gja5H z1EV*S5u8#;n;6L%MKm%-i2G1R$)f?v?_w&m#i5XSS--{Z4;kMnR0QdmWI2ArKWAPK}ZChb<**0O;s89QXWDkcr8to?f zS&6mA1$ro_TRo}QWbrIfSTS~?qwmaKeU zj&@2Dy@kBeXy|H*<`^=tte1wZOHVkyGU-X*Y>NY>G)4_QPs;YsmUM+$8hV{R7ChI$ ztKS579{RVZ_kk7CcojripPtc?juT~mP?Tu^mqW!vWFChh`jb*_uvj6L^)}EWd^k=r zlxHaQq;0-L3;XFIvuBL7?oBjQy}f>^w`*pX=vsO?J3~xVCH`{E5}zWYMpjj=(FHa} z`(F}o8h(R5L0@8I58o5KYFs(%Md25U!Y+M!ZS<-5Rf(h6=mE!_imC&(IQf2tF}q}j zo-;(BnzVa}nBX{?8~#}#)qjCLLd$(#1$4ATn~L6m?+l;iHF0SMu|6x`D*C)75i~&z z^pv^8YxV)2WQb3W`l)DWw1a1^=BtWTKEk?{^9bo}=BU%KP54fs1&^gqcaVpulh>3x zs5vtG%<-o2Z-9SYj6zk7(*P&O$nm^c)Mu>etggnYq8|Q_BSbbvS=9VpQPagL&w34D zeOP1eiDD|g0=3w;;aAjBaaH;bIR4f|)EUaMGAb66(I%^aRlq7>6|f2@3al1ouL1kf z)&Ku13|q7cSOs1+1)NH!+u3S-Xe)6qys_P75m(To}U7sFN`HWBX pB;kFV3$Uk!MG5IY|1&^-qD$3w|Id3_bvJJJ|1Xps+$+2P{}<&5nH>NC literal 0 HcmV?d00001 diff --git a/docs/ATTPs/.DS_Store b/docs/ATTPs/.DS_Store new file mode 100644 index 0000000000000000000000000000000000000000..f60c37ef1b5464f1b6345faf24fbd96a41ee77a7 GIT binary patch literal 6148 zcmeHKF-`+P474FdP@0sK`vN3>utb-Ff`)tmg_J?5=&#Bvcnm)aGq#0@4jLpHG?why z^?Gh|Q=DTn^VRF_)@*5Jb2!nC3{&GdePS1taUdMec(AqI*o*D%_mk@H6XagmBY1Z< zeB~dWxBJ5ur~GMe@Xe_VYnc>~0#ZN_zq7;w$B+Hp2?9RK0cba_qGY{sd>uJDi4f oP!OUW1EU>d!*+ZfMOoLl#(6Is6N8R?(1H3hKwV@~;I9?<0H{M8rvLx| literal 0 HcmV?d00001 diff --git a/docs/ATTPs/README.md b/docs/ATTPs/README.md new file mode 100644 index 0000000..5180e8b --- /dev/null +++ b/docs/ATTPs/README.md @@ -0,0 +1,377 @@ + +# APRO-COM/ATTPs-framework + +Foundation framework that enables advanced agent based on DeepSeek interactions, data verification, and price queries with [ATTPs Protocol](https://docs.apro.com/attps) . It streamlines agent creation, verification processes, and provides a flexible framework for building robust agent-based solutions. + +For more details about ATTPs, you can see the [whitepaper here](https://www.apro.com/attps.pdf) + +## Overview + +The ATTPs framework bridges agent-based logic with the DeepSeek. It handles agent registration, data verification, and price queries, empowering both automated and user-driven workflows. + +## Features + +### Agent Operations +- **Agent Creation**: Deploy new agents with custom settings +- **Registration**: Register agents on-chain or via standardized processes +- **Multi-Signer Framework**: Supports threshold-based approval flows + +### Data Verification +- **Chain Validation**: Verify data authenticity on-chain +- **Transaction Execution**: Handle verification logic with built-in security checks +- **Auto-Hashing**: Convert raw data to hashed formats when needed +- **Metadata Parsing**: Validate content type, encoding, and compression + +### Price Queries +- **Live Price Data**: Fetch price information for various pairs +- **Format Validation**: Normalize user query inputs to standard trading-pair formats +- **APIs Integration**: Retrieve real-time or near-real-time pricing information + +## Security Features + +### Access Control +- **Private Key Management**: Safe usage of private keys for transaction signing +- **Environment Variables**: Secure injection of credentials +- **On-Chain Validation**: Leverage on-chain contract checks + +### Verification +- **Input Validation**: Strict schema checks before on-chain operations +- **Transaction Receipts**: Provide verifiable transaction details +- **Error Handling**: Detailed error logs for quick debugging + +## Performance Optimization + +1. **Cache Management** + - Implement caching for frequent queries + - Monitor retrieval times and cache hits + +2. **Network Efficiency** + - Batch requests where possible + - Validate response parsing to reduce overhead + +## System Requirements +- Node.js 16.x or higher +- Sufficient network access to on-chain endpoints +- Basic configuration of environment variables +- Minimum 4GB RAM recommended + +## Troubleshooting + +1. **Invalid Agent Settings** + - Ensure signers and threshold are correct + - Validate agentHeader for proper UUIDs and numeric values + +2. **Verification Failures** + - Check the input data formats + - Confirm environment variables are set + +3. **Price Query Errors** + - Verify the trading pair format + - Check external API availability + +## Safety & Security + +1. **Credential Management** + - Store private keys securely + - Do not commit secrets to version control + +2. **Transaction Limits** + - Configure thresholds to mitigate abuse + - Log transaction attempts and failures + +3. **Monitoring & Logging** + - Track unusual activity + - Maintain detailed audit logs + + +# Usage with js + +## Installation + +```bash +npm install ai-agent-sdk-js +``` + +## Configuration + +Configure the plugin by setting environment variables or runtime settings: +- APRO_RPC_URL +- APRO_PROXY_ADDRESS +- APRO_PRIVATE_KEY +- APRO_CONVERTER_ADDRESS +- APRO_AUTO_HASH_DATA + +## Usage with js sdk + +To use the AI Agent SDK, import the library and create an instance of the `Agent` class: + +```typescript +import { AgentSDK } from 'ai-agent-sdk-js' + +const agent = new AgentSDK({ + rpcUrl: 'https://bsc-testnet-rpc.publicnode.com', + privateKey: '', + proxyAddress: '', +}) + +// if you want the SDK to hash the data automatically +const autoHashAgent = new AgentSDK({ + rpcUrl: 'https://bsc-testnet-rpc.publicnode.com', + privateKey: '', + proxyAddress: '', + autoHashData: true, + converterAddress: '', +}) +``` + +To create a new agent, call the `createAndRegisterAgent` method: + +```typescript +import type { AgentSettings, TransactionOptions } from 'ai-agent-sdk-js' +import { randomUUID } from 'node:crypto' +import { parseUnits } from 'ethers' + +// prepare the agent settings +const agentSettings: AgentSettings = { + signers: [], + threshold: 3, + converterAddress: '', + agentHeader: { + messageId: randomUUID(), + sourceAgentId: randomUUID(), + sourceAgentName: 'AI Agent SDK JS', + targetAgentId: '', + timestamp: Math.floor(Date.now() / 1000), + messageType: 0, + priority: 1, + ttl: 3600, + }, +} + +// prepare the transaction options +const nonce = await agent.getNextNonce() +const transactionOptions: TransactionOptions = { + nonce, + gasPrice: parseUnits('1', 'gwei'), + gasLimit: BigInt(2000000), +} + +const tx = await agent.createAndRegisterAgent({ agentSettings, transactionOptions }) + +// or you can leave the transaction options empty, the SDK will use the auto-generated values +// const tx = await agent.createAndRegisterAgent({ agentSettings }) +``` + +The SDK also provides the tool to extract the new agent address from the transaction receipt: + +```typescript +import { parseNewAgentAddress } from 'ai-agent-sdk-js' + +const receipt = await tx.wait() +const agentAddress = parseNewAgentAddress(receipt) +``` + +To verify the data integrity, call the `verify` method: + +```typescript +import type { MessagePayload } from 'ai-agent-sdk-js' +import { hexlify, keccak256, toUtf8Bytes } from 'ethers' + +// prepare the payload +const data = hexlify(toUtf8Bytes('Hello World!')) +const dataHash = keccak256(data) +const payload: MessagePayload = { + data, + dataHash, + signatures: [ + { + r: '', + s: '', + v: 1, // 1, 0, 27, 28 are allowed + }, + // ... + ], + metadata: { + contentType: '', + encoding: '', + compression: '', + }, +} + +const tx = await agent.verify({ payload, agent: '', digest: '' }) +``` + +If the data is obtained from the APRO DATA pull service, you can use the auto-hash feature: + +```typescript +import type { MessagePayload } from 'ai-agent-sdk-js' + +const payload: MessagePayload = { + data: '0x...', + signatures: [ + { + r: '', + s: '', + v: 1, // 1, 0, 27, 28 are allowed + }, + // ... + ], + metadata: { + contentType: '', + encoding: '', + compression: '', + }, +} + +// When +const tx = await autoHashAgent.verify({ payload, agent: '', digest: '' }) +``` + +For more examples, see the [test](https://github.com/APRO-com/ai-agent-sdk-js/tree/main/test) cases. +``` + + +# Usage with Python + +## Installation +```bash +$ pip3 install ai-agent-sdk +``` + +## Usage + +### Initialize AgentSDK + +```python +from ai_agent.agent import AgentSDK + +AGENT_PROXY_ADDRESS = "0x07771A3026E60776deC8C1C61106FB9623521394" +NETWORK_RPC = "https://testnet-rpc.bitlayer.org" + +agent = AgentSDK(endpoint_uri=NETWORK_RPC, proxy_address=AGENT_PROXY_ADDRESS) +``` + +To create a new agent, call the createAndRegisterAgent method: + +```python +import time +from ai_agent.entities import ( + AgentSettings, + AgentHeader, + MessageType, + Priority +) +from ai_agent.utils import ( + generate_uuid_v4 +) + +AGENT_SETTINGS = AgentSettings( + signers=[ + "0x4b1056f504f32c678227b5Ae812936249c40AfBF", + "0xB973476e0cF88a3693014b99f230CEB5A01ac686", + "0x6cF0803D049a4e8DC01da726A5a212BCB9FAC1a1", + "0x9D46daa26342e9E9e586A6AdCEDaD667f985567B", + "0x33AF673aBcE193E20Ee94D6fBEb30fEf0cA7015b", + "0x868D2dE4a0378450BC62A7596463b30Dc4e3897E", + "0xD4E157c36E7299bB40800e4aE7909DDcA8097f67", + "0xA3866A07ABEf3fD0643BD7e1c32600520F465ca8", + "0x62f642Ae0Ed7F12Bc40F2a9Bf82ccD0a3F3b7531" + ], + threshold=2, + converter_address="0xaB303EF87774D9D259d1098E9aA4dD6c07F69240", + agent_header=AgentHeader( + version="1.0", + message_id="d4d0813f-ceb7-4ce1-8988-12899b26c4b6", + source_agent_id="da70f6b3-e580-470f-b88b-caa5369e7778", + source_agent_name="APRO Pull Mode Agent", + target_agent_id="", + timestamp=int(time.time()), + message_type=MessageType.Event, + priority=Priority.Low, + ttl=60 * 60 + ) +) + +dynamic_setting = AGENT_SETTINGS +dynamic_setting.agent_header.source_agent_id = generate_uuid_v4() +dynamic_setting.agent_header.target_agent_id = generate_uuid_v4() +dynamic_setting.agent_header.message_id = generate_uuid_v4() +user_owner = agent.add_account("0x_user_private_key") +result = agent.create_and_register_agent( + transmitter="", + nonce=None, + settings=AGENT_SETTINGS) +print("created agent:", result) + +``` +To verify the data integrity, call the verify method: + +```python +from ai_agent.entities import ( + AgentMessagePayload, + Proofs, + AgentMetadata, +) + +AGENT_CONTRACT = "0xA1903361Ee8Ec35acC7c8951b4008dbE8D12C155" +AGENT_SETTING_DIGEST = "0x010038164dba6abffb84eb5cb538850d9bc5d8f815149a371069b3255fd177a4" +AGENT_PAYLOAD = AgentMessagePayload( + data="0x0006e706cf7ab41fa599311eb3de68be869198ce62aef1cd079475ca50e5b3f60000000000000000000000000000000000000000000000000000000002b1bf0e000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000e0000000000000000000000000000000000000000000000000000000000000022000000000000000000000000000000000000000000000000000000000000002a0000101000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001200003665949c883f9e0f6f002eac32e00bd59dfe6c34e92a91c37d6a8322d6489000000000000000000000000000000000000000000000000000000006762677d000000000000000000000000000000000000000000000000000000006762677d000000000000000000000000000000000000000000000000000003128629ec0800000000000000000000000000000000000000000000000004db732547630000000000000000000000000000000000000000000000000000000000006763b8fd0000000000000000000000000000000000000000000015f0f60671beb95cc0000000000000000000000000000000000000000000000015f083baa654a7b900000000000000000000000000000000000000000000000015f103ec7cb057ea80000000000000000000000000000000000000000000000000000000000000000003b64f7e72208147bb898e8b215d0997967bef0219263726c76995d8a19107d6ba5306a176474f9ccdb1bc5841f97e0592013e404e15b0de0839b81d0efb26179f222e0191269a8560ebd9096707d225bc606d61466b85d8568d7620a3b59a73e800000000000000000000000000000000000000000000000000000000000000037cae0f05c1bf8353eb5db27635f02b40a534d4192099de445764891198231c597a303cd15f302dafbb1263eb6e8e19cbacea985c66c6fed3231fd84a84ebe0276f69f481fe7808c339a04ceb905bb49980846c8ceb89a27b1c09713cb356f773", + data_hash="0x53d9f133f1265bd4391fcdf89b63424cbcfd316c8448f76cc515647267ac0a8e", + proofs=Proofs( + zk_proof="0x", + merkle_proof="0x", + signature_proof="0x000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000e000000000000000000000000000000000000000000000000000000000000001600000000000000000000000000000000000000000000000000000000000000003b64f7e72208147bb898e8b215d0997967bef0219263726c76995d8a19107d6ba5306a176474f9ccdb1bc5841f97e0592013e404e15b0de0839b81d0efb26179f222e0191269a8560ebd9096707d225bc606d61466b85d8568d7620a3b59a73e800000000000000000000000000000000000000000000000000000000000000037cae0f05c1bf8353eb5db27635f02b40a534d4192099de445764891198231c597a303cd15f302dafbb1263eb6e8e19cbacea985c66c6fed3231fd84a84ebe0276f69f481fe7808c339a04ceb905bb49980846c8ceb89a27b1c09713cb356f7730000000000000000000000000000000000000000000000000000000000000003000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000001", + ), + meta_data=AgentMetadata( + content_type="0x", + encoding="0x", + compression="0x" + ) +) +user_owner = agent.add_account("0x_user_private_key") +result = agent.verify( + transmitter=user_owner, + nonce=None, + agent_contract=AGENT_CONTRACT, + settings_digest=AGENT_SETTING_DIGEST, + payload=AGENT_PAYLOAD +) +print("verify:", result) +``` +For more examples, see the [test cases](https://github.com/APRO-com/ai-agent-sdk-python/tree/main/tests). + + +# Other SDKs + +JAVA: https://github.com/APRO-com/ai-agent-sdk-java + +RUST: https://github.com/APRO-com/ai-agent-sdk-rust + +GOLANG: https://github.com/APRO-com/ai-agent-sdk-go + +# Support + +For issues or feature requests: +1. Check existing documentation +2. Submit a GitHub issue with relevant details +3. Include transaction logs and system info if applicable + +# Contributing + +We welcome pull requests! Refer to the project’s CONTRIBUTING.md and open discussions to coordinate efforts. + +# Credits + +- [APRO](https://www.apro.com/) - Plugin sponsor and partner +- [ai-agent-sdk-js](https://github.com/APRO-com/ai-agent-sdk-js) - Underlying agent SDK +- [ethers.js](https://docs.ethers.io/) - Transaction and contract interaction +- Community contributors for feedback and testing + +For more information about Apro plugin capabilities: + +- [Apro Documentation](https://docs.apro.com/en) + +# License + +This plugin is part of the Eliza project. Refer to the main project repository for licensing details. \ No newline at end of file